ベストプラクティス

仕様

宣言的に書く、物語的にではなく。 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から読む」ではない。

内部のモックなし。 外部境界をモック：HTTP、DB、ファイルシステム。自分のコードをモックするのは実際のバージョンが遅いか非確定的な場合のみ。

前提が本質的に変わったら、止めて再探索する。 解こうとしている問題がもはや問題でないなら、無理に進めない。発見ノートに試みと理由と学びをマークする。

マイルストーンのゴールが≥50%ずれたら、設計に戻る。 計画を延長しない。新しい方向を認め、再開する。

Living docsは事実、staging docsは草稿。 ship 後、仕様はliving docsに移動する。コードのテストとコメントは両方と現在の状態を保つ。

READMEは最初の仕様。 コードと一致しなければ、PRはレビューで失敗する。同じルールがすべての公開契約に適用される。