지난 글에서는 AI 코딩이 복잡해질수록 흔들리는 이유를 살펴봤습니다. 더 좋은 모델을 사용하거나 프롬프트를 자세히 작성해도 작업 방식이 그대로라면 같은 문제가 반복될 수 있습니다.

AI가 "다 했어요"라고 보고했지만 실제로는 오류가 발생하고, 새 세션을 열 때마다 프로젝트를 처음부터 설명해야 합니다. 새로운 기능을 추가하다 기존 코드가 깨지는 일도 생깁니다.

그렇다면 AI에게 어떤 순서로 일을 맡기고, 무엇을 완료의 기준으로 삼아야 할까요? 이 글에서는 4단계 워크플로부터 CLAUDE.md를 활용한 맥락 관리, 작업 분할, 결과 검증까지 살펴봅니다.

모델을 바꾸거나 프롬프트를 늘리는 것만으로는 복잡한 프로젝트가 끝까지 완성되지 않습니다. 결과물의 품질은 모델 성능만이 아니라 작업 방식, 검증 구조, 맥락 품질이 함께 정하기 때문입니다.

그렇다면 AI에게 어떤 순서로 일을 맡기고, 무엇을 완료의 기준으로 삼아야 할까요? 이 글에서는 4단계 워크플로, CLAUDE.md와 작업 분할, 테스트 루프, 세션 운영을 차례로 살펴봅니다.

Q. 채팅창 대신 어떤 순서로 일을 맡겨야 할까요?

채팅창이 아니라 파일 위에서 생각을 먼저 끝내고 타이핑은 나중에 맡기는 순서로 일해야 합니다. 책『에이전틱 코딩 완성의 기술』 4장에서는 이를 '생각'과 '타이핑'을 분리하라는 단 하나의 원칙으로 정리하고, 리서치·계획·주석 달기·구현의 4단계 워크플로로 풀어줍니다.

1) 채팅창은 흐름일 뿐 자산이 아닙니다.

채팅창의 본질은 ‘흐름’입니다. 메시지가 위에서 아래로 흘러가고, 새 메시지가 들어오면 오래된 메시지는 밀려나고, 화면 밖으로 사라지며, 결국 잊히게 됩니다. 그런데 코딩 작업에서 이 ‘흐름’은 치명적입니다. 코딩에서 정말 중요한 것은 마지막 메시지가 아니라 채팅 내내 합의된 결정들이기 때문이죠.

대화가 길어지면 묻히므로, 중요한 결정은 파일로 옮겨야 합니다. "우리는 PUT이 아니라 PATCH로 가기로 했다" 같은 결정이 50번째 메시지에 묻히면, AI는 100번째 메시지에서 그 결정을 잊습니다. 이를 해결하는 가장 단순한 방법은 흐름을 자산으로 바꾸는 일입니다. 흐름은 채팅창이고, 자산은 파일입니다.

클로드 코드의 내장 플랜 모드를 쓰면 안 되느냐는 질문도 많습니다. 하지만 편집의 자유도, 영속성, 공유 가능성 세 가지 이유로 내장 플랜 모드만으로는 충분하지 않습니다. 세션은 흐름이고, 파일은 자산입니다. 플랜 모드는 흐름 위의 계획이고, PLAN.md는 자산으로서의 계획입니다.

2) 단 하나의 원칙: ‘생각’과 ‘타이핑’을 분리하세요.

4단계 워크플로는 ①리서치, ②구현 계획, ③주석 달기 사이클, ④구현의 순서로 진행합니다. 결론을 먼저 말하자면, “작성한 계획을 내가 직접 검토하고 승인하기 전까지, AI에게 코드를 절대 쓰게 하지 마라.” 입니다.

➀ 리서치 (research.md)

AI에게 코드베이스를 깊이 읽게 하고 그 결과를 research.md에 기록하게 합니다. AI에게 코드베이스를 깊이 읽게 하고 그 결과를 research.md에 기록하게 합니다. 간단한 스크립트나 새 프로젝트에서는 리서치를 생략할 수 있지만, 기존 코드베이스에 새 기능을 추가하거나 중요한 기능을 수정할 때는 리서치부터 시작하는 것이 좋습니다.

②구현 계획 작성(PLAN.md)

계획도 채팅창이 아니라 PLAN.md라는 별도 파일에 적게 합니다. AI가 만든 PLAN.md는 완성품이 아니라 초안입니다.

③주석 달기 사이클 (PLAN.md annotate)

사람이 PLAN.md에 직접 메모를 달고 AI에게 반영하게 하는 과정을, 만족할 때까지 반복합니다.

④구현 (start coding)

모든 결정이 끝난 뒤에 구현을 시킵니다. 구현 단계는 지루해야 합니다.

이 워크플로 전체의 핵심은 ‘운전대를 누가 잡고 있느냐’입니다. 이는 "‘LLM에게 실행은 맡기지만, 뭘 만들지에 대한 결정권은 절대 넘기지 않는다’"라는 한 문장으로 요약할 수 있습니다.

이것이 카파시가 말한 “사람은 spec을 잡고, 에이전트가 그 안을 채우게 한다”의 가장 작은 실천 형태입니다. OpenAI의 “Humans steer. Agents execute.”가 한 사람의 책상 위에서 어떻게 구현되는지를 보여 주는 그림이기도 합니다. 운전대는 사람의 손에 있어야 합니다. AI에게 핸들을 넘기는 순간, 차는 빨라지고 운전도 잘할 수는 있겠지만 ‘어디로 갈지’는 알 수 없게 됩니다. 적어도 정확한 내비게이션을 지정해 주는 역할은 필요합니다.

Q. CLAUDE.md와 작업 분할로 어떻게 맥락을 지킬까요?

맥락은 채팅이 아니라 프로젝트 루트의 CLAUDE.md(AGENTS.md)에 적어 두고, 작업은 검증할 수 있는 단위로 쪼개 하나씩 끝내야 지켜집니다. 책 5장은 이 두 가지를 프로젝트의 작업 환경과 작업 단위 설계로 다룹니다.

1) CLAUDE.md는 백과사전이 아니라 지도입니다.

CLAUDE.md는 모든 정보를 담는 곳이 아니라 정보가 어디 있는지 알려 주는 지도여야 합니다. 새 세션을 열 때마다 같은 말을 반복하게 되는 이유는 AI가 잊은 것이 아닙니다. 그 말이 적힌 곳이 사라진 것입니다.

SaaStr의 Replit DB 삭제 사고도 "프로덕션 DB는 건드리지 마"라는 약속이 채팅 로그 어딘가에만 적혀 있었기 때문에 새 세션에서 깨진 것일 수도 있습니다.

지도에는 프로젝트 간단 설명, 코드 컨벤션, 도메인 규칙, 금지 사항, 자주 쓰는 명령어, 더 자세한 문서의 위치를 담아야 합니다. 반대로 일회용 정보, 사람만 읽는 메타 정보, 너무 자세한 코드 예시, 변하기 쉬운 정보, 코드를 보면 알 수 있는 것은 담지 않는 것이 좋습니다.

운영 방법도 단순합니다. AI가 같은 실수를 두 번 했다면, 그 실수를 막을 규칙을 클로드

코드에서는 CLAUDE.md, 코덱스 등에서는 AGENTS.md와 같은 프로젝트 지시 파일에 한 줄 추가하는 형태면 됩니다. 하네스 5가지 원리 중 ‘실수는 시스템에 반영된다'를 가장 단순하게 실천하는 방법입니다.

2) 작업은 검증할 수 있는 단위로 쪼개고 한 번에 하나만 시킵니다.

작업 분할의 기본 방법은 작업을 검증할 수 있는 단위로 쪼개는 것이고, 그 아래에는 공통 기반이 있어야 합니다. 기초 공사 없이 작업을 쪼개봤자 모래성이니까요. 그래서 작업 단위를 잘 쪼개는 능력의 절반은 그 작업들이 따를 공통 기반을 잘 만드는 능력입니다.

이때 책에서는 작업을 나누는 기준으로 세 가지를 제시합니다. 첫째, 작업이 끝났을 때 성공과 실패를 명확하게 판단할 수 있는 검증 가능성. 둘째, 다른 작업에 영향을 최소화하는 독립성. 셋째, 한 세션 안에서 끝낼 수 있는 적절한 크기입니다.

이 기준에 따라 작업을 나누고 하나씩 검증하면 문제가 발생했을 때 원인을 찾거나 이전 상태로 되돌리기도 쉬워집니다.

Q. AI의 '다 했어요'를 믿어도 될까요?

AI의 '다 했어요'는 그 자체로는 믿을 신호가 아니며, 테스트와 검증 장치를 통과해야 완료가 됩니다.

완료는 감각이 아니라 신호입니다.

AI가 끝났다고 말해도 그것을 완료로 받아들이는 기준은 사람의 감각이 아니라 신호여야 합니다. 경험 많은 개발자는 "이건 뭔가 불안한데?"라는 감각으로 완성도를 느낍니다. 그러나 AI에게 ‘완성’은 감각이 될 수 없습니다. AI에게 완성은 ‘신호’입니다. 테스트 통과, 타입 체크 통과, 린트 통과, E2E 시나리오 성공, 보안 스캔 통과 같은 신호가 있어야 AI가 올바른 방향으로 가는지 알 수 있습니다.

하네스의 다섯 가지 원리 중 하나는 '완료는 합의가 아니라 검증된 신호다'입니다. 계획서의 모든 항목을 구현하고 완료 표시를 남기는 것은 시작일 뿐입니다. 타입 체크, 테스트, 빌드 등 실제 검증을 통과했다는 증거가 있어야 결과물을 신뢰할 수 있습니다.

구현 단계에서는 계획서의 모든 항목이 코드로 옮겨졌는지 확인하고 완료 표시를 남깁니다. 하지만 이것만으로 소프트웨어의 품질이 보장되지는 않습니다. 타입 체크, 테스트, 빌드 등 실제 검증을 통과했다는 증거가 있어야 결과물을 신뢰할 수 있습니다.

AI가 만든 코드가 실행되고 기본 기능이 작동한다고 해서 완성된 것은 아닙니다. 예외 상황에서도 정상적으로 동작하는지, 실제 운영 환경에서 문제가 없는지, 시간이 지나도 안정적으로 유지되는지까지 확인해야 합니다.

이를 해결하려면 AI에게 코딩을 맡기는 것만으로는 부족합니다. 작업을 계획하고, 프로젝트의 맥락을 기록하며, 결과를 테스트하고 검증하는 체계가 필요합니다.

결국 에이전틱 코딩의 핵심은 AI가 코드를 얼마나 빠르게 작성하느냐가 아니라, 그 결과물을 얼마나 안정적으로 완성하고 발전시킬 수 있느냐에 있습니다.

위 컨텐츠는 『에이전틱 코딩 완성의 기술』 내용을 기반으로 작성하였습니다.

댓글

관련 콘텐츠