한 번의 실패를 다음 성공으로 바꾸는 법──AGENTS.md, Memory, Skill의 활용 구분 제3회

이 시리즈에서는 AI 에이전트를 「코드를 작성하게 하는 도구」가 아니라, 개발 공정에 참여하는 작업자로 다룹니다.

제0회에서는 전체를 Plan, Work, Review, Compound로 나누었습니다.

제1회에서는 에이전트에게 전달할 사양서(Specification)를 작성하는 법을 다루었습니다.

제2회에서는 에이전트의 업무를 어떻게 검품할지를 다루었습니다.

이번에는 마지막 단계인 Compound입니다.

Compound는 조금 추상적으로 들릴 수 있습니다. 하지만 실무에서는 상당히 구체적입니다.

같은 지적을 다음 PR(Pull Request)에서도 또 쓰고 있지는 않은가.

같은 조사를 다른 세션에서 또 처음부터 다시 하고 있지는 않은가.

같은 실수를 다른 agent가 또 저지르고 있지는 않은가.

이것을 줄이는 것이 Compound입니다.

바꿔 말하면, AI 에이전트와의 개발에서 가장 아까운 것은 실패 그 자체가 아닙니다.

실패로부터 얻은 판단 기준이 다음 작업으로 돌아가지 않는 것입니다.

AI 에이전트 이야기를 하면 곧바로 memory라는 단어가 나옵니다.

다만, 여기서 중요한 것은 「AI에게 무엇이든 기억시키게 하는 것」이 아닙니다.

기억이 늘어나더라도 다음 작업의 입구에서 사용되지 않는다면 의미가 없습니다. 오래된 판단, 모호한 취향, 기한이 지난 사양이 섞이면 오히려 방해가 됩니다.

개발에 필요한 memory는 보관소가 아니라, 되돌아오는 길입니다.

Review에서 발견된 문제를 다음 Plan으로 되돌린다.

테스트에서 실패한 조건을 다음 사양서로 되돌린다.

사람이 매번 설명해야 하는 취향을 다음 작업 시작 시에 되돌린다.

조사에서 발견한 설계 판단을 다음 구현 시에 되돌린다.

이 「되돌리는」 메커니즘을 만들면 에이전트와의 업무는 조금씩 편해집니다.

매번 프롬프트(Prompt)를 잘 쓰는 사람이 강한 것이 아닙니다.

매번의 작업 결과가 다음 작업의 문맥(Context)이 되는 팀이 강한 것입니다.

memory를 생각할 때는 저장소보다 먼저 흐름을 봅니다.

• 무엇을 남길 것인가
• 어떻게 요약할 것인가
• 언제 꺼낼 것인가
• 어디에 주입할 것인가
• 언제 지울 것인가

이 다섯 가지입니다.

많은 실패는 첫 번째 항목만 보고 발생합니다.

「전부 남긴다」는 것만으로는 다음 작업이 좋아지지 않습니다.

오래된 판단이 남는다.

이번에만 해당하는 사정이 남는다.

비슷한 메모가 늘어난다.

중요한 규칙이 묻힌다.

agent가 매번 관계없는 문맥을 읽는다.

이렇게 되면 memory는 도움이 아니라 부하가 됩니다.

그래서 memory에는 수명을 부여합니다.

단기:
- 이번 조사의 로그
- 일시적인 가설
...

단기적인 것을 AGENTS.md에 넣지 않습니다.

장기적인 것을 채팅 흐름에만 두지 않습니다.

이 구분이 중요합니다.

memory는 저장, 검색, 주입, 삭제까지 포함하여 설계합니다.

무엇이든 AGENTS.md에 쓰면 된다는 이야기가 아닙니다.

무엇이든 CLAUDE.md에 쓰면 된다는 이야기도 아닙니다.

무엇이든 memory tool에 저장하면 된다는 이야기도 아닙니다.

남길 것은 우선 세 가지 종류로 나누는 것이 다루기 쉽습니다.

첫 번째는 사실과 입구입니다.

어떤 파일에서 읽을 것인가.

어떤 명령어로 테스트할 것인가.

어떤 설계 문서가 지금도 유효한가.

어떤 화면이 어떤 컴포넌트(Component)에 대응하는가.

이것은 README.md, docs/, INDEX.md, runbook에 둡니다.

두 번째는 작업 규칙입니다.

이 리포지토리(Repository)에서는 무엇을 해서는 안 되는가.

변경 전에 무엇을 읽게 할 것인가.

테스트가 실패했을 때 어디까지 수정해도 되는가.

큰 변경을 할 때 어디에서 멈춰야 하는가.

이것은 AGENTS.md나 project-scoped memory에 둡니다.

세 번째는 절차입니다.

버그 재현 절차.

PR review 절차.

DB migration 확인 절차.

장애 조사 분류 절차.

사양서를 만드는 절차.

이것은 checklist, template, skill, custom command로 만듭니다.

이 세 가지를 섞으면 금방 읽기 어려워집니다.

AGENTS.md에 전부 넣으면 agent는 매번 긴 주의사항을 읽어야 합니다. CLAUDE.md에 전부 넣으면 개인의 취향과 리포지토리의 규칙이 섞입니다. memory tool에 전부 넣으면 어떤 것이 지금도 유효한 판단인지 알 수 없게 됩니다.

처음에 놓을 장소를 나누는 것만으로도 사고를 상당히 줄일 수 있습니다.

AGENTS.md는 에이전트용 리포지토리 설명서입니다.

사람을 위한 README.md

사람을 위한 README.md가 "이 프로젝트는 무엇인가"를 설명하는 것이라면, AGENTS.md는 "이 프로젝트에서 작업할 때 어떻게 행동해야 하는가"를 설명하는 것입니다.

작성해야 하는 것은 매번 적용되기를 바라는 규칙입니다.

예를 들어, 다음과 같은 것입니다.

# AGENTS.md
## Before Editing
- 변경 전 관련 router, service, test를 읽는다.
...

여기서 중요한 것은 AGENTS.md를 희망 사항 목록으로 만들지 않는 것입니다.

나쁜 예시입니다.

- 깨끗한 코드를 작성한다.
- 최고의 구현을 만든다.
- 버그를 내지 않는다.
...

이것은 거의 효과가 없습니다.

"깨끗함"이란 무엇인가?

"최고"란 무엇인가?

"정중함"이란 무엇을 하는 것인가?

에이전트 (agent)가 실행 가능한 형태가 아니기 때문입니다.

좋은 AGENTS.md는 행동으로 구체화되어 있습니다.

- `services/search.ts`를 변경한 경우, `tests/search/*.test.ts`를 실행한다.
- 새로운 검색 조건을 추가한 경우, 기존 조건과의 조합 테스트를 1개 이상 추가한다.
- SQL을 변경한 경우, 결과 없음, 다수 건, 권한 없음의 3가지 케이스를 확인한다.

이 정도로 구체적이라면, 다음 Plan (계획)과 Review (검토) 단계로 돌아옵니다.

SQLite의 AGENTS.md는 이 점에서 상당히 흥미롭습니다.

SQLite는 에이전트 (agent)가 생성한 코드를 그대로 받아들이지 않습니다. 반면, 에이전트 (agent)가 만든 bug report (버그 리포트), 재현 절차, test case (테스트 케이스)는 받아들이기 쉽습니다.

이것은 중요합니다.

AI 에이전트와의 개발에서는 "무엇을 만들게 할 것인가"뿐만 아니라, "무엇이라면 받아들일 것인가"를 결정해야 합니다.

예를 들어, 리포지토리(repository)에 따라 다음과 같이 작성할 수 있습니다.

## Accepted Agent Outputs
- 작은 테스트 추가
- bug reproduction (버그 재현)
...

이것은 과도하게 신중한 이야기가 아닙니다.

오히려 에이전트 (agent)를 실무에 투입하기 위한 현실적인 선긋기입니다.

전부 맡기지 않는다.

하지만, 전부 금지하지도 않는다.

어떤 결과물이라면 빠르게 받아들일 수 있는지를 결정한다.

이것이 결정되면, Codex나 Claude Code에 넘길 작업의 입도(granularity)가 상당히 안정됩니다.

CLAUDE.md는 Claude Code에서 자주 사용되는 작업 문맥(context) 파일입니다.

AGENTS.md와 비슷하지만, 완전히 같은 것으로 취급하지 않는 것이 좋습니다.

AGENTS.md는 리포지토리에 들어오는 에이전트 (agent) 전체에 대한 작업 규칙입니다.

CLAUDE.md는 Claude Code로 작업할 때의 문맥, 선호도, 워크플로우 (workflow)입니다.

예를 들어 CLAUDE.md에는 다음과 같은 내용이 적합합니다.

# CLAUDE.md
## Working Style
- 처음에 관련 파일을 읽고, 바로 구현에 들어가지 않는다.
...

단, CLAUDE.md는 너무 길게 만들지 않는 것이 좋습니다.

너무 긴 CLAUDE.md는 그 자체로 부하가 됩니다. 매번 모든 것을 읽게 하면, 해당 세션과 관계없는 정보까지 문맥 (context)을 압박합니다.

길어진다면 분리합니다.

CLAUDE.md
docs/agent-guides/
review.md
...

항상 읽는 것은 짧게.

필요할 때만 읽는 것은 guide (가이드)나 skill (스킬)로.

이렇게 분리할 수 있게 되면, memory (메모리)는 상당히 가벼워집니다.

규모가 큰 리포지토리에서 에이전트 (agent)는 우선 길을 잃습니다.

어디서부터 읽어야 할지.

무엇이 오래된 설계이고, 무엇이 현재의 설계인지.

비슷한 이름의 파일 중 어떤 것이 입구인지.

여기서 INDEX.md가 효과를 발휘합니다.

INDEX.md는 긴 설명서가 아닙니다. 입구의 지도입니다.

# Project Index
## Product List
- `app/products/page.tsx`
...

이것만으로도 초기 조사 비용이 상당히 낮아집니다.

에이전트 (agent)는 모든 것을 읽을 수 있는 것처럼 보이지만, 실제로는 입구가 좋지 않으면 시간을 낭비합니다. 관계없는 파일을 읽고, 오래된 구현을 참고하며, 비슷하지만 다른 테스트를 수정합니다.

INDEX.md는 그 낭비를 줄이기 위한 작은 지도입니다.

반복되는 작업은 skill (스킬)로 만듭니다.

여기서 말하는 skill (스킬)은 특정 agent (에이전트)가 필요할 때 읽는 절차서입니다. Claude Code의 skill (스킬)이든, Codex의 project guide (프로젝트 가이드)든, 독자적인 skills/ 디렉터리여도 상관없습니다.

기준은 단순합니다.

일주일에 한 번 수행한다면, skill (스킬)로 만들 후보입니다.

예를 들어, 다음과 같은 것들입니다.

• 사양서 작성하기
• PR (Pull Request) 리뷰하기
• 버그 재현하기
• flaky test (플래키 테스트) 분리하기
• migration (마이그레이션) 확인하기
• release note (릴리스 노트) 작성하기
• 장애 조사 메모 만들기
• 보안 영향 확인하기

skill (스킬)로 만들 때는 추상적인 설명보다 입력과 출력을 명확히 합니다.

# Skill: Bug Reproduction
사용자가 버그를 보고했지만 근본 원인을 모를 때 사용하십시오.
## Inputs
...

이 정도라면 다음에 같은 종류의 버그가 왔을 때 사용할 수 있습니다.

"버그를 조사해줘"라고 부탁하는 것보다 훨씬 강력합니다.

Review (리뷰)의 마지막에 매번 조금씩 Compound note (컴파운드 노트)를 작성합니다.

이것은 긴 일일 보고서가 아닙니다.

다음 작업으로 넘기기 위한 메모입니다.

예를 들어, 검색 기능의 PR (Pull Request)을 리뷰했다고 가정해 봅시다.

문제는 다음과 같았습니다.

• 상품명 검색은 추가됨
• category filter (카테고리 필터)와 동시에 사용하면 망가짐
• 테스트는 상품명만 보고 있으며, 기존 필터와의 조합은 확인하지 않음

그 자리에서 코드를 고치기만 한다면, 다음에도 똑같은 일이 일어납니다.

Compound note (컴파운드 노트)로 작성하면 다음과 같습니다.

## Compound Note
### What failed
상품명 검색 구현 시, 기존 category filter (카테고리 필터)와의 조합이 누락됨.
...

이 note (노트)의 가치는 "이번의 실패"를 "다음의 입구"로 바꾸는 것입니다.

여기까지 해야 비로소 Review (리뷰)가 Compound (컴파운드)해집니다.

나쁜 note (노트)는 반성문이 됩니다.

다음부터는 더 주의하자.
검색 관련은 조심하자.
테스트를 제대로 쓰자.

이것은 거의 효과가 없습니다.

좋은 note (노트)는 다음 작업으로 이어집니다.

검색 조건을 추가할 경우, 단일 조건뿐만 아니라 기존 조건과의 조합 테스트를 추가한다.
대상: `services/product-search.ts`
확인 대상: `tests/product-search.test.ts`
...

"조심하자"가 아니라, 다음 Plan (계획), Review (리뷰), Test (테스트)로 들어가는 형태를 만듭니다.

Compound note (컴파운드 노트)를 작성했다면, 보관할 장소를 정합니다.

이 표로 대략적인 판단이 가능합니다.

되돌리고 싶은 내용	보관 장소
리포지토리 전체의 작업 규칙	AGENTS.md
...

모든 것을 영구화하지 않는 것도 중요합니다.

단 한 번뿐인 조사 로그를 AGENTS.md에 넣으면 금방 지저분해집니다.

반대로, 매번 같은 리뷰 지적 사항을 PR (Pull Request) 코멘트에만 적고 있다면, 그것은 영구화해야 합니다.

판단 기준은 다음과 같습니다.

다음 3번의 작업에서도 유효하다면 남긴다.

이번 한 번뿐이라면 남기지 않는다.

망설여진다면 우선 checklist (체크리스트)에 둔다.

여기서 GPS, Walrus Memory, Minimi와 같은 memory layer (메모리 레이어)가 자연스럽게 등장합니다.

다만, 이것들을 단순히 "기억 도구"로만 보면 약합니다.

개발에서의 역할은 다음 작업 시작 시 필요한 문맥 (context)을 되돌려주는 것입니다.

예를 들어, 다음과 같은 문제가 있다고 가정해 봅시다.

• agent (에이전트)가 매번 같은 repo rule (리포지토리 규칙)을 잊어버림
• 과거의 설계 판단을 매번 설명해야 함
• 다른 앱이나 다른 세션에서 결정한 사항이 돌아오지 않음
• "지난번에 왜 그렇게 구현하지 않았는지"가 사라짐

이 단계에서 memory layer (메모리 레이어)가 후보가 됩니다.

GPS는 repo rules (리포지토리 규칙)와 past lessons (과거의 교훈)를 저장하는 memory layer (메모리 레이어)로 소개됩니다.

Walrus Memory는 apps (앱)와 sessions (세션)를 가로질러 agent (에이전트)가 context (문맥)를 가질 수 있게 하는 도구입니다.

Minimi는 Claude를 위한 ambient memory (앰비언트 메모리)라는 위치를 가집니다.

무엇을 사용할지 결정하기 전에, 무엇을 되돌리고 싶은지를 먼저 결정해야 합니다.

나쁜 사용법입니다.

전부 기억해 둬.

좋은 사용법입니다.

이 repo에서는 검색 조건을 추가하면 기존 filter와의 조합 테스트를 반드시 추가한다.
다음에 product search를 다룰 때, 이 규칙을 Plan으로 되돌린다.

memory는 양보다 어떻게 다시 불러오느냐의 문제입니다.

Recursion (재귀)와 같은 도구도 단순히 "AI가 스스로 개선한다"라고 보기보다, 작업 루프(work loop)의 어디에 들어가는지로 생각하는 편이 좋습니다.

Plan, Work, Review, Compound 중에서는 주로 Compound 측입니다.

작업 중에 나온 수정 패턴을 다음 작업으로 되돌린다.

실패한 흐름을 다음 실행 절차에 반영한다.

같은 종류의 작업을 이전보다 적은 설명으로 시작할 수 있게 한다.

이것이 가능하다면, "우리들의 작업에 맞춰 성장한다"라는 말에 실체가 생깁니다.

반대로, 그저 매번 긴 컨텍스트 (context)를 갖게 하는 것뿐이라면 개선이 아닙니다.

배움이 돌아올 장소가 필요합니다.

여기서 흥미로운 점은 구현 그 자체보다 공정을 나누는 것입니다.

많은 사람은 AI 에이전트 (AI agent)에게 이렇게 부탁합니다.

이 기능을 만들어줘.

하지만 공정으로 본다면 다음과 같이 나눕니다.

먼저 plan 해줘.
그다음 작게 work 해줘.
그 결과를 review 해줘.
...

이것은 형식적인 차이가 아닙니다.

마지막에 compound를 명시하면, agent는 "다음에 남겨두어야 할 것"을 찾기 시작합니다.

사람도 마찬가지입니다.

작업을 마친 순간 바로 다음 태스크 (task)로 넘어가면 배움은 사라집니다.

단 5분이라도 다음에 되돌릴 것을 결정합니다.

이 5분이 장기적으로는 상당히 효과적입니다.

조금 더 실무에 가깝게 가보겠습니다.

상품 목록에 검색을 추가하는 태스크가 있었습니다.

사양은 다음과 같습니다.

상품 목록에 상품명 검색을 추가한다.
기존의 category filter, status filter, pagination은 유지한다.

agent는 구현했습니다.

Review 단계에서 category filter와 검색어를 동시에 지정했을 때 망가진다는 것을 알게 되었습니다.

그 자리에서 수정하고 끝낸다면 여기서 종료입니다.

Compound까지 수행한다면, 4곳으로 되돌립니다.

## Search Changes
- 검색 조건을 추가·변경했을 경우, 기존 조건과의 조합 테스트를 추가한다.
- filter, sort, pagination 중 하나를 건드렸을 경우, 동시 지정 케이스를 확인한다.

이것은 repo 전체에서 반복적으로 적용되는 규칙입니다.

## Existing Behavior To Preserve
- category filter:
- status filter:
...

다음 사양서를 작성할 때, 처음부터 기존 동작을 확인할 수 있습니다.

## Search Review Checklist
- 새로운 조건은 단독으로 동작하는가.
- 기존 조건과 동시에 지정해도 동작하는가.
...

다음 PR review에서 사람이 같은 일을 기억해내지 않아도 됩니다.

it("combines keyword search with category filter", async () => {
const result = await searchProducts({
keyword: "desk",
...

매번 사람이 읽는 것보다 테스트로 만드는 것이 더 강력한 것은 테스트로 만듭니다.

여기까지 하면 다음 agent는 처음부터 다른 지도를 가지고 작업할 수 있습니다.

이것이 Compound입니다.

여기서 주의할 점이 있습니다.

Compound를 시작하면 파일이 늘어납니다.

AGENTS.md가 늘어납니다.

CLAUDE.md가 늘어납니다.

docs/agent-guides/가 늘어납니다.

skill이 늘어납니다.

checklist가 늘어납니다.

늘리는 것 자체가 목적이 되면 금방 파탄 납니다.

오래된 memory는 오래된 의존 라이브러리 (dependency library)와 같습니다.

존재하는 것만으로도 다음 작업에 영향을 줍니다.

그래서 정기적으로 검토합니다.

## Memory Review
- 이 규칙은 지금도 유효한가.
- 이미 테스트로 보장되고 있다면, 문서에서 지울 수 없는가.
...

memory는 더하기만 하는 것이 아니라 깎아낼 필요도 있습니다.

처음부터 완벽한 memory system을 만들 필요는 없습니다.

우선 4가지만으로도 충분합니다.

첫 번째. AGENTS.md에 테스트 커맨드 (test command), 금지 사항, 정지 조건을 적는다.

두 번째. INDEX.md에 주요 기능의 진입점 파일을 적는다.

세 번째. PR review의 마지막에 Compound note를 3줄만 작성한다.

네 번째. 동일한 지적 사항이 2번 나오면, AGENTS.md, template, test, skill 중 하나로 되돌린다.

이 정도라면 바로 시작할 수 있습니다.

## Compound Note
- What failed:
- Pattern:
...

처음에는 이것만으로 충분합니다.

중요한 것은 작업의 마지막에 "다음으로 되돌릴 것은 무엇인가"라고 묻는 것입니다.

Codex App이나 Claude Code를 사용하는 경우도 사고방식은 같습니다.

처음에 agent에게 전달하는 것은 거대한 지시문이 아닙니다.

먼저 AGENTS.md와 INDEX.md를 읽어주세요.
이번 태스크(task)와 관련된 파일만 추가로 읽어주세요.
구현 전에 Plan을 내주세요.

작업 중에는 Work를 작게 나눕니다.

먼저 검색 조건 구성 부분만 변경해 주세요.
UI는 아직 건드리지 마세요.

Review에서는 검수할 관점을 전달합니다.

차이점(diff)을 review해 주세요.
특히 기존 filter, pagination, empty state의 regression을 확인해 주세요.

마지막으로 Compound 합니다.

이번 작업에서 다음으로 되돌려야 할 규칙, checklist, test, skill 후보를 꼽아주세요.
AGENTS.md에 넣어야 할 것과 이번에만 해당하는 메모를 구분해 주세요.

이렇게 하면 agent는 단발성 구현자가 아니라, 공정 속에서 학습을 환류(feedback)하는 작업자가 됩니다.

AI 에이전트를 사용하면 한 번의 작업은 빨라집니다.

하지만 그것만으로는 팀의 개발 속도가 안정되지 않습니다.

안정시키려면 Review에서 발견된 것을 다음 Plan으로 되돌려야 합니다.

AGENTS.md는 repo-wide한 작업 규칙.

CLAUDE.md는 Claude Code를 위한 작업 문맥(context)이나 선호도.

INDEX.md는 리포지토리(repository)의 입구 지도.

skill은 반복되는 절차.

memory layer는 과거의 판단을 다음 작업 시작 시점에 되돌리기 위한 부품입니다.

이 모두 단순히 늘리기만 하면 되는 것이 아닙니다.

목적은 AI에게 많이 기억시키는 것이 아닙니다.

다음 작업을 지난번보다 조금 더 나은 상태에서 시작하는 것입니다.

다음에는 AI 에이전트에게 실행시키기 전의 이야기를 하겠습니다.

sandbox, 권한, 파일 경계, secret, 네트워크 액세스.

에이전트를 강력하게 만들수록 실행 환경의 설계가 중요해집니다.