하네스 회고는 새 문서로 쌓지 않고 종류에 맞는 기존 단일 소스에 환원한다

에이전트 파이프라인을 돌리면 평가자들이 지적을 계속 만들어 낸다. 이 지적에서 얻은 교훈을 retrospectives/ 같은 새 문서에 쌓기 시작하면, 그 문서가 또 하나의 낡아 가는 문서가 된다. 이 글은 회고 결과를 새 문서가 아니라 이미 단일 소스 역할을 하는 문서에 직접 환원하는 구조를 정리한다. 평가자 역할마다 환원 위치가 다른 이유, 일회성 지적을 거르는 기준, 별도 회고 문서와 실행 기록을 도입했다가 제거한 사례를 다룬다.

회피 패턴 문서를 파일로 나눠 운영하는 방법은 에이전트가 배운 회피 패턴은 조건을 통과한 것만 파일로 쌓고 주기적으로 지운다에 있다. 이 글은 그 앞 단계, 즉 지적이 어디로 흘러가야 하는가를 다룬다.

회고 문서가 또 하나의 낡는 문서가 된다

회고를 docs/retrospectives/ 에 사건별로 남기면 처음에는 편하다. 그런데 회고 산출물이 또 하나의 문서가 되면 그 문서가 새로운 rot 소스가 된다. 회고에서 나온 규칙은 이미 그 규칙을 소유한 문서에 있어야 에이전트가 그 문서를 읽을 때 만난다. 별도 회고 파일 속에 있으면 코드와 지침이 바뀌어도 함께 갱신되지 않는다.

거울 구조: 지적한 역할이 환원 위치를 정한다

회고를 평가자 역할별로 나누면 환원 위치가 자연스럽게 정해진다. 누적 대상이 역할마다 다르기 때문이다.

이 표의 핵심은 회고 산출물을 별도 문서로 만들지 않는다는 점이다. 평가자가 쓰는 점검표와 회고가 환원되는 문서가 서로 거울처럼 대응하므로 거울 구조라고 부른다. docs-verifier 의 점검 항목은 기획 문서의 영향 표를 그대로 비춘 것이어서, 별도 체크리스트를 새로 만들지 않는다.

각 역할의 회고 절차는 같은 골격을 갖는다.

• 트리거: 해당 평가자가 한 번 이상 지적하면 의무로 실행하고, 한 번에 통과하면 건너뛴다. 지적이 0건이어도 자문한다.
• 반복 가능성 판정: 앞 글의 쌓는 조건 네 가지를 적용한다.
• 갱신 위치: 역할마다 다른 단일 소스다.
• 작성 형식과 커밋 규약: 회고 커밋은 작업 브랜치에서 PR 에 포함하고, main 에는 직접 커밋하지 않는다.

현재의 환원 위치 표

공개 저장소 fos-skills 의 build-with-teams 스킬은 마감 단계의 references/step-finish.md 에서 환원 위치를 표로 정한다.

여기에 오르려면 세 가지를 모두 만족해야 한다.

• 다른 plan 이나 코드에서도 다시 일어날 수 있다.
• 원인과 회피 방법이 특정 사건을 떠나 일반화된다.
• grep, lint, test, build 처럼 구체적인 검출 방법이 있다.

1회성 오타, 특정 plan 의 상황 설명, 단순 실행 통계는 PR 본문과 결과 보고에만 남긴다. 같은 스킬의 review-fix 도 같은 원칙으로, 리뷰 반영 뒤 재현 가능한 패턴만 docs/pitfalls/code-review/<패턴>.md 에 누적한다.

별도 회고와 실행 기록은 제거했다

fos-skills 는 한때 회고와 실행 기록을 별도 문서로 두었다. 이 구성의 설계를 남겨 둔다. 정리 이유는 뒤에서 다시 다룬다.

실행 기록의 핵심 열은 사용자 개입 횟수였다. critic 의 REVISE 횟수 같은 값은 파이프라인 내부 지표이고, 사용자가 실제로 겪은 비용은 개입 횟수라는 판단이다. 스킬이 나아졌다는 말은 결국 사용자가 덜 끼어들어도 된다는 뜻이기 때문이다.

개입 횟수는 두 가지를 센다.

• 구조화 질문 도구를 호출해 사용자 판단을 받은 횟수
• 사용자가 진행 방향을 바로잡거나 결과를 되돌리게 한 횟수

사용자가 먼저 꺼낸 새 요구와 단순한 진행 승인은 세지 않는다.

회고는 기록 시점도 정했다. 종료까지 미루지 않고 phase 종료, FIX_NEEDED, 검증 정체 직후에 남겨야 사건의 맥락이 휘발되지 않는다는 이유였다.

소비처가 없는 기록은 제거한다

fos-skills 의 git 이력에서 확인되는 순서는 다음과 같다.

evaluation/ 을 제거한 커밋 메시지는 이유를 적고 있다. 누적 점수를 소비하는 곳이 없었다는 것이다. 회고와 실행 기록을 제거한 커밋에는 이유가 적혀 있지 않다. 다만 제거 뒤 남은 규칙은 앞 절의 표와 같다. 재사용할 가치가 있는 것은 단일 소스로 환원하고, 나머지는 PR 본문과 결과 보고에만 남긴다.

이 순서에서 얻을 수 있는 판단 기준은 하나다. 기록을 쌓기 전에 그 기록을 누가 언제 읽는지 정한다. 읽는 쪽이 없는 기록은 낡을 문서만 늘린다. 반대로 읽는 쪽이 이미 정해진 곳, 즉 기존 단일 소스에는 환원해도 낡을 문서가 늘지 않는다.

정리