모범 사례

명세

선언적으로 작성하라, 서술적으로 말고. contract:, invariant:, test:, failure: 같은 섹션을 사용하라. 번호 매긴 단계나 산문은 사용하지 않는다. 에이전트는 빠르게 읽고 정확한 선언을 따른다.

구현에 영향을 미치는 결정만 닫아라. plan에 넘기기 전에 해결할 것: 계약, 데이터 형태, 실패 모드, 테스트 기준. 철학적 논쟁과 "있으면 좋은" 기능은 deferred 또는 Working notes에 남겨라.

코드는 경로로 참조하고, 절대 붙여넣지 않는다. 명세는 무엇을 만들지에 대한 결정이지, 어떻게 만드는지에 대한 안내가 아니다.

작업은 30~60분. 에이전트가 추론할 수 있을 만큼 원자적으로. 너무 크면 가시성을 잃고, 너무 작으면 오버헤드가 흐름을 죽인다.

수락 조건은 실행 가능해야 한다. 각 작업의 수락 조건은 CI/사람이 검증할 수 있는 것이어야 한다: 테스트 이름, 명령어, 또는 스크립트. 모호하지 않고, 이상론적이지 않게.

[parallel]은 진정으로 독립적일 때만 표시. 공유 상태, 오류 처리, 또는 닫히지 않은 계약 → 작업은 병렬이 아니다. 과도한 표시는 깨진 병합으로 이어진다.

RED-GREEN-refactor 사이클마다 한 번 커밋. 생각을 히스토리에 남긴다. 나중에 디버깅할 때 도움이 된다.

각 사이클 후 문서를 동기화. 커밋 직전. 기다리면 무엇을 바꿨는지, 왜 바꿨는지 잊어버린다.

설명적인 브랜치 이름을 사용. feature1이 아닌 feat/oauth-github. 여러 worktree가 있을 때 탐색하기 쉽다.

마일스톤이 ≥3개면 로드맵을 사용. 처음부터 모두 계획하려 하지 마라. 현재 것만 plan하고, 배우면서 스텁을 업데이트하라.

현재 마일스톤을 명확하게 표시. M1에 ← 지금 상세 계획으로 의도를 나타낸다. ship 후, M2를 계획하기 전에 마커를 옮긴다.

M1 후 마일스톤을 수정할 것을 예상하라. 첫 번째 마일스톤이 나머지 비용을 가르쳐 준다. 그것이 핵심이다.

먼저 고립시키고, 다음에 가설을 세워라. 최소 재현 지점까지 좁혀라. 증상이 사라질 때까지 코드를 제거하라. 그 후에 "왜"를 물어라.

한 번에 하나의 변수만 바꿔라. 병렬 가설은 매력적이지만 어떤 변경이 수정했는지 알기 어렵게 만든다.

구현이 아닌 계약을 테스트하라. 계약이 "성공 시 200 반환"이라고 하면, 그것을 테스트한다. "X 함수 호출"이나 "데이터베이스 Y에서 읽기"가 아니다.

내부 목(mock) 사용 금지. 외부 경계를 목 처리: HTTP, DB, 파일시스템. 자신의 코드를 목 처리하는 것은 실제 버전이 느리거나 비결정적인 경우에만.

가정이 본질적으로 바뀌면, 멈추고 재탐색하라. 해결하고 있는 문제가 더 이상 문제가 아니라면 억지로 밀어붙이지 마라. 발견 노트에 시도 이유와 교훈을 기록하라.

마일스톤 목표가 ≥50% 바뀌면, 설계로 돌아가라. 계획을 연장하지 마라. 새로운 방향을 인정하고 재시작하라.

Living docs는 사실, staging docs는 초안. ship 후, 명세는 living docs로 이동한다. 코드의 테스트와 주석은 둘 다와 현재 상태를 유지한다.

README가 첫 번째 명세다. 코드와 일치하지 않으면, PR은 리뷰에서 실패한다. 같은 규칙이 모든 공개 계약에 적용된다.