게임을 만들면서 알게 된 것들을 방법론 문서 하나에 모으고 있습니다.

문제는 제가 그걸 계속 갱신하지 못한다는 거였어요. 그래서 매주 게임 저장소들의 변화를 읽고 문서를 직접 고치는 회고 에이전트를 붙였습니다.

2026년 7월 25일에 v1.0으로 시작해서 12일 만에 v1.37.0이 됐습니다. 커밋은 57개고요.

그런데 잘 굴러간 부분보다 되돌린 것들이 기억에 남아서, 그것만 적어봅니다.

1. GitHub Actions를 걷어내고 로컬로 바꿨습니다

처음엔 주간 회고를 GitHub Actions 워크플로로 걸어놨습니다.

이게 ANTHROPIC_API_KEY 시크릿을 요구했는데, 저장소에 시크릿이 없었어요. 그래서 매주 그냥 건너뛰었습니다. 한참 뒤에야 알았습니다.

7월 27일에 로컬 실행기(scripts/retro.mjs)로 바꿨습니다. 헤드리스로 claude -p를 띄우고, 이 기기에 이미 로그인돼 있는 Claude Code 인증을 그대로 씁니다. 키를 새로 발급받을 이유가 없더라고요.

지시서(RETRO.md)도 .github/ 아래에서 저장소 루트로 꺼냈습니다. 문서를 고치는 규칙이 스케줄러 설정 안에 숨어 있으면 diff에도 안 잡히고 리뷰도 못 하니까요.

2. “푸시하지 마라”를 프롬프트에서 권한 파일로 옮겼습니다

회고 에이전트는 커밋까지만 하고, npm test를 통과한 커밋만 실행기가 밀도록 했습니다.

처음엔 이걸 지시서에 문장으로만 적어놨어요. 지금은 권한 파일(.claude/retro-settings.json)의 deny 목록에 들어가 있습니다. git push, reset, rebase, checkout, gh pr/release/secret이 전부 막혀 있어요.

실제로 사고가 났던 건 아닙니다. 다만 검사보다 먼저 밀어버리면 그 검사는 아무 의미가 없어지는데, 그걸 부탁으로 남겨두는 게 계속 마음에 걸렸습니다.

3. --force가 반쪽이었습니다

같은 주에 두 번 돌지 않도록 커밋 마지막 줄에 Retro-Run: 2026-W32 같은 트레일러를 답니다. 실행기가 이걸 찾아보고 이미 있으면 바로 종료해요.

어제 강제 재실행(--force)을 처음 돌려봤는데 아무 일도 안 일어났습니다. 가드가 두 겹이었더라고요.

1. 실행기의 트레일러 검사 → --force로 뚫림
2. 에이전트가 지시서를 읽고 “표식이 있으니 멈춘다”고 판단 → 안 뚫림

지시서에 트레일러를 “두 번 도는 걸 막는 표식”이라고만 써둔 게 원인이었습니다. 에이전트는 그걸 자기가 쓰는 표식이 아니라 자기가 검사할 관문으로 읽었어요. 그 판단 자체는 지시서에 충실했습니다.

멈추는 근거를 표식이 아니라 내용(이미 반영됐는가)으로 바꿔서 고쳤습니다. 판정하는 곳이 둘이면 재실행 경로가 이렇게 조용히 막히더라고요.

4. 주당 건수 상한을 지웠습니다

회차마다 2~3건까지만 반영하고 나머지는 사람이 볼 대기열로 넘기게 해뒀습니다.

그런데 대기열을 열어보니, 판단이 필요해서 올라온 게 아니라 그냥 순서가 밀려서 대기 중인 항목이 4개였어요. 상한을 없애고 근거 기준만 남겼습니다. 실제 커밋과 줄 번호로 가리킬 수 있는가, 다음 게임에도 통하는가, 이미 있는 내용의 재탕은 아닌가.

💡 팁 / 주의할 점

• 팁: 에이전트에게 지키게 할 규칙은 프롬프트보다 권한 설정 파일 쪽이 편합니다. 프롬프트는 잘 지켜지더라도 매번 확인해야 하는데, deny는 확인할 일이 없어요.
• 주의할 점: 합본 문서는 생성물입니다. 에이전트가 합본을 직접 고치면 정합성 테스트가 깨져요. 장별 원본만 고치고 빌드로 다시 만들게 해두면 어긋나는 순간 CI가 잡아줍니다.

정리

제일 마음에 드는 규칙은 따로 있습니다. 승격할 교훈이 없으면 아무것도 커밋하지 않는 것.

빈 주는 정상이에요. 매주 뭐라도 써내라고 시켰으면 문서가 지금쯤 훨씬 두껍고 훨씬 쓸모없어졌을 거라고 생각합니다.

---

태그: #AI개발, #클로드코드, #에이전트, #자동화, #문서화, #깃허브액션, #CI, #게임개발, #방법론, #회고