ベストプラクティス
仕様
宣言的に書く、物語的にではなく。 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 のレビューは不合格となります。同じルールがすべての公開契約に適用される。