# ベストプラクティス ## 仕様 **宣言的に書く、物語的にではなく。** `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から読む」ではない。 **内部のモックなし。** 外部境界をモック：HTTP、DB、ファイルシステム。自分のコードをモックするのは実際のバージョンが遅いか非確定的な場合のみ。 ## いつ諦めるか **前提が本質的に変わったら、止めて再探索する。** 解こうとしている問題がもはや問題でないなら、無理に進めない。発見ノートに試みと理由と学びをマークする。 **マイルストーンのゴールが≥50%ずれたら、設計に戻る。** 計画を延長しない。新しい方向を認め、再開する。 ## 仕様レビューの統合評価 (Spec Review Synthesis) **レビュアーは助言を行い、Coordinator が裁决を下します。** 仕様レビュアーは独立したサブエージェントとして専用の役割で動作します。主エージェント（Coordinator）は指摘事項を批判的に評価し、矛盾の解決、漏れの特定を行い、一度の変更で仕様書を修正します。 ## モデル階層マッピング (Model Tier Mapping) **タスクのリスクに応じてモデルの能力をマッチングさせます。** 機械的な修正や Lint チェックには `fast`、単一コンポーネントの実装には `balanced`、核心プロトコルや安全レビュー、複雑な状態マシンには `strongest` を使用します。`.praxis/model-tiers.yaml` で設定します。 ## マルチモジュール調整 (Multi-Module Coordination) **Coordinator リポジトリを1つ明示的に指定します。** Coordinator が change-set ID、モジュール横断仕様、ワークスペース計画を所有します。各モジュール仕様で共有契約を重複記述せず、Coordinator 仕様を直接参照します。コミットは依存関係順に行い、Coordinator が最後にコミットします。 ## ドキュメント同期 **リビングドキュメントは事実、ステージングドキュメントは下書きです。** `ship` の後、仕様はリビングドキュメントに移動します。コード内のテストやコメントは常に最新を維持します。 **README は最初の仕様書です。** コードと一致しない場合、PR のレビューは不合格となります。同じルールがすべての公開契約に適用される。