Claude Code / Codex 시대의 개발 플로우──Plan, Work, Review, Compound로 AI를 공정에 포함시키기 제0회

이 기사는 「AI 에이전트를 공정에 포함시키기」 시리즈의 제0회입니다.

Claude Code, Codex, Cursor, Gemini CLI와 같은 coding agent를 단순한 코드 생성 도구가 아니라, 개발 공정에組み込む(組み込む, 포함시키기) 위한 사고방식을 정리합니다.

이 기사의 예상 독자는 Claude Code, Codex, Cursor, Gemini CLI 등을 사용하여 기존 리포지토리(repository) 조사, 구현, 테스트, PR 리뷰, 장애 조사를 진행하고 있는 엔지니어입니다.

일반적인 「AI 활용술」이 아니라, 개발 공정에 관한 이야기를 합니다. 프롬프트(prompt)의 잔기술보다는 사양(specification), 변경 범위, 테스트, review, eval, sandbox, AGENTS.md / CLAUDE.md에 관심이 있는 분들을 위한 글입니다.

Claude Code나 Codex를 접하면 처음에는 상당히 놀라게 됩니다.

자연어로 요청하면 파일을 읽고, 코드를 쓰고, 테스트를 실행하고, 에러를 보고 수정합니다. 이전에는 반나절이 걸렸을 작업이 몇 분 만에 형태를 갖추기도 합니다.

하지만 잠시 사용하다 보면 다른 문제에 부딪힙니다.

빠릅니다. 확실히 빠릅니다. 하지만 방향을 틀리면 빠르게 틀립니다. 테스트가 부실한 채로 「완료했습니다」라고 말합니다. 기존 설계를 간과합니다. 작은 수정일 뿐인데 관계없는 파일까지 건드립니다. 리뷰해 보면 겉모습은 정돈되어 있는데, 핵심적인 전제가 어긋나 있습니다.

여기서 많은 사람은 이렇게 생각합니다.

「역시 AI는 아직 신뢰할 수 없어」

절반은 맞습니다. 아무 생각 없이 맡긴다면 신뢰하지 않는 편이 좋습니다.

하지만 나머지 절반은 틀렸습니다. 문제는 AI를 사용할 수 없다는 것이 아닙니다. AI에게 일을 넘기는 공정이 없다는 것입니다.

사람에게 일을 부탁할 때도 마찬가지입니다. 갑자기 「알아서 잘 전부 해줘」라고 말하면, 상대가 우수하더라도 사고가 발생합니다. 목적, 제약, 판단 기준, 확인 방법, 실패했을 때의 복구 방법이 필요합니다.

AI 에이전트(AI agent)도 마찬가지입니다.

다른 점은, AI 에이전트는 인간보다 훨씬 빠르게 움직인다는 것입니다. 그래서 공정이 약하면 실패도 빠르게 확산됩니다. 반대로 공정이 강하면, 속도가 그대로 무기가 됩니다.

이 기사에서는 그 공정을 4가지로 나눕니다.

Plan 만들게 하기 전에, 일을 설계한다
Work 작게 만들게 하고, 실행 결과를 보면서 진행한다
Review 나온 결과물을, 인간과 별도의 메커니즘으로 검품한다
...

이 4가지는 CLAUDE.md / AGENTS.md / evals / sandbox와 같은 실무 부품들과 매우 깔끔하게 연결됩니다.

이 기사의 목적은 Claude Code와 Codex의 비교가 아닙니다.

어느 쪽이 더 강력한지는 모델이나 시기에 따라 달라집니다. 중요한 것은 어떤 에이전트를 사용하더라도 무너지지 않는 업무 흐름을 만드는 것입니다.

가장 먼저 버려야 할 사고방식이 있습니다.

그것은 AI 에이전트를 「코드를 써주는 사람」으로만 보는 것입니다.

물론 코드는 쓸 수 있습니다. 오히려 그 부분이 눈에 띄기 때문에, 처음에는 누구나 「쓰게 만드는 것」에 의식이 집중됩니다.

하지만 실무에서 가치가 나오는 것은 코드를 쓰는 순간만이 아닙니다.

• 무엇을 만들어야 할지 결정한다
• 기존 코드를 읽는다
• 변경 범위를 좁힌다
• 사양의 모호함을 찾아낸다
• 테스트 관점을 도출한다
• 구현한다
• 에러를 읽고 수정한다
• diff를 설명한다
• 리뷰에서 논점을 압축한다
• 실패를 다음 규칙으로 바꾼다

이 전체가 업무입니다.

AI 에이전트를 사용한다는 것은 이 중 어느 하나를 통째로 떠넘기는 이야기가 아닙니다. 업무 전체의 흐름을 재구성하는 이야기입니다.

이 부분을 틀리면 「AI에게 전부 맡긴다」 또는 「AI는 신뢰할 수 없다」라는 이지선다에 빠지게 됩니다. 둘 다 조잡한 방식입니다.

실무에서는 훨씬 더 수수한 방식이 됩니다.

만들게 하기 전에 조사하게 한다.

큰 변경을 작게 나눈다.

실행 결과를 보면서 진행한다.

다른 관점에서 리뷰하게 한다.

성공한 절차를 남긴다.

실패한 패턴을 다음 규칙으로 만든다.

이 수수한 축적이 AI 에이전트를 「편리한 일회성 재주」에서 「업무의 일부」로 변화시킵니다.

먼저 전체상을 제시합니다.

이 흐름의 포인트는 마지막이 「완료(Completion)」가 아니라 「Compound」로 되어 있다는 점입니다.

보통의 개발에서는 태스크(task)가 끝나면 거기서 끝나는 경우가 많습니다.

하지만 AI 에이전트를 사용하면 같은 종류의 실패가 몇 번이고 일어납니다.

• 매번 테스트를 쓰는 것을 잊어버린다
• 매번 기존의 명명 규칙(naming convention)을 벗어난다
• 매번 UI 문구가 약간 딱딱하다
• 매번 DB migration의 영향 범위를 간과한다
• 매번 타입은 통과하지만 사양과 다르다
• 매번 README 업데이트를 잊는다

이러한 「매번」을 방치하면, 인간이 매번 똑같은 주의를 기울여야 합니다. AI를 사용하고 있음에도 불구하고, 인간의 리뷰 부하만 늘어납니다.

Compound는 이 지점을 바꾸는 사고방식입니다.

한 번 일어난 실패를 다음 입력으로 되돌린다.

한 번 성공했던 절차를 재사용할 수 있는 형태로 만든다.

한 번 만든 판단 기준을 AGENTS.md, 체크리스트, 테스트, eval, skill, subagent, prompt template에 녹여낸다.

이것이 가능해지면, 한 번의 작업이 다음 작업을 조금 더 수월하게 만듭니다.

하나하나의 업무가 다음 업무를 쉽게 만든다. Compound의 사고방식은 바로 여기에 있습니다.

AI 에이전트 (AI Agent)에서 가장 큰 차이가 나는 지점은 구현 전입니다.

코드를 작성하게 하기 전에, 얼마나 일을 작고 검증 가능한 형태로 나눌 수 있는가. 여기서 거의 결정됩니다.

에이전트 (agent)에게 전달할 사양은 상당히 실무적으로 생각하는 것이 좋습니다. 거대한 사양을 한꺼번에 던지는 것이 아니라, AI가 헤매지 않을 정도의 정보만 전달합니다. 큰 일은 작게 나눕니다. 처음에는 read-only mode로 계획만 세우게 합니다. 구조, 스타일, 테스트, 경계를 명확히 합니다.

이것은 평소의 사용 방식에 그대로 적용할 수 있습니다.

첫 요청에서 갑자기 다음과 같이 쓰는 것은 좋지 않습니다.

검색 기능을 추가해 주세요.

이렇게 하면 AI는 부족한 부분을 알아서 채웁니다. 검색 대상, UI, 상태 관리 (state management), API, 테스트 범위, 기존 설계와의 관계를 상당 부분 추측합니다. 추측이 맞으면 빠르지만, 틀리면 뒷수습이 무거워집니다.

처음에는 다음과 같이 부탁하는 것이 안정적입니다.

아직 구현하지 마세요.
이 리포지토리 (repository)를 읽고, 검색 기능을 추가할 경우
어떤 파일을 확인해야 하는지, 어떤 설계에 맞춰야 하는지,
...

여기서 중요한 것은 「작업」이 아니라 「관찰」을 부탁하고 있다는 점입니다.

AI 에이전트는 부탁하면 바로 만들기 시작합니다. 그래서 인간 측에서 제어해야 합니다. 먼저 읽는다. 그다음 계획한다. 마지막으로 작게 만든다.

Plan 단계에서는 적어도 다음을 결정합니다.

항목	결정할 것
목적	무엇이 되면 완료인가
...

「비목적 (Non-objective)」은 특히 효과적입니다.

AI는 친절하기 때문에 무심코 주변부까지 수정하곤 합니다. 작은 UI 수정만 의도했는데, 컴포넌트 (component) 구조까지 정리하기 시작할 때가 있습니다. 악의는 없습니다. 하지만 실무에서는 곤란합니다.

그래서 하지 말아야 할 것을 명시합니다.

이번에는 검색창 추가만 다룹니다.
API 사양 변경, DB schema 변경, 디자인 시스템 업데이트는 하지 마세요.
필요해 보이더라도 제안에 그쳐주세요.

이 한 문장만으로도 사고는 상당히 줄어듭니다.

Plan이 안정되지 않는 원인 중 하나는 전제가 매번 사라진다는 점입니다.

어제 리뷰에서 결정한 명명 규칙 (naming convention). 지난주 장애 조사에서 파악한 위험한 의존 관계. 팀에서 피하기로 한 구현 패턴. 지난 작업에서 「다음부터는 반드시 확인하자」고 결정한 테스트 관점.

인간이라면 이런 것들을 어렴풋이 기억하고 있습니다. 하지만 에이전트 (agent)의 세션은 기본적으로 매번 리셋됩니다. AGENTS.md나 CLAUDE.md에 적혀 있지 않은 것, 프로젝트 메모리 (project memory)에 남아 있지 않은 것, 수중에 있는 체크리스트에 들어 있지 않은 것은 다음 Plan으로 돌아오지 않습니다.

여기서 메모리 레이어 (memory layer)가 등장합니다.

예를 들어 GPS, Walrus Memory, Minimi와 같은 도구들을 「AI에게 무엇이든 기억시키기 위한 기억 도구」로만 본다면 조금 얕은 접근입니다. Plan의 문맥에서 그 역할은 훨씬 구체적입니다.

과거의 판단을 다음 Plan으로 되돌리기 위한 부품입니다.

repo rules, past lessons, 자주 발생하는 실수, 리뷰에서 매번 수정하는 점을 다음 작업의 입구로 되돌릴 수 있는가. 이 부분이 핵심입니다.

따라서 이런 도구들을 평가할 때도 「기억할 수 있습니까」만으로는 부족합니다.

• 오래된 기억을 어떻게 버리는가
• 잘못된 기억을 어떻게 수정하는가
• 리포지토리 단위로 규칙을 나눌 수 있는가
• 에이전트가 Plan을 만들기 전에 그 문맥을 자연스럽게 읽을 수 있는가
• 인간이 확인하지 않은 채 위험한 규칙이 섞이지 않는가

이런 점들을 살펴봅니다.

Plan의 정밀도는 프롬프트 (prompt)의 문장력만으로 결정되지 않습니다. Plan 이전에 어떤 전제가 돌아오느냐에 따라 결정됩니다.

Plan 단계에서 원하는 것은 거창한 설계서가 아닙니다.

「이 작업은 어디를 건드리면 되고, 어디가 위험한가」를 알 수 있는 메모입니다.

예를 들어, 다음과 같은 출력이라면 충분합니다.

구현 방침:
1. ProductList.tsx に 검색 입력을 추가한다
2. 기존의 category filter 와 동일한 state 관리 방식에 맞춘다
...

이 정도라면 인간이 판단할 수 있습니다.

여기서 「sku 는 대상 외」「표기 불일치(表記ゆれ)는 이번에 불필요」라고 답하면, Work 단계로 넘어갈 수 있습니다.

Plan 이 통과되면, Work 에 들어갑니다.

Work 에서 중요한 것은, 작게 만들게 하는 것입니다.

AI 에이전트 (AI Agent)는 긴 태스크 (Task)도 수행할 수 있습니다. 다만, 태스크가 길어질수록 중간의 판단이 늘어납니다. 판단이 늘어나면, 멋대로 보완하는 부분도 늘어납니다.

그래서 처음에는 다음과 같이 나눕니다.

방침은 OK입니다.
먼저 ProductList.tsx 와 filterProducts() 만 변경해 주세요.
테스트는 아직 추가하지 마세요.
...

한꺼번에 전부가 아니라, 얇게 한 걸음씩 나아가는 것입니다.

그 후에 테스트를 추가합니다.

다음으로 ProductList.test.tsx に 테스트를 추가해 주세요.
필요한 케이스:
- 빈 문자열이라면 전체 표시
...

여기서, 실행하고 실패를 보면서 고쳐나가는 사고방식이 효과를 발휘합니다.

AI에게 「써서 끝내기」를 시키지 마세요. 실행합니다. 실패를 봅니다. 원인을 읽습니다. 수정합니다. 다시 실행합니다.

이 루프 (Loop)가 있는 것만으로도, AI의 출력물은 상당히 업무에 가까워집니다.

중요한 것은, 실패했을 때 바로 수정하게 하는 것뿐만 아니라, 원인을 설명하게 하는 것입니다.

테스트가 실패했을 경우에는 바로 수정하지 말고,
먼저 실패 원인을 한 단락으로 설명해 주세요.
그 후에 최소한의 수정안을 제시해 주세요.

이렇게 하면, AI가 임기응변식으로 수정하는 것을 어렵게 만들 수 있습니다.

Work 에 들어가면, 문제는 프롬프트 (Prompt)가 아니라 실행 환경 (Execution Environment)이 됩니다.

에이전트 (Agent)에게 테스트를 실행하게 합니다. 빌드 (Build)하게 합니다. 로컬 서버 (Local Server)를 띄우게 합니다. 로그 (Log)를 읽게 합니다. 여기까지는 자연스럽습니다.

다만, 로컬 PC에서 자유롭게 명령어를 입력하게 하면, 에이전트는 자신의 작업 환경에 너무 가깝게 접근하게 됩니다. 파일, 환경 변수 (Environment Variable), 인증 정보 (Credential), SSH 키, 브라우저 로그인 상태, 사내 네트워크. 인간이 평소에 별로 의식하지 않는 것들에 에이전트가 접촉할 가능성이 있습니다.

여기서 샌드박스 (Sandbox)나 원격 실행 환경 (Remote Execution Environment)이 등장합니다.

Boxes.dev 나 AppWizzy 같은 도구들은 「Claude Code / Codex 를 더 편리하게 사용하기」 위한 것만이 아닙니다. Work 단계에서 에이전트를 어디서 구동할지를 분리하기 위한 부품입니다.

자신의 작업용 기기에서 구동할 것인가.

일시적인 VM (Virtual Machine)에서 구동할 것인가.

클라우드 상의 격리된 환경에서 구동할 것인가.

네트워크를 차단한 환경에서 구동할 것인가.

Secrets 를 애초에 넣지 않는 환경에서 구동할 것인가.

이 설계를 하지 않은 채 에이전트의 실행 권한을 넓히면, 편리함과 같은 속도로 사고의 반경도 넓어집니다.

DotBGE 같은 로컬 우선 암호화 (Local-first Encryption) 계열의 도구도 이 맥락에서 보면 이해하기 쉽습니다. 에이전트가 파일에 접근한다면, 어떤 파일을 보여줄 것인지, 어떤 데이터는 암호화해 둘 것인지, 어디까지 로컬에 한정할 것인지가 문제가 됩니다.

Work 단계에서 던져야 할 질문은 「이 에이전트는 똑똑한가」가 아닙니다.

「이 에이전트는 실패하더라도 피해가 확산되지 않는 곳에서 구동되고 있는가」입니다.

이 질문을 던지면 샌드박스 계열의 툴들이 자연스럽게 떠오릅니다.

Work 의 끝에는 다음을 출력하게 합니다.

마지막으로, 다음 내용을 짧게 요약해 주세요.
- 변경한 파일
- 변경 내용
...

이 요약은 이후의 Review 에 그대로 사용할 수 있습니다.

AI에게 만들기만 시키면, 인간은 차이점 (Diff)을 추적하는 것부터 시작해야 합니다. AI에게 「리뷰의 입구」를 만들게 하면, 인간은 판단에 집중할 수 있습니다.

AI 에이전트를 사용하면 작업량은 늘어납니다.

이것은 의외일지도 모릅니다. 자동화하는데 왜 늘어나는가?

이유는 간단합니다. 만들 수 있는 양이 늘어나기 때문입니다.

자동화가 진행될수록 인간의 일이 사라진다고 단정할 수는 없습니다. 오히려 리뷰, 판단, 조정이 늘어납니다. 이 감각은 AI 코딩 에이전트 (AI Coding Agent)를 사용하면 바로 알 수 있습니다.

AI는 많이 만들 수 있습니다. 그래서 인간은 많이 판단하게 됩니다.

여기서 필요한 것은 모든 것을 끈기로 다 읽는 것이 아닙니다. 볼 곳을 정하는 것입니다.

저는 최소한 이 5가지를 봅니다.

이 5가지를 그대로 리뷰 요청에 할 수 있습니다.

이 diff를 리뷰해 주세요.
관점:
1. 첫 번째 목적에서 벗어나지 않았는지
...

이것은 다른 에이전트에게 던져도 좋습니다.
예를 들어, Claude Code로 구현하고 Codex로 diff review를 시키는 식입니다. Codex로 구현하고 Gemini에게 긴 컨텍스트로 제3자 리뷰를 시키는 것도 가능합니다. 어떤 조합이라도 괜찮습니다.

중요한 것은, 구현된 것과 같은 흐름 그대로 '문제없지?'라고 묻지 않는 것입니다.
같은 컨텍스트에 몰입해 있으면 AI든 인간이든 전제를 의심하기 어려워집니다. 리뷰는 약간 거리를 두고 하는 것이 효과적입니다.

예를 들어 SQLite의 AGENTS.md는 이 점에서 매우 시사적입니다.
AI가 생성한 코드를 그대로 받아들이지는 않습니다. 반면, 재현 가능한 테스트 케이스를 포함하는 버그 리포트는 받아들입니다. 즉, AI의 참여를 완전히 거부하는 것이 아니라, 어떤 형태일 때 가치가 있고 어떤 형태는 위험한지 구분하고 있습니다.

이것은 실무에서도 사용할 수 있는 사고방식입니다.
AI가 작성한 코드를 그대로 프로덕션에 넣을 필요는 없습니다.
하지만 AI에게 다음 작업을 시킬 가치는 있습니다.

• 재현 절차를 만들기
• 실패하는 테스트를 쓰기
• 변경 후보를 내놓기
• diff의 논점을 정리하기
• 기존 코드 읽기 메모 만들기
• review checklist 만들기

즉, AI의 출력을 '완성품'이 아니라 '인간이 판단하기 쉽게 만드는 재료'로 사용하는 것입니다.
이러한 거리감이 있으면 AI 에이전트는 상당히 사용하기 쉬워집니다.

agent가 만들어내는 양이 늘어나면, Review 문제는 곧바로 바뀝니다.
처음에는 'AI가 작성한 코드를 인간이 보는 것'으로 충분합니다. 하지만 PR(Pull Request)이 늘고, 수정안이 늘고, 여러 agent가 병렬로 작동하게 되면, 인간은 모든 것을 꼼꼼히 볼 수 없습니다.

여기서 필요한 것은 단순히 'AI에게 다시 리뷰를 시키는 것'만 아닙니다.
어떤 작업이 실행되었는지.
어떤 프롬프트로, 어떤 파일을 건드렸는지.
어떤 테스트가 통과했고, 어디에서 실패했는지.
어떤 변경을 인간에게 올려야 하는지.
CI(Continuous Integration)에 들어가기 전에 막아야 할 차이점은 무엇인지.

여기서 trace나 CI에 들어가기 전의 검증 과정이 등장합니다.
PromptLayer 같은 도구는 AI의 실행 이력, 프롬프트, 비용, 워크플로우를 추적하는 위치에 있습니다. 리뷰 자료를 남기기 위해서입니다.
Chunk sidecars 같은 메커니즘은 AI가 만든 diff를 CI에 넣기 전에 검증하는 위치에 있습니다. 인간이 모든 것을 보기 전에 명백히 위험하거나 부실한 것을 막기 위해서입니다.

Linear Diffs 같은 PR review workflow도 같은 맥락입니다. diff를 단순히 표시하는 것이 아니라, 인간이 봐야 할 변경을 어떻게 정리할지가 문제입니다.

이 단계까지 오면, Review는 '읽는 작업'이라기보다 '진단(分診)'에 가까워집니다.
모든 것을 읽는 것이 아니라, 볼 것을 올리는 것입니다.
기계로 처리할 수 있는 것은 처리하고,
인간이 판단해야 할 것만 남기는 것입니다.

AI 생성 코드의 양이 많아질수록, 이 계층(layer)이 필요합니다.
작은 개인 개발이라면 인간의 육안 검토 리뷰로 충분합니다.
하지만 같은 종류의 작업이 늘어나면, 리뷰는 점차 eval에 가까워집니다.

traces, evals, Codex를 사용해서 agent를 개선하는 흐름도 이 연장선상에 있습니다. LLM이나 agent의 품질은 분위기가 아니라 실제 데이터, 실패 사례, 평가 세트(evaluation set), 회귀 테스트로 봐야 합니다.

이것은 과장이 아닙니다.
예를 들어, 사내 FAQ bot나 코딩 에이전트라도 매번 같은 확인을 하고 있다면, 그것은 eval 할 수 있습니다.

• 답변에 근거 URL이 포함되는지
• 존재하지 않는 API를 사용하고 있지 않은지
• 변경 대상 외의 파일을 건드리고 있지 않은지
• migration을 변경했다면 rollback도 있는지
• 보안 경계를 넘어서고 있지 않은지
• 기존 테스트를 지우고 있지 않은지

처음에는 체크리스트로 충분합니다. 체크리스트가 안정되면, 테스트나 스크립트로 만듭니다. 더 필요하면 eval로 합니다.

Review는 인간의 의욕에서 점차적으로 시스템으로 옮겨가는 것입니다.
이 부분이 이 흐름에서 가장 중요한 부분입니다.
AI 에이전트를 사용하고 있다면, 실패는 반드시 발생합니다.
실패 자체가 문제가 아닙니다. 같은 실패가 반복해서 발생하는 것이 문제입니다.

예를 들어, AI가 또 테스트를 얕게 작성했다고 가정해 봅시다.

그 자리에서 "더 제대로 테스트해 줘"라고 말하면, 이번에는 고쳐질지도 모릅니다. 하지만 다음번에 또 발생합니다.

Compound에서는 그 실패를 다음번 메커니즘에 포함시킵니다.

향후 이 프로젝트에서 UI의 상태 변경을 다룰 때는,
정상계(Happy Path)뿐만 아니라 빈 상태(Empty State), 복수 조건의 조합, 리셋 조작을
최소 1케이스씩 테스트 후보에 포함해 주세요.

이것을 AGENTS.md에 넣습니다. 혹은 project memory에 넣습니다. 아니면 review prompt의 템플릿에 넣습니다.

중요한 것은, "이번의 주의사항"으로 끝내지 않는 것입니다.

배움을 남길 장소는 몇 가지 있습니다.

위치	적합한 내용
AGENTS.md	리포지토리 전체의 규칙, 커맨드, 금지 사항
CLAUDE.md	Claude Code를 위한 작업 방침, 프로젝트 문맥
project memory	장기적인 선호도, 반복되는 판단
checklist	review 관점, 작업 전 확인
prompt template	자주 사용하는 요청 문구
...

어느 것이 정답이라는 이야기는 아닙니다.

짧은 주의사항이라면 AGENTS.md.

매번 사용하는 요청이라면 템플릿.

자주 발생하는 실패라면 테스트.

복잡한 작업 절차라면 skill.

품질 판정이라면 eval.

이렇게 생각하면 정리하기 쉽습니다.

Compound에서 가장 어려운 것은 배움을 남기는 것이 아닙니다.

남긴 배움이 다음 작업으로 돌아오는 것입니다.

AGENTS.md에 규칙을 써도, 너무 길어지면 읽기 어려워집니다. project memory에 저장해도, 오래된 판단이 섞이면 방해가 됩니다. skill로 만든다 해도, agent가 필요한 타이밍에 호출할 수 없다면 의미가 없습니다.

여기서 memory나 작업 절차를 다음으로 돌려주는 도구가 다시 등장합니다.

Walrus Memory나 GPS는 단순히 문맥을 저장하는 도구가 아니라, 과거의 작업 결과를 다음 Plan으로 되돌리는 부품으로 봅니다. Recursi와 같은 도구는 작업 중에서 얻은 절차나 수정 패턴을 다음에 돌려주는 메커니즘으로 봅니다.

즉, 여기서도 평가 축은 "편리해 보이는가"가 아닙니다.

• 지난번의 실패가 다음번 Plan에 나타나는가
• review에서 수정한 것이 다음번 체크리스트에 들어가는가
• 테스트 부족이 다음번 spec에 반영되는가
• agent가 멋대로 나쁜 규칙을 늘리지 않는가
• 인간이 memory나 skill을 정리(Inventory)할 수 있는가

이런 점들을 봅니다.

Compound는 기억의 양이 아닙니다. 배움이 다음 공정으로 돌아가는 경로입니다.

나쁜 예는 너무 추상적인 규칙입니다.

품질에 주의해 주세요.

이것은 거의 효과가 없습니다. 무엇을 해야 할지 모르기 때문입니다.

조금 개선하면 다음과 같습니다.

구현 후에는 반드시 테스트를 수행해 주세요.

아직 약합니다. 어떤 테스트를, 어느 범위에서, 실패하면 어떻게 할지가 모호합니다.

더 좋은 것은 이런 형태입니다.

UI 컴포넌트를 변경한 경우:
- 기존 관련 테스트를 먼저 확인한다
- 상태가 변하는 조작을 최소 1케이스 추가한다
...

AI에게 효과적인 규칙은 정신론이 아니라 절차입니다.

절차를 skill로 나누는 것도 이 때문입니다. 조사, 계획, 구현, 원인 파악, 리뷰, 다음으로의 반영을 나눕니다. 작업 종류에 따라 필요한 입력과 출력을 결정합니다.

인간이 매번 떠올려야 했던 것을 에이전트가 꺼내 쓸 수 있는 형태로 만드는 것.

그것이 Compound입니다.

여기까지 읽고, "그럼 Claude Code와 Codex 중 어느 것을 사용해야 하는가"라고 생각할지도 모릅니다.

제 대답은, 고정하지 않는 편이 좋다는 것입니다.

모델이나 제품의 장단점은 변합니다. 오늘의 최적해가 다음 달에도 같으리라는 보장은 없습니다.

다만, 역할로서 나눈다면 다음과 같이 생각하는 것이 사용하기 쉽습니다.

역할	적합한 사용법
Claude Code	복잡한 문맥의 정리, 설계 상담, 기존 코드의 해석, 긴 계획
...

이것은 절대적인 것이 아닙니다.

중요한 것은 도구의 역할 분담보다 공정의 역할 분담입니다.

Plan은 누가 하는가.

Work는 어디까지 맡길 것인가.

Review는 무엇을 보는가.

Compound는 어디에 남기는가.

이 4가지가 정해져 있다면, 사용하는 에이전트 (Agent)가 바뀌어도 흐름이 쉽게 무너지지 않습니다.

반대로, 이 부분이 정해져 있지 않으면 어떤 에이전트를 사용하더라도 "빠르지만 불안하다"는 단계에서 멈추게 됩니다.

여기서 구체적인 예를 들어보겠습니다.

기존 관리 화면에 상품 검색 기능을 추가한다고 가정합니다.

첫 번째 요청입니다.

아직 구현하지 마세요.
관리 화면의 상품 목록에 검색 기능을 추가하고 싶습니다.
먼저 기존 코드를 읽고, 구현 계획 (Implementation Plan)만 제시해 주세요.
...

여기서 나온 계획을 사람이 확인합니다.

검색 대상이 상품명만으로 충분한지, SKU도 포함할 것인지. 서버 측 검색 (Server-side search)인지, 클라이언트 측 필터 (Client-side filter)인지. 대규모 데이터를 상정할 것인지.

이러한 판단은 사람이 하는 것이 좋습니다.

계획을 좁혔다면 구현을 진행합니다.

방침은 OK입니다.
이번에는 클라이언트 측에서 상품명만 검색합니다.
SKU 검색, API 변경, 페이지네이션 (Pagination) 변경은 하지 마세요.
...

다음은 테스트입니다.

관련 테스트를 추가해 주세요.
필요한 케이스:
- 검색 문자열이 비어 있다면 전체 항목 표시
...

구현 후, 다른 관점에서 리뷰 (Review)합니다.

이 변경 사항을 리뷰해 주세요.
관점:
- 당초 목적에 부합하는가
...

여기서도 사람이 확인해야 합니다.

AI 리뷰는 편리하지만, 최종 판단은 아닙니다. 특히 사양 (Specification)의 우선순위, 사용자 경험 (UX), 지금은 하지 않기로 한 판단 등은 사람이 보유해야 합니다.

마지막으로, 이번 학습 내용을 남깁니다.

이번 작업으로부터, 다음 이후에도 사용할 수 있는 규칙을 추출해 주세요.
대상:
- AGENTS.md 에 추가해야 할 규칙
...

나온 결과물을 그대로 넣지 않고 사람이 확인합니다.

예를 들어, 다음과 같은 규칙이라면 사용할 수 있습니다.

목록 화면에 필터나 검색을 추가할 경우:
- 기존 정렬(Sort) 및 카테고리 필터와의 조합을 확인할 것
- 빈 문자열인 경우 전체 항목이 표시되는 테스트를 추가할 것
...

이렇게 하면, 다음 목록 화면 변경 작업이 조금 더 수월해집니다.

이 "조금 더 수월해지는 것"을 쌓아가는 것이 바로 Compound 입니다.

지금까지는 기능 추가의 예로 작성했지만, 이 4단계는 코드를 작성하는 상황에만 국한되지 않습니다.

기술자의 일상에는 코드 이외에도 에이전트 (Agent)와 상성이 좋은 작업들이 있습니다.

• 기존 리포지토리 (Repository) 조사
• 장애 원인 분류 (Troubleshooting)
• PR (Pull Request) 사전 리뷰
• 라이브러리 업데이트 영향 조사
• RFC 또는 설계 메모 초안 작성
• 마이그레이션 (Migration) 절차 확인
• 로그 및 트레이스 (Trace) 읽기
• 보안 관점의 점검 (Inventory)

예를 들어, 장애 조사라면 다음과 같습니다.

아직 수정하지 마세요.
이 에러 로그와 관련 코드를 읽고,
원인 후보를 정리해 주세요.
...

먼저 재현 테스트만 만들어 주세요.
본체 코드는 아직 수정하지 마세요.
테스트가 실패하는 것을 확인했다면,
...

이 재현 테스트를 리뷰해 주세요.
관점:
- 정말로 이번 장애를 재현하고 있는가
...

이번 장애로부터, 다음번에 같은 종류의 문제를 빨리 찾기 위한
체크 항목을 만들어 주세요.
저장 위치는 AGENTS.md 또는 runbook을 상정합니다.
...

이렇게 하면, 코드 수정에 들어가기 전에 재현 조건과 판단 재료가 갖춰집니다.

AI 에이전트에게 갑자기 수정을 맡기는 것이 아니라, 먼저 조사, 다음으로 재현, 마지막으로 수정. 기술 작업에서는 이 순서가 매우 효과적입니다.

이 글은 입구입니다.

이후 내용은 각론을 나누어 깊이 있게 다룰 것입니다.

큰 요청을 망가뜨리지 않고, 작게 나누어 전달하는 방법을 다룹니다.

다루는 내용:

• 좋은 spec과 나쁜 spec
• read-only plan
• 비목적적(Non-objective)인 작성 방식
• 변경 범위 지정
• 테스트 조건
• 사양이 너무 길 때의 분할

AI가 내놓은 결과물을 어떻게 리뷰할지를 다룹니다.

다루는 내용:

• diff review
• human review
• AI에 의한 1차 판정
• eval
• traces
• 회귀 테스트 (Regression Test)
• "왠지 모르게 좋다"에서 벗어나는 방법

memory와 학습 내용을 되돌리는 방법을 다룹니다.

다루는 내용:

• 실패를 규칙으로 바꾸기
• AGENTS.md / CLAUDE.md
• project memory
• skill
• subagent
• review checklist
• SQLite의 AGENTS.md가 보여주는 "수용하는 AI 결과물"과 "수용하지 않는 AI 결과물"

Sandbox, 권한, 파일 경계를 다룹니다.

다루는 내용:

• 프로세스 샌드박스 (process sandbox)
• VM (가상 머신)
• 파일 시스템 경계 (filesystem boundary)
• 이그레스 제어 (egress control)
• 자격 증명 (credentials)을 넘겨주지 않는 설계
• 코드 실행의 위험성
• 에이전트 호러 스토리 (agent horror stories)

외부 도구 연결을 다룹니다.

다루는 내용:

• MCP의 역할
• 무엇이든 연결할 때의 위험성
• 읽기 전용 도구 (read-only tool)와 쓰기 도구 (write tool)
• 권한 스코프 (permission scope)
• 감사 로그 (audit log)
• 도구가 늘어났을 때의 관리

코드를 작성하기 전의 조사, 재현, 격리(切り分け)를 다룹니다.

다루는 내용:

• 읽기 전용 (read-only) 조사
• 변경 전의 가설 정리
• 재현 테스트
• 로그와 트레이스 (trace) 읽는 법
• 먼저 런북 (runbook)을 작성하게 하기
• 수정 전 리뷰

Codex App을 기술자가 로컬 작업, 리뷰, 화면 확인을 진행하는 작업대로 다룹니다.

다루는 내용:

• 프로젝트 (project)
• 스레드 (thread)
• 파일 (files)
• 앱샷 (Appshots)
• 로컬 파일 보여주기
• UI 깨짐이나 에러 화면 보여주기
• CLI 버전과의 용도 구분

매번 사용할 수 있는 요청 문구를 정리합니다.

다루는 내용:

• 조사만 요청하기
• 구현 계획만 요청하기
• 작게 구현하게 하기
• 테스트 추가시키기
• diff 리뷰
• 실패 원인 설명
• AGENTS.md 업데이트
• 다음 회차용 체크리스트화

이것은 스톡 (stock)되는 기사로 만들 것입니다. 독자가 그대로 복사해서 사용할 수 있는 형태로 구성합니다.

마지막으로, 팀이나 개인이 어디서부터 시작해야 하는지를 다룹니다.

다루는 내용: