개발자, 병렬 클로드 코드 세션을 위해 사양에서 제안서로 전환

명세서 우선 접근법의 문제점

개발자는 상세한 명세서를 미리 작성하면 AI가 생성한 코드가 기술적으로는 맞지만 맥락적으로는 잘못되는 문제를 겪었습니다. 명세서에는 "인증 엔드포인트에 속도 제한 추가"라고 적혀 있지만, 이전에 거부된 접근 방식(예: 토큰 버킷)이나 구현 결정(예: 스테이징 환경에서 Cloudflare 대신 Redis 선택)에 대한 맥락이 포함되지 않았습니다. 이로 인해 AI가 합리적인 선택을 하면서 이미 결정된 사항을 다시 열게 되는 상황이 발생했습니다.

명세서 업데이트 자체가 작은 프로젝트가 되었고, 업데이트된 명세서가 검토될 때쯤이면 코드베이스는 이미 달라져 있었습니다. 명세서는 "무엇"을 캡처했지만 "왜"를 잃어버렸습니다—모든 추론, 거부된 대안, 결정 시점이 누락되었습니다.

제안서 우선 대안

명세서를 미리 작성하고 그에 맞춰 코딩하는 대신, 개발자는 제안서를 작성합니다—변경이 왜 발생하는지, 무엇이 고려되고 거부되었는지, 범위에 포함되거나 제외되는 내용을 담은 짧은 문서입니다. 명세서는 실제로 구축된 내용을 반영하도록 코드가 적용된 후에 업데이트됩니다.

예시 비교:

• 명세서: "시스템은 속도 제한을 지원해야 합니다."
• 제안서: "프로덕션에서 무차별 대입 공격이 감지됨. 슬라이딩 윈도우 + Redis를 통한 속도 제한 추가(스테이징 환경에서 Cloudflare 사용 불가). 버스트 트래픽 문제로 인해 토큰 버킷은 거부됨. 범위: 로그인 + 비밀번호 재설정만."

제안서는 AI(및 미래의 개발자)에게 전체적인 그림을 제공합니다.

병렬 제안서 워크플로우

개발자는 여러 Claude Code 세션을 동시에 실행하며, 각 세션은 서로 다른 제안서를 작업합니다. 때로는 동일한 문제를 다른 각도에서 해결하는 경쟁 제안서를 만들기도 합니다.

일반적인 워크플로우:

• 동시에 2-3개의 기능/버그/이슈 작업
• 이슈당 다른 접근 방식에 대한 1-2개의 제안서 작성
• 각 제안서에 대해 Claude Code 세션을 병렬로 실행하도록 시작
• 각 세션은 GitHub PR 생성
• GitHub PR이 제안서 검토 플랫폼 역할
• 접근 방식과 코드를 함께 검토
• 두 제안서가 동일한 문제를 다르게 해결하는 경우, 더 나은 것을 선택하고 다른 것은 종료
• 승인된 PR이 적용되면, Claude에게 제안서 구현 지시
• 코드 변경 사항을 반영하여 명세서 업데이트(향후 제안서에서 빠른 참조용)

명세서는 첫날부터 벗어나는 희망 문서가 아니라 항상 현실과 일치하는 살아있는 문서가 됩니다.

PACE 사이클

개발자는 이 사이클을 PACE(단계 기억용)라고 부릅니다:

• 제안(Propose): 맥락과 추론이 담긴 짧은 제안서 작성
• 승인(Approve): GitHub PR에서 검토, 접근 방식(승인, 수정, 거부)
• 코딩(Code): AI가 제안된 내용을 정확히 구현, 추가 없음
• 진화(Evolve): 새로운 현실을 반영하도록 명세서 업데이트