에이전트가 배운 회피 패턴은 조건을 통과한 것만 파일로 쌓고 주기적으로 지운다

리뷰와 장애에서 배운 교훈을 common-pitfalls.md 같은 문서 하나에 계속 덧붙이면, 문서는 금방 커지고 에이전트는 매번 전부 읽게 된다. 이 글은 회피 패턴(pitfalls)을 패턴 하나에 파일 하나로 쌓고, 작업에 맞는 파일만 골라 읽게 하는 운영 방식을 정리한다. 무엇을 쌓을지 정하는 네 가지 조건, 쌓은 것을 정리하는 주기, 파일 형식과 링크 규칙을 함께 다룬다.

하네스 엔지니어링 실전편은 critic 이 같은 지적을 반복하자 common-pitfalls.md 로 누적한 과정을 다룬다. 이 글은 그 파일이 커진 뒤의 운영을 다룬다. 항목마다 파일을 나눠 머지 충돌을 줄이는 이유는 끝에 계속 쌓이는 문서의 머지 충돌은 항목마다 파일을 나눠 없앤다에 있어 여기서는 반복하지 않는다.

사례는 공개 저장소 nhncloud-cli의 docs/pitfalls/INDEX.md 와 fos-skills 의 review-fix 스킬에서 가져왔다.

한 문서에 쌓으면 생기는 문제

회피 패턴 문서를 하나로 두면 두 가지 비용이 커진다.

• 작업마다 관련 없는 패턴까지 컨텍스트에 올라가 토큰을 쓰고, 정작 필요한 한 줄이 묻힌다.
• 오래된 패턴을 지우려면 큰 문서 한가운데를 고쳐야 해서, 지우는 일이 점점 미뤄진다.

파일을 나누면 두 비용이 함께 줄어든다. 읽을 때는 필요한 파일만 열면 되고, 지울 때는 파일 하나를 삭제하면 된다.

구조: 카테고리 디렉터리와 INDEX 라우터

nhncloud-cli 의 docs/pitfalls/ 는 소비하는 시점에 따라 디렉터리를 나눈다.

디렉터리 이름이 곧 "누가 언제 읽는가" 이므로, 새 패턴을 어디에 둘지는 어느 단계에서 막을 수 있는 실수인지로 정해진다.

INDEX.md 는 변경 유형별로 어느 파일을 읽을지 알려 주는 라우터 표다. 에이전트는 이 표에서 작업의 변경 유형에 맞는 행을 찾아 읽을 파일을 정한다.

읽는 방법: 전부 읽지 않는다

INDEX 가 정한 소비 방식은 세 단계다.

1. INDEX 의 라우터 표에서 지금 작업의 변경 유형 행을 찾는다.
2. 그 행이 가리키는 패턴 파일만 읽고 self-check 한다.
3. 어느 행인지 애매하면 해당 카테고리 디렉터리를 통째로 읽는다.

세 번째 단계는 과소선택을 막는 안전장치다. 필요한 파일을 놓치는 비용이 몇 개 더 읽는 비용보다 크기 때문에, 애매하면 넓게 읽는다.

쌓는 조건 네 가지

새 패턴은 아래 네 조건을 모두 통과할 때만 파일로 추가한다. 하나라도 통과하지 못하면 PR 답글로 끝낸다.

세 번째 조건이 가장 자주 작동한다. 컴파일러나 테스트가 잡아 주는 실수를 문서로도 적어 두면 두 곳을 함께 고쳐야 하고, 어느 한쪽이 낡은 채 남는다.

이 기준은 review-fix 스킬의 학습 누적에도 그대로 쓰인다. 같은 실수가 다른 코드에서도 날 수 있고 grep 이나 lint 규칙으로 검출할 수 있는 패턴만 누적한다. 일회성 오타, 특정 PR 맥락에서만 성립하는 지적, 칭찬과 단순 확인은 누적하지 않는다. 누적 위치는 저장소 설정이 정하고, 지정이 없으면 docs/pitfalls/code-review/<패턴>.md 를 쓴다.

정리 주기: 추가로만 기울지 않게

규칙에 쌓는 조건만 있으면 문서는 늘기만 한다. nhncloud-cli 는 분기마다 한 번 두 가지를 점검한다.

• prune: 가리키는 코드가 사라진 낡은 파일을 삭제하고, 같은 원인을 다루는 중복 파일을 합친다.
• automate: 도구로 승격할 수 있는 패턴은 타입 검사, 테스트, ast-grep 같은 도구로 옮기고 파일을 삭제한다.

automate 는 쌓는 조건의 세 번째 "도구로 못 잡음" 과 짝을 이룬다. 처음에는 도구로 잡지 못해 문서에 적었더라도, 나중에 검사로 만들 수 있게 되면 문서를 지운다.

점검 주기는 저장소마다 정한다. nhncloud-cli 는 분기마다 점검하고, 원시 회고와 실행 통계는 별도 문서로 누적하지 않는다. 조건을 통과한 패턴만 이 디렉터리에 패턴당 한 파일로 남긴다.

패턴 파일 형식

각 패턴 파일은 frontmatter 와 본문으로 구성한다.

---
id: <kebab-slug = 파일명 stem>
category: plan | team | code-review
title: <한 줄 요약>
triggers: [<변경 유형 키워드>, ...]
tool_catchable: <true|false>
source: [<출처 PR 번호나 plan 번호>, ...]
related: [<다른 패턴 slug>, ...]
---

triggers 는 라우터가 매칭에 쓰는 키다. 변경 유형의 키워드를 적어 두면 에이전트가 grep 으로 해당 파일을 찾는다. tool_catchable 이 true 이면 도구가 잡을 수 있는데도 문서를 유지하는 이유를 본문 Why 에 적는다.

본문은 증상, Good, 검출, Self-check, Why 로 구성한다.

• 사고 사례는 하나면 충분하다. 여러 개를 나열하지 않는다.
• 왜 이 가드가 필요한지 한 줄 단서가 반드시 있어야 한다. 없으면 나중의 에이전트가 가드를 우회한다.
• 검출용 grep 을 함께 적으면 다음 작업 전에 바로 self-check 로 쓸 수 있다.

링크 규칙: 선택적 로드를 지킨다

패턴끼리 서로 참조하되, 참조가 읽는 양을 늘리면 파일을 나눈 의미가 없어진다.

• 패턴 간 참조는 본문 끝에 관련: 로 시작하는 줄을 두고 다른 패턴의 slug 를 적는다. 자동으로 로드되지 않는 grep 용 토큰이다.
• @경로 import 는 쓰지 않는다. 그 파일 내용을 통째로 포함시켜 선택적 로드를 깨뜨린다.
• 클릭할 수 있는 마크다운 링크는 INDEX 의 카테고리 목록에만 둔다.

스킬에도 생명주기가 있다

NAVER D2 의 발표 도구에서 동료로 — AI 에이전트 자율 성장 프레임워크는 성장형 에이전트가 스킬을 무제한 쌓으면 안 된다고 말한다. 발표자는 스킬에 생명주기가 있어야 한다고 보고, 단계를 다음 순서로 든다.

1. seed
2. developing
3. active
4. degrading
5. archived

발표는 보관 단계로 가는 스킬이 점진적으로 늘어나는 것을 건강한 망각이 작동한다는 신호로 본다. 이 내용은 자동 자막을 바탕으로 정리했고 수치는 발표자의 주장이다.

이 관점은 prune 과 automate 에 그대로 이어진다. 회고 루프의 품질 기준은 얼마나 많이 배웠는가가 아니라 살아 있는 규칙과 죽은 규칙을 구분했는가까지 포함한다.

정리