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

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

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

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

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

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

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

"역시 AI는 아직 신뢰할 수 없어"\n
절반은 맞습니다. 아무 생각 없이 맡긴다면 신뢰하지 않는 편이 좋습니다.

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

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

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

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

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

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

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

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

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

우선, "AI에게 만들게 하기"에서 벗어나기

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

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

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

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

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

이 전체가 업무입니다.

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

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

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

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

큰 변경을 작게 나눈다.

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

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

성공한 절차를 남긴다.

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

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

전체상: Plan, Work, Review, Compound

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

이 흐름의 포인트는 마지막이 "완료(Done)\

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

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

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

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

Plan: 만들게 하기 전에, 업무를 설계한다

AI 에이전트에서 가장 차이가 벌어지는 지점은 구현 전이다.

코드를 쓰게 하기 전에, 얼마나 업무를 작고 검증 가능한 형태로 나눌 수 있는가. 여기서 거의 결정된다.

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

이는 평소의 사용 방식에 그대로 적용할 수 있다.

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

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

이렇게 하면 AI는 부족한 부분을 마음대로 채워 넣는다. 검색 대상, UI, 상태 관리 (State Management), API, 테스트 범위, 기존 설계와의 관계를 상당 부분 추측한다. 추측이 맞으면 빠르지만, 틀리면 뒷수습이 무거워진다.

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

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

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

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

Plan에서 결정할 것

Plan에서는 적어도 다음을 결정한다.

'비목적 (Non-goal)'은 특히 효과적이다.

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

그래서 하지 않을 일을 명시한다.

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

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

Plan에서 막히는 부분: 전제가 매번 사라짐

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

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

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

여기서 memory layer가 등장한다.

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

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

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

그래서 이런 도구들을 평가할 때도 '기억할 수 있습니까?'만으로는 부족하다.

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

이런 점들을 본다.

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

좋은 Plan은 구현을 서두르지 않는다

Plan 단계에서 원하는 것은 훌륭한 설계서가 아니다.

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

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

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

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

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

Work: 작게 만들게 하고, 실행 결과를 보면서 진행하기

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

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

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

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

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

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

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

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

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

AI에게 "작성하고 끝"내게 하지 마세요. 실행합니다. 실패를 봅니다. 원인을 읽습니다. 수정합니다. 다시 실행합니다.

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

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

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

이렇게 하면 AI가 임기응변식으로 수정하는 것을 방지할 수 있습니다.

Work에서 막히는 부분: 실행 환경이 너무 가까움

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

에이전트 (Agent)에게 테스트를 실행하게 하고, 빌드하게 하고, 로컬 서버를 띄우게 하고, 로그를 읽게 하는 것까지는 자연스럽습니다.

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

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

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

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

임시 VM에서 구동할 것인가.

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

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

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

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

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

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

"이 에이전트는 실패하더라도 피해가 확산되지 않는 곳에서 작동하고 있는가?"

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

Work에서 확인해야 할 것

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

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

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

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

Review: 인간은 전부 읽기보다 "볼 곳"을 정한다

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

이것은 의외일 수 있습니다. 자동화하는데 왜 늘어나는 걸까요?

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

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

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

여기서 필요한 것은 모든 것을 끈기로 읽어내는 것이 아닙니다. 어디를 볼지 결정하는 것입니다.

Review에서 확인해야 할 5가지

저는 최소한 이 5가지를 확인합니다.

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

이 diff를 리뷰해 주세요.
관점:
1. 최초의 목적에서 벗어나지 않았는가
...

이것은 별도의 에이전트 (Agent)에게 던져도 좋습니다.

예를 들어, Claude Code로 구현하고, Codex로 diff review를 수행합니다. Codex로 구현하고, Gemini에게 긴 문맥 (Context)을 활용해 제3자 리뷰를 시킵니다. 어떤 조합이든 상관없습니다.

중요한 것은, 구현한 것과 동일한 흐름 속에서 "문제없지?"라고 묻지 않는 것입니다.

같은 문맥에 젖어 있으면, AI도 인간도 전제를 의심하기 어려워집니다. 리뷰는 조금 거리를 두는 편이 효과적입니다.

"AI가 작성한 코드"를 그대로 받아들이지 않는다

예를 들어 SQLite의 AGENTS.md는 이 점에서 매우 시사하는 바가 큽니다.

AI가 생성한 코드를 그대로 받아들이는 것이 아닙니다. 반면, 재현 가능한 테스트 케이스 (Test Case)를 포함한 버그 보고는 받아들입니다. 즉, AI의 참여를 완전히 거부하는 것이 아니라, 어떤 형태라면 가치가 있고 어떤 형태는 위험한지를 구분하고 있습니다.

이는 실무에서도 사용할 수 있는 사고방식입니다.

AI가 작성한 코드를 그대로 운영 환경 (Production)에 넣을 필요는 없습니다.

하지만 AI에게 다음을 시킬 가치는 있습니다.

• 재현 절차 만들기
• 실패하는 테스트 작성하기
• 변경 후보 제시하기
• diff의 논점 정리하기
• 기존 코드 읽기 메모 만들기
• review checklist 만들기

즉, AI의 출력을 "완성품"이 아니라 "인간이 판단하기 쉽게 만드는 재료"로 사용하는 것입니다.

이러한 거리감이 있다면 AI 에이전트 (AI Agent)는 상당히 사용하기 편해집니다.

Review에서 막히는 부분: 인간의 눈이 따라가지 못함

에이전트 (Agent)가 만드는 양이 늘어나면, Review의 문제는 즉시 변합니다.

처음에는 "AI가 작성한 코드를 인간이 본다"로 충분합니다. 하지만 PR (Pull Request)이 늘어나고, 수정안이 늘어나며, 여러 에이전트 (Agent)가 병행해서 움직이게 되면, 인간은 모든 것을 정성스럽게 볼 수 없습니다.

여기서 필요한 것은 단순히 "AI에게 다시 한번 리뷰를 시키는 것"만이 아닙니다.

어떤 작업이 실행되었는가.

어떤 프롬프트 (Prompt)로 어떤 파일을 건드렸는가.

어떤 테스트가 통과했고 어디서 실패했는가.

어떤 변경 사항을 인간에게 보고해야 하는가.

CI (Continuous Integration)에 들어가기 전에 멈춰야 할 차분 (Diff)은 무엇인가.

여기서 trace나 CI에 들어가기 전의 검증이 등장합니다.

PromptLayer와 같은 도구는 AI의 실행 이력, 프롬프트 (Prompt), 비용, 워크플로우 (Workflow)를 추적하는 위치에 들어갑니다. Review를 위한 재료를 남기기 위해서입니다.

Chunk sidecars와 같은 메커니즘은 AI가 만든 차분 (Diff)을 CI에 넣기 전에 검증하는 위치에 들어갑니다. 인간이 전부를 보기 전에, 명백히 위험하거나 조잡한 것을 차단하기 위해서입니다.

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

이 단계까지 오면, Review는 "읽는 작업"이 아니라 "분진 (Triage)"에 가까워집니다.

전부를 읽는 것이 아니라, 봐야 할 것을 올린다.

기계로 걸러낼 수 있는 것은 걸러낸다.

인간이 판단해야 할 것만 남긴다.

AI 생성 코드의 양이 늘어날수록, 이 계층이 필요해집니다.

Review는 eval에 가까워진다

작은 개인 개발이라면 인간의 육안 리뷰로 충분합니다.

하지만 동일한 종류의 작업이 늘어나면, 리뷰는 점점 eval (Evaluation)에 가까워집니다.

traces, evals, Codex를 사용하여 에이전트 (Agent)를 개선하는 흐름도 이 연장선에 있습니다. LLM이나 에이전트 (Agent)의 품질은 분위기가 아니라, 실제 데이터, 실패 사례, 평가 세트 (Evaluation Set), 회귀 테스트 (Regression Test)로 확인해 나갑니다.

이는 과장된 이야기가 아닙니다.

예를 들어 사내 FAQ bot이라도, 코딩 에이전트 (Coding Agent)라도, 매번 같은 확인을 하고 있다면 그것은 eval (Evaluation)로 만들 수 있습니다.

• 답변에 근거 URL이 포함되어 있는가
• 존재하지 않는 API를 사용하고 있지 않은가
• 변경 대상이 아닌 파일을 건드리고 있지 않은가
• migration을 변경했다면 rollback도 있는가
• 보안 경계 (Security Boundary)를 넘지 않았는가
• 기존 테스트를 삭제하지 않았는가

처음에는 체크리스트로 시작해도 좋습니다.

체크리스트가 안정되면 테스트나 스크립트로 만듭니다. 더 필요하다면 eval (평가)로 만듭니다.

Review (리뷰)는 인간의 의지(기합)로부터 조금씩 시스템(메커니즘)으로 옮겨가는 것입니다.

Compound: 한 번의 실패를 다음의 성공으로 바꾸기

이 부분이 이 흐름에서 가장 중요한 부분입니다.

AI 에이전트 (AI Agent)를 사용하다 보면 실패는 반드시 일어납니다.

실패 자체가 문제는 아닙니다. 같은 실패가 반복되는 것이 문제입니다.

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

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

Compound (컴파운드)에서는 그 실패를 다음번의 시스템에 포함시킵니다.

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

이것을 AGENTS.md에 넣습니다. 혹은 project memory (프로젝트 메모리)에 넣습니다. 아니면 review prompt (리뷰 프롬프트) 템플릿에 넣습니다.

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

Compound의 위치

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

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

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

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

반복되는 실패라면 테스트.

복잡한 작업 절차라면 skill (스킬).

품질 판정이라면 eval (평가).

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

Compound에서 막히는 부분: 배움이 다음으로 돌아오지 않음

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

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

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

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

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

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

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

이러한 점들을 봅니다.

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

나쁜 Compound, 좋은 Compound

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

품질에 주의해 주세요.

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

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

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

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

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

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

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

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

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

그것이 Compound입니다.

Claude Code와 Codex는 어떻게 구분해서 사용하는가

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

제 대답은, 하나로 고정하지 않는 것이 좋습니다.

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

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

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

Plan은 누가 하는가.

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

Review는 무엇을 볼 것인가.

Compound는 어디에 남길 것인가.

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

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

실례: 작은 기능 추가를 4단계로 돌리기

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

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

1. Plan

첫 번째 요청입니다.

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

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

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

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

2. Work

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

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

다음은 테스트입니다.

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

3. Review

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

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

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

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

4. Compound

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

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

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

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

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

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

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

코드 이외의 기술 작업에도 동일한 흐름을 사용하기

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

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

• 기존 리포지토리(Repository) 조사
• 장애 원인 분류
• PR(Pull Request) 사전 리뷰
• 라이브러리 업데이트 영향 조사
• RFC나 설계 메모 초안 작성
• migration 절차 확인
• 로그나 trace 읽기
• 보안 관점의 점검

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

Plan

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

Work

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

Review

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

Compound

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

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

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

이 시리즈에서 다룰 내용

이 글은 입구입니다.

여기서부터는 각론을 나누어 깊이 있게 다루겠습니다.

제1회: AI 에이전트에게 전달할 사양서(Specification) 작성법

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

다루는 내용:

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

제2회: AI 에이전트의 결과물을 어떻게 검품할 것인가

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

다루는 내용:

• diff review
• human review
• AI에 의한 1차 판정
• eval
• traces
• 회귀 테스트 (regression test)
• "어쩐지 괜찮다"는 느낌에서 벗어나는 방법

제3회: 한 번의 실패를 다음의 성공으로 바꾸기

memory와 학습 내용을 되돌려주는(feedback) 방법을 다룹니다.

다루는 내용:

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

제4회: AI 에이전트에게 실행시키기 전에

Sandbox, 권한, 파일 경계(file boundary)를 다룹니다.

다루는 내용: