여러 에이전트에게 설계·구현·검증을 나눠 맡겨 한 차례 진행하는 과정을 이 글에서는 라운드라고 부른다. 라운드가 끝난 뒤 어디서 막혔고 무엇이 늦었는지 회고 문서에 적었다. 마지막에는 “다음에는 검증부터 실행하자”는 제안도 덧붙였다.
하지만 다음 라운드에서 회고 문서를 읽은 에이전트는 없었다. 작업 절차에 회고를 읽는 단계가 없었기 때문이다. 회고를 써 두면 다음 라운드가 달라진다고 보기 쉬운데, 그 문서를 읽을 주체가 정해져 있지 않으면 아무 일도 일어나지 않는다.
에이전트가 읽는 건 자기 정의 파일과 자기가 부른 스킬 문서뿐이었다. 회고 문서는 읽지 않았다.
다음 라운드를 바꾸려면 그 파일들을 고쳐야 했다. curvez의 retrospective 스킬이 그 방법을 정해 놓았다.
1. 회고를 읽는 건 사람이 아니다
이 스킬은 회고에 무엇을 적을지를 SKILL.md 첫 줄에서 정한다.
회고의 산출물은 규약 수정안이다. 감상이 아니다.
규약은 에이전트가 읽고 따르는 규칙 문서다. 회고에는 그 문서를 어떻게 고칠지 적어야 한다.
다음 라운드의 에이전트가 읽을 것이므로 어느 파일의 어느 섹션을 어떻게 고칠지가 있어야 한다. 그게 없으면 다음 라운드는 그대로다. “다음엔 꼼꼼히 하자”는 어느 파일도 바꾸지 않는다.
그래서 넣지 말라고 못 박은 문장 목록이 따로 있다.
| 넣지 않는다 | 대신 |
|---|---|
| “소통이 부족했다”, “다음엔 더 꼼꼼히” | 어느 파일의 어느 섹션에 어떤 조건문을 넣을지 |
| “A가 실수했다” | 그 상황을 다루는 문장이 규약에 있었는지 |
| “전반적으로 잘 진행됐다” | 삭제. 판정에 쓰이지 않는다 |
| “앞으로 주의하자” | 기계가 잡을 검증 명령 |
표 1. 회고에 넣지 않는 문장과 그 자리에 들어갈 것
두 번째 행에 이유가 하나 더 붙어 있다. 누가 못했는지가 회고에 적히면 다음 라운드의 인수인계 기록에서 실패한 시도와 확인 못 한 항목이 빠진다. 통과한 명령만 남은 로그가 회고의 유일한 증거가 된다.
2. 무엇을 증거로 삼나
이 스킬은 기억으로 회고를 쓰지 못하게 한다. 증거로 쓸 파일이 정해져 있다. 그중 둘은 없으면 시작 자체를 막는다.
하나가 핸드오프다. 에이전트가 일을 마칠 때 남기는 인수인계 JSON 인데, 자유 서술이 아니라 status·decisions·verification 같은 칸이 미리 정해져 있다. 그 칸을 어떻게 정했는지는 에이전트의 작업 완료 기준과 인수인계 형식 정하기 에 적었다. 칸이 정해져 있으니 회고에서도 grep으로 증거를 찾을 수 있다.
| 경로 | 필수 | 없을 때 |
|---|---|---|
.curvez/profile.json |
O | status: blocked |
.curvez/handoff/*.json |
O | status: blocked. 회고 문서를 만들지 마라 |
docs/retro/*.md (이전 회고) |
X | 반복 항목 승격을 못 한다는 점을 summary에 남기고 진행 |
| 지목할 규약 파일 | O | 실제로 열어 섹션이 있는지 확인한다. 못 열면 액션 아이템이 아니다 |
표 2. 회고의 증거 파일과 없을 때의 처리
두 파일이 있는지부터 세고 시작한다.
test -f .curvez/profile.json || echo "BLOCKED: profile.json 없음"
ls .curvez/handoff/*.json 2>/dev/null | wc -l # 0 이면 BLOCKED
증거 없이 쓴 회고는 그냥 의견이다. 의견을 규약에 올리면 있지도 않았던 문제를 막는 규칙이 생기고 다음 라운드는 그것까지 지키느라 늦어진다. 그래서 로그가 없으면 문서를 아예 쓰지 않는다.
날짜도 추측하지 않는다. 회고 파일명의 날짜는 date +%F로, 핸드오프 파일명의 시각은 date +%Y%m%d-%H%M%S로 확인한다. 모델은 오늘 날짜를 세션마다 다르게 답하는데, 날짜가 틀리면 docs/retro/의 정렬이 어긋나 다음 회고가 “이전 라운드”를 못 찾는다. 반복 판정이 무력해진다.
그다음이 본론이다. 핸드오프를 시간순으로 전부 읽는다. 요약본을 만들지 말고 원본을 읽으라고 적혀 있다.
ls -1 .curvez/handoff/*.json | sort
읽으면서 뽑는 신호도 정해져 있다. status: blocked는 실행이 멈춘 지점이라, 무엇을 누구에게 묻고 있었는지(blocked_on[].question, who)를 본다. verification이 비었거나 그 안의 result가 “통과”·”확인함”이면 돌려 보지 않고 완료라고 적은 것이다. 뒤 핸드오프의 decisions.what이 앞 결정을 뒤집었다면 아무에게도 알리지 않고 설계를 바꾼 것이다. 서로 다른 from의 artifacts[].path가 겹치면 두 에이전트가 같은 파일을 건드렸다. to가 비었거나 없는 이름이면 다음 담당이 안 정해진 채 끝난 것이다. 같은 질문이 여러 파일에 나오면 반복 지적이고, 타임스탬프 간격이 유난히 긴 구간은 대기하거나 다시 만든 구간으로 본다.
뽑은 것마다 파일 경로를 함께 적는다. 로그에 없는 것은 ## 확인 불가에 남긴다. 기억이나 추론으로 채우지 않는다. 스킬은 “확인 불가”를 실패가 아니라 정상 산출물이라고 부른다. 다음 라운드에 무엇을 더 남겨야 하는지를 알려주기 때문이다.
3. 한 번뿐인 일은 왜 안 올리나
읽고 나면 어긋난 지점이 여러 개 나오는데, 전부를 액션 아이템으로 올리지는 않는다. 액션 아이템은 “이 파일의 이 섹션을 이렇게 고쳐라” 하는 한 건짜리 지시다.
반복될 것만 규약을 고친다. 한 번 일어난 일은 기록만 한다. 일회성 이슈마다 규칙을 붙이면 규약 문서가 계속 길어진다. 너무 길어지면 아무도 끝까지 안 읽고 중요한 규칙 몇 개도 함께 놓친다.
반복 판정 기준은 셋이다. 서로 다른 핸드오프 2건 이상에서 같은 원인이면 반복이다. 이전 회고에 같은 항목이 있으면 반복이고 우선순위도 올린다. 1건이라도 재발 시 되돌리기가 불가능하면 반복으로 친다.
부속 문서 references/action-item-examples.md에 애매한 사례가 붙어 있다. 구현 담당 curvez-nextjs와 검증 담당 curvez-qa가 같은 토큰 파일이 없다고 각각 막혔다면 반복이다. 서로 다른 에이전트가 같은 지점에서 막혔으니 규약에서 원인을 찾는다. 반면 한 에이전트가 verification을 빼먹은 핸드오프 1건은 일회성이다. 규약에 이미 있고 1건이니 기록만 한다. 다음 회고에서 재발하면 그때 승격한다. 설계 결정이 구현 중 뒤집힌 경우는 다르다. 후행 산출물 3개가 그 위에 쌓였다면 1건인데도 반복으로 올린다. 이때는 빈도보다 기댓값을 기준으로 삼는다.
애매하면 일회성으로 내린다. 반복이 아닌 것을 규약에 올리는 비용은 영구적이다. 반복인 것을 놓치는 비용은 한 라운드다.
4. 고칠 위치로 인정되는 것
이제 관찰 하나마다 실제 파일을 열어 판정해 보자. 그 상황을 다루는 문장이 정의·스킬 문서에 있었나가 기준이다.
| 확인 결과 | 판정 | 고치는 방식 |
|---|---|---|
| 그런 문장이 없다 | 규약의 공백 | 문장을 추가한다 |
| 있는데 적용 여부가 즉시 안 보인다 | 규약의 모호함 | 서술을 조건문으로 바꾼다 |
| 있고 명확한데 안 지켜졌다 | 규약의 무력함 | ## 품질 자체 검증에 실행 가능한 명령을 추가한다 |
표 3. 규약 확인 결과별 판정과 고치는 방식
실제로 강제력을 더할 수 있는 건 세 번째 줄이다. “규약은 충분했는데 지키지 않았다”가 반복되면 문장을 한 번 더 쓰지 말라고 되어 있다. 사람이 읽고 지키는 규칙과 기계가 잡는 규칙은 강제력이 다르다. 부속 문서의 예는 이렇다. verification이 빠진 핸드오프를 세는 grep -L '"verification"' .curvez/handoff/*.json을 “출력 0건” 체크박스와 함께 정의 파일에 넣고 다음 라운드가 끝난 뒤 같은 명령의 출력을 본다.
고칠 위치로 인정받으려면 파일 경로와 섹션 헤딩을 둘 다 적어야 한다.
- **고칠 위치:** `plugins/curvez/agents/curvez-qa.md` 의 `## 품질 자체 검증`
- **고칠 위치:** `plugins/curvez/skills/quality-gate/SKILL.md` 의 `## 완료 기준`
이 줄을 받아 파일을 고칠 에이전트가 위치를 찾을 수 있도록 범위를 좁힌다. 경로와 섹션 이름이 둘 다 있으면 파일을 열어 그 자리에 문장을 넣으면 된다. 하나라도 빠지면 어디를 고칠지부터 다시 판단해야 하고 그 판단은 부를 때마다 다르게 나온다.
인정되지 않는 것도 예로 나열해 뒀다. “핸드오프 규약”과 “팀 전체의 검증 문화”는 아예 파일이 아니고 curvez-qa.md만 쓰면 경로도 섹션도 없어 500줄 문서에서 자리를 다시 찾아야 한다. “plugins/curvez/agents/curvez-qa.md 전반”도 안 된다. “전반”은 위치가 아니다. 이런 것은 액션 아이템이 될 수 없고 ## 어긋난 지점에만 남는다.
지목한 직후에 그 섹션이 정말 있는지 확인한다.
grep -n '^## 품질 자체 검증' plugins/curvez/agents/curvez-qa.md
없으면 비슷한 이름의 다른 파일로 바꿔 달지 않는다. ## 확인 불가에 “지목 대상 파일 없음”으로 내린다.
5. 액션 아이템은 최대 7건으로 제한한다
우선순위는 네 단계다. P0은 잘못된 전제 전파, P1은 실행 중단이다. P2는 비용 증가, P3는 읽기 어려움이다.
상한은 한 회고당 7건이다. 넘으면 P0부터 7건까지만 올린다. 나머지는 ## 이번엔 올리지 않은 것에 이유와 함께 남긴다. 액션 아이템 20건은 0건과 같다는 게 이유다. 다음 라운드 전에 아무도 다 못 고친다. 못 고친 목록이 남으면 회고 자체가 신뢰를 잃는다.
그 7건을 적는 형식도 굳어 있다.
### A1. <한 줄 제목> — P0
- **무엇이 어긋났나:** <사실만>
- **증거:** `.curvez/handoff/<파일>.json`
- **왜 어긋났나:** <규약의 어느 부분이 비었는가>
- **고칠 위치:** `plugins/curvez/agents/curvez-qa.md` 의 `## 품질 자체 검증`
- **어떻게 고치나:** <추가·삭제·교체할 내용을 문장 수준으로>
- **우선순위:** P0
- **검증 방법:** <고친 뒤 무엇을 돌리면 고쳐졌다고 판정하나>
세 문자열은 표기를 바꾸지 말라고 되어 있다. ### A<n>., - **고칠 위치:**, - **증거:** 다. 이 문자열을 grep으로 찾는 쪽이 둘이다. 회고자의 자체 검증 명령과, 회고를 받아 실제 수정을 주관하는 curvez-orchestrator의 수신 절차다. 한쪽만 고치면 검증은 0건을 세고 통과하는데, 오케스트레이터는 액션 아이템을 하나도 못 찾아 “고칠 것 없음”으로 라운드를 닫는다. 그래서 형식을 바꾸고 싶으면 회고 문서가 아니라 두 정의 파일을 함께 고치는 액션 아이템으로 올린다.
6. 자체 검증을 통과해야 완료로 기록한다
문서를 다 쓰면 자기 산출물을 스스로 센다.
A=$(grep -cE '^### A[0-9]+\.' "$RETRO") # 액션 아이템 수
W=$(grep -cE '^- \*\*고칠 위치:\*\*' "$RETRO") # A 와 같아야 한다
E=$(grep -cE '^- \*\*증거:\*\*' "$RETRO") # A 와 같아야 한다
항목 수와 “고칠 위치” 줄 수와 “증거” 줄 수, 이 셋이 같아야 한다. 여기에 지목한 규약 파일과 증거로 든 핸드오프를 test -f로 열어 없는 경로가 몇 개인지 센다. A ≤ 7, A = W, A = E, 없는 파일 0건. 넷이 다 맞아야 PASS 다. FAIL이면 status를 done으로 올리지 못하고 partial로 낮춰 위 수치를 verification에 적는다.
이 시리즈를 쓰면서 curvez 문서 자체에서 다섯 건이 나왔다. 같은 판정선이 두 파일에 다른 값으로 적혀 있던 것, description이 약속한 항목이 본문에 없던 것. 그리고 근거가 안 붙은 기준값 하나와 문서에 아예 빠져 있던 항목 둘이다. 회고에서도 어느 파일 어느 줄이 무엇과 어긋났는지까지 목록으로 적는다. 그래야 받은 쪽이 바로 고칠 수 있다.
7. 도입 비용과 한계
| 무엇을 내주는가 | 어떻게 나타나는가 |
|---|---|
| 라운드가 하나 더 든다 | 회고는 수정안까지만 낸다. 실제 편집은 curvez-orchestrator가 사용자 승인을 받아 authoring-agents / authoring-skills로 한다 |
| 로그 밖의 일은 회고가 못 본다 | 핸드오프에 안 남은 것은 전부 ## 확인 불가로 간다 |
| 일회성 이슈는 규약에 안 남는다 | 재발해야 승격된다. 그 사이 한 라운드는 같은 방식으로 실패한다 |
| 형식이 굳는다 | 마커 세 개를 바꾸려면 회고자와 오케스트레이터 정의를 함께 고쳐야 한다 |
표 4. 회고 규약이 내주는 것
첫 줄의 부담이 가장 크다. 회고 도중에 정의를 고치면 이번 라운드의 증거와 정의가 어긋나 “그때 정의가 무엇이었나”를 복원할 수 없게 된다. 그래서 고치지 않고 넘긴다. 대신 승인이 늦으면 다음 라운드가 옛 규약으로 돌아간다.
검증 스크립트가 확인할 수 있는 범위도 제한적이다. 지목한 파일이 실재하는지까지는 세지만 그 섹션이 정말 그 원인의 자리였는지는 판정하지 못한다. 위치를 잘못 짚었다는 사실은 다음 회고가 같은 항목을 반복으로 올릴 때에야 드러난다. 그래서 부속 문서에 “이전에 지목한 위치를 다시 지목하지 마라”는 한 줄이 따로 적혀 있다. 같은 자리를 또 지목했다는 건 그 자리가 원인이 아니었다는 뜻이다.
회고는 다 적었다고 끝나지 않는다. A = W = E와 없는 경로 0건이 맞아야 done을 쓴다.
답글 남기기