# 모범 사례

## 명세

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

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

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

## 계획

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

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

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

## Git 워크플로

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

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

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

## 대규모 프로젝트

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

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

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

## 디버깅

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

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

## 테스트

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

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

## 언제 포기할까

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

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

## 명세 리뷰 통합 평가 (Spec Review Synthesis)

**리뷰어는 조언을 제공하고 Coordinator가 최종 결정을 내립니다.** 명세 리뷰어는 전용 찰터를 가진 독립 서브에이전트로 작동합니다. 주 에이전트(Coordinator)는 지적 사항을 비판적으로 평가하고, 충돌 해결, 누락 조치를 수행하여 한 번의 패스로 명세서를 수정합니다.

## 모델 계층 매핑 (Model Tier Mapping)

**작업 위험도에 맞춰 모델 능력을 매핑합니다.** 기계적 수정이나 Lint 검사에는 `fast`, 단일 컴포넌트 구현에는 `balanced`, 핵심 프로토콜이나 안전 리뷰, 복잡한 상태 머신에는 `strongest`를 사용합니다. `.praxis/model-tiers.yaml` 파일에서 설정합니다.

## 멀티 모듈 조율 (Multi-Module Coordination)

**Coordinator 리포지토리를 하나 명시적으로 지정합니다.** Coordinator가 change-set ID, 모듈 교차 명세 및 워크스페이스 계획을 소유합니다. 각 모듈 명세에 공유 계약을 중복 정의하지 말고 Coordinator 명세를 직접 참조합니다. 커밋은 의존성 순서대로 진행하며 Coordinator가 마지막에 커밋합니다.

## 문서 동기화

**라이빙 문서는 사실이고, 스테이징 문서는 초안입니다.** `ship` 이후 명세는 라이빙 문서로 이동합니다. 코드 내 테스트와 주석은 항상 최신 상태를 유지합니다.

**README는 첫 번째 명세서입니다.** 코드와 일치하지 않으면 PR 리뷰를 통과할 수 없습니다.