🤖
1858 in / 2000 out / 3858 total tokens
AI 에이전트가 맘대로 코드 갈아엎는 걸 막으려고, coder.md에 17단계 하드코어 절차를 박아넣었다. 기존 10단계도 헐거웠는데, 사전 탐색 6단계 + 구현 3단계 + 검증 8단계로 쪼갰다. CLAUDE.md에는 Brain/Hands 투트랙 다이어그램을 추가해서 에이전트 전체 파이프라인이 한눈에 보이게 정리했다.
가장 큰 변화는 coder.md의 실행 절차 재구성이다. 예전엔 '구현 전/중/후' 세 구간에 10단계가 대충 나뉘어 있었다. 실제론 에이전트가 구현 전 탐색을 대충 넘기고 바로 코드 짜기 시작하는 게 문제였다. 그래서 사전 탐색을 6단계로 독립시켰다 — 파일 읽고, 호출부 grep하고, 유사 구현 찾고, 의존성 추적하는 걸 체크리스트처럼 강제했다. UE5에서 모듈 의존성 빌드 에러 나는 거랑 같은 맥락이다. 빌드 타임에才发现하는 것보다 사전에 다 뒤져보는 게 낫다.
CLAUDE.md에 추가한 하네스 구조도가 핵심이다. Brain 트랙(계획)과 Hands 트랙(개발)이 impl 문서를 경계로 연결되는 구조를 ASCII 아트로 그렸다. 게임 서버 아키텍처 설계할 때 클라이언트-서버 경계를 명확히 하듯, AI 에이전트 파이프라인에서도 계획과 실행의 경계를 명시한 것이다. 계층 테이블에는 트리아지 → Scout → Coder → Reviewer → QA 흐름을 파일 단위로 매핑했다. 나중에 어느 계층에서 문제 터졌는지 추적하기 쉽게 하려는 의도다.
17단계 절차에서 특히 신경 쓴 건 검증 8단계다. 함수 시그니처 일치 확인, node -c 문법 체크, 영향 범위 게임별 리포트, 브라우저 QA 체크리스트까지 포함했다. Socket.IO 기반 멀티플레이어 게임 서버 특성상, 한 번 핸들러 시그니처 잘못 바꾸면 클라이언트-서버 간 프로토콜이 깨진다. UE5에서 RPC 함수 시그니처 안 맞으면 크래시 나는 거랑 똑같은 문제다. 자동 테스트 작성이 불가능한 경우엔 그 이유까지 명시하도록 강제했다 — 테스트 못 짜는 걸 숨기면 안 된다.
이 변경은 이전 커밋에서 Scout 패턴 인식을 추가한 것과 맞물려 있다. Scout가 프로젝트 패턴을 찾아주면, Coder는 그 패턴을 따르면서 17단계를 밟아야 한다. 패턴은 Scout가, 절차는 coder.md가, 불변조건은 CLAUDE.md가 각각 통제하는 구조다. 책임 분리를 에이전트 레벨에서 적용한 셈이다.
계획 (Brain) 개발 (Hands) /meeting-codex 자동 트리아지 Claude ↔ Codex 토론 Scout → Coder → Reviewer → QA ↓ ↑ impl 문서 ──── 사용자 승인 ────→ 입력
AI 에이전트 제어는 컴파일러처럼 — 통과하지 못하면 다음 단계로 못 간다.