Imported from myokoym/aozorasearch (AGENTS.md). Install upstream with npx skills add myokoym/aozorasearch. Copyright stays with the author.

開発プロセス・ガイドライン

Plan保存ルール

• Codexが実装planを作成した場合は、必ずリポジトリ直下の .codex/plans/ にMarkdownで保存すること。
• ファイル名は YYYYMMDDHHMMSS-<topic>.md 形式とすること。
• <topic> は内容が分かる短いASCIIのkebab-caseとすること。
• 同一秒でファイル名が衝突する場合は、YYYYMMDDHHMMSS-<topic>-2.md のように末尾へ連番を付けて重複を避けること。
• plan本文は日本語で記述すること。ユーザーが明示的に別言語を指定した場合のみ、その指定に従うこと。
• planの冒頭には、詳細手順の前に 3〜5 項目の「要約」、3〜5 項目の「完了条件」、3〜5 項目の「主要マイルストーン」を置くこと。
• planは、まず人間が数十秒で判断できることを優先し、詳細手順はその後ろに置くこと。
• 実装途中の足場作りだけで完了と誤認されないように、「今回の本丸がどのマイルストーンか」を冒頭要約で明示すること。
• 長いplanでは、詳細タスクに入る前に「ここまで終わっても完了ではない」中間段階を明記すること。

調査メモとADR

• 調査メモ、比較、候補、却下理由、実装前の設計メモ・specは .codex/research/ にMarkdownで保存すること。
• 今回は実装しないが将来着手したい機能候補、運用TODO、バックログ項目は .codex/backlog/ にMarkdownで保存すること。
• 長期的に参照したい設計判断、採用理由、影響範囲は docs/adr/ にMarkdownで保存すること。
• 調査メモのファイル名は YYYYMMDDHHMMSS-<topic>.md 形式とすること。
• backlog のファイル名も YYYYMMDDHHMMSS-<topic>.md 形式とすること。
• ADRのファイル名は NNNN-<topic>.md 形式とし、NNNN は4桁の連番とすること。
• ADRには Status Context Decision Consequences References を含めること。
• ADRの References には、関連する .codex/research/ と .codex/plans/ のファイルを明記すること。
• 一時的な調査結果をすべてADRに書かず、まず .codex/research/ に保存し、長期的な判断だけをADRへ昇格させること。
• .codex/research/、.codex/backlog/、docs/adr/ に保存する本文は日本語で記述すること。ユーザーが明示的に別言語を指定した場合のみ、その指定に従うこと。
• 実装 plan に将来タスクや別件の backlog を混ぜないこと。今回の残 TODO だけを plan に書き、今回やらない項目は backlog へ分離すること。

完了定義と検証 (Verification)

• コードの変更後、必ず対象プロジェクトのテストスイートを実行し、Passすることを確認すること。
• テストが未実行、または失敗した状態でのコミットは禁止する。
• 残タスクがある間は、Codex は常に残り TODO を意識して進めること。中断時・脱線時・未完了の報告時には、残り TODO を明示すること。

環境セットアップと権限が必要な操作

• sudo や system package の導入、system Ruby/Bundler の変更、グローバルな設定変更が必要な場合は、Codexが回避策を積み上げる前に、まずユーザーに実行してもらう標準的なコマンドを提示すること。
• /tmp や一時的な環境変数での回避は、標準的な開発環境を置き換える手段として常用しないこと。どうしても必要な場合だけ、理由と影響範囲を明示して使うこと。
• ローカル検証を進める前に標準的な手順で解決できる問題は、まずその手順を優先すること。

Worktreeでの作業と本流への合流

• worktree 上で機能開発や依存更新を進めた場合は、どの base branch から分岐したかを明示すること。現状の既定は master とする。
• worktree 側で作業が完了したら、まず worktree 上で必要な検証を完了し、その結果を共有すること。
• 本流へまだ合流しない場合は、なぜ合流しないのか、残っている TODO は何か、次にどの単位で合流するのかを明示すること。
• 本流へ合流する場合は、どのコマンドで master に merge または cherry-pick するのか、合流後にどの検証を再実行するのか、worktree をいつ削除するのかまで明示すること。
• worktree を削除するのは、本流への合流と合流後の検証が完了してからにすること。
• README.md には、特定のローカル絶対パス、特定の worktree 名、特定ブランチ名に依存する一時的な作業手順を書かないこと。
• worktree の合流手順を文書化する場合は、AGENTS.md に汎用ルールとして書くか、今回タスク固有であれば .codex/plans/ または .codex/research/ に保存すること。
• 汎用的な merge の説明が必要な場合は、git checkout <base-branch>、git merge <feature-branch>、git worktree remove <worktree-path> のように placeholder で書き、環境依存の絶対パスを避けること。

Gitコミット戦略

• 機能の追加またはバグ修正が一段落し、上記の検証を通過したタイミングでコミットを実行すること。
• コミットは atomic に保ち、1コミット1論理変更を原則とすること。無関係な変更を同じコミットに混ぜないこと。
• ドキュメント更新、依存更新、機能追加、リファクタリングは、検証可能な単位でコミットを分けること。
• ライブラリ互換性問題では、まず依存更新・依存pin・設定変更・既存コードの局所修正で解決できないかを検討し、アプリ側の monkey patch や互換 patch は最終手段にすること。
• monkey patch や互換 patch を入れる前に、試した代替案と却下理由を .codex/research/ またはコミットメッセージに残すこと。特に「依存で解けるか」を先に確認すること。
• 不具合が特定の runtime path（例: /search HTML 描画、CLI の load、起動時の start）で再現している場合は、その経路を直接通す fail-first の回帰テストまたは同等の実行確認を先に作ること。近いが別の経路（例: JSON API、単純な require、周辺 helper）だけで修正確認した扱いにしてはいけない。
• review comment に suggested change がある場合は、まずその提案どおりに適用できるかを検討し、妥当なら原則そのまま採用すること。複数の妥当な対応案がある場合は、Codex が勝手に選ばず、ユーザーに確認してから進めること。
• ある変更を「今はコミットしない」と判断した場合は、その理由だけでなく、次にいつ・どの単位でコミットするのか、何が揃えばコミットするのかまで明示すること。
• 通常の保守更新から外れる特別な対応を入れる場合は、その理由をコードコメントまたはコミットメッセージのどちらかに必ず明記すること。理由が長くなる場合は、コードコメントとコミットメッセージの両方に残すこと。
• 未コミット差分がある状態で別論点の変更に着手する前に、必ず git status --short で差分を確認し、「同じコミット単位か」を明示的に判定すること。
• 同じコミット単位でない場合は、新しい変更を始める前に、先にコミットするか、stash ではなく論点ごとに分離して整理すること。
• 作業中に脱線タスクが発生した場合は、本流タスクと脱線タスクを別コミットにすることを先に宣言し、脱線タスク完了後は残 TODO を明示して本流へ戻ること。
• ブランチ移動、cherry-pick、revert、reset など履歴整理系の操作は並列実行しないこと。まず移し先 branch の存在と現在の commit を確認し、移動成功を確認してから source branch 側の更新を行うこと。
• 問題やルール違反を起こした場合は、その場で再発防止策を考え、必要なら AGENTS.md やテンプレートにルールとして追加すること。ユーザーに言われる前に自発的に行うこと。
• コミットメッセージは日本語で記述し、変更内容と検証結果を簡潔に記載すること。