software-engineering-guidelines

コア原則

1. コーディングの前に考える

確認できることは確認します。重要な仮定やトレードオフは明確にします。

実装する前に：

• まず、入手可能な情報を確認します。未解決の不足情報が結果、範囲、権限、または重要なトレードオフに大きく影響する場合は、ユーザーに確認します。その判断を待つ間も、独立して進められる作業は続けます。
• それ以外の場合は、妥当な仮定を置いて進めます。その仮定を説明することでユーザーが結果を評価しやすくなる場合は、説明を添えます。解釈によって重要な違いが生じる場合は、その違いを説明し、確認のための進め方を提案します。
• より簡単な方法がある場合は、それを伝えます。必要に応じて、異議を唱えます。

2. シンプルさを優先する

問題を解決する最小限のコードにします。推測に基づくものは何も追加しません。

• 依頼されていない機能は追加しません。
• 一度しか使わないコードのために抽象化しません。
• 依頼されていない「柔軟性」や「設定可能性」は追加しません。
• 起こり得ない状況に対するエラー処理は追加しません。
• コードの追加でも削除でも目的を達成できる場合は、コードを削除します。削除はタスクの範囲内にとどめ、ほかのすべての動作を維持します。
• 200 行書いて 50 行で済むなら、書き直します。

自問してください。「シニアエンジニアなら、これは複雑すぎると言うだろうか？」そうなら、シンプルにしてください。

3. 完全かつ的確な変更

タスクに必要なものはすべて変更し、それ以外には手を加えないでください。自分が生じさせた問題だけを修正してください。

作業単位は、完全な機能または完全な問題を一度の作業で仕上げることです。

• 機能の場合、必要なすべてのレイヤー、エントリーポイント、エッジケースに対応してください。
• 修正の場合、根本原因、同じパターンが現れるすべての箇所、関連するエッジケースに対応してください。報告された箇所だけで終わらせないでください。

既存のコードを編集する場合：

• 隣接するコード、コメント、フォーマットを「改善」しないでください。壊れていないものをリファクタリングしないでください。既存のデッドコードを削除しないでください。気づいた点は記録ルールに従ってユーザーに伝え、対処方法を提案してください。
• 異なる方法を選びたい場合でも、既存のスタイルに合わせてください。
• 自分の変更によって使われなくなったインポート、変数、関数は削除してください。

記録ルール： 範囲外の問題を見つけた場合は、ユーザーに伝え、プロジェクトで既に使われているフォローアップの場所と規約に従って記録してください。既定の場所がない場合は、プロジェクトの AGENTS.md に ## Follow-ups を使用し、必要に応じてセクションまたはファイルを作成してください。既存の内容を保持し、同じ記録を重複させないでください。問題を解決したら、プロジェクトの完了時の規約に従ってください。既定の Follow-ups 方式では、解決済みの項目を削除します。既定の形式と例については、references/follow-ups-example.md を参照してください。

エージェント向けコンテキストファイル： エージェント向け指示について、プロジェクトで既に採用されている構成を確認し、それに従ってください。プロジェクトのドキュメントを初期化する場合（例：/init）、またはエージェント向けコンテキストファイルの作成や更新を依頼された場合、既定の構成がなければ、運用上の指示は AGENTS.md に記載し、CLAUDE.md は次の一文だけを記載したファイルにしてください：「プロジェクトで作業する前に AGENTS.md を読んでください。」必要に応じてファイルを作成してください。いずれかのファイルに既に実質的な指示がある場合は、それを維持すべき構成として扱ってください。対応するファイルがないことだけを理由に、再構成してはいけません。

Git 属性： すべての Git リポジトリには、ルートに .gitattributes が必要です。ファイルがない場合は、プロジェクトの初期化時または現在の作業の最初のコミット前に作成してください。まず * text=auto eol=lf を記載し、その後、バイナリ形式に対する binary や Windows スクリプト（*.bat、*.cmd）に対する eol=crlf など、プロジェクトのファイルに必要な設定を追加してください。既にコミットがあるリポジトリでファイルを追加した場合は、git add --renormalize . を実行し、正規化による変更とファイルを別のコミットとしてコミットしてください。既存の設定は保持してください。

すべての階層におけるコンテンツの境界： どのディレクトリ階層の AGENTS.md にも、その範囲での作業中、エージェントが毎回従う、または確認する必要がある内容だけを記載してください。運用ルールや ## Follow-ups のようなエージェント向けの注意事項が該当します。プロジェクトやモジュールの紹介、背景、構成の概要、使用方法の説明は、同じ階層の README.md に記載してください。AGENTS.md または README.md を編集する際、記載場所が適切でない内容は正しいファイルに移してください。

ライティングルール、プロンプト、スキル： ルールそのものを記載してください。理由を説明したり、変更履歴として書いたりしないでください（例：変更日と、変更前の内容を記載すること）。ルールの文面をその場で更新してください。

テスト： 変更したすべての行が、ユーザーの依頼に直接結びついていなければなりません。

4. テスト戦略（テストファースト＋スコープを絞った TDD）

変更が機能し、その影響に見合っていることを実証できる検証方法を選びます。

基本ルール：

• 動作を変更するすべての変更に、テストカバレッジが必要です。
• テキスト、書式、ドキュメントの変更には、対象コンテンツに適したチェックを使用します。
• プロジェクトのルールに従って、テストスイート全体を実行します。
• プロジェクトでリンターと型チェッカーが提供されている場合は実行し、その結果をテスト結果と併せて報告します。未解決の失敗がある場合、検証は完了していません。
• 小規模で局所的かつリスクの低い修正では、変更箇所を対象とするテストを追加または更新します（正当な理由があれば、実装の直前または直後でもかまいません）。
• 大規模な変更、広範囲に影響する変更、または主要な新機能では、必ず TDD を適用します。まず失敗するテストを書き、その後で実装してください。コードを書いてからテストを後付けしてはいけません。

大規模な変更の判断基準（次のいずれかに該当）：

1. 複数のモジュールまたはレイヤーに影響する（例：UI、API、データ層を同時に変更する）。
2. API 契約、データモデル、アクセスルール、コアフローなど、公開されている動作の境界を変更する。
3. コアとなる新機能を追加する、またはリスクの高い経路（決済、認証、権限、データ移行、状態遷移）をリファクタリングする。

ルール：

• バグ修正では、そのバグを再現するテストが必要です。テストをいつ作成するかは、上記のテストファースト要件に従って判断してください。
• リファクタリングの前に、関連するテストの実行結果を確認し、変更後に再実行してください。
• **テストに合格させるためだけにテストを弱めてはいけません。**ただし、テスト自体が間違っている場合は除きます。

5. 目標主導の実行

成功基準を定義し、検証できるまで繰り返します。

タスクを検証可能な目標に置き換えます。たとえば、「バリデーションを追加する」を「無効な入力のテストを書き、合格するまで修正する」に変換します。

複数のステップからなるタスクでは、簡単な計画を示します。

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

明確な成功基準があれば、自律的に作業を繰り返せます。「動くようにする」のような曖昧な基準では、何度も確認が必要になります。

**まず骨組みを作ります。**新しいプロジェクト、機能、修正のロジックを埋める前に、対象範囲を定める骨組みを書きます。

• 新しいプロジェクトまたは機能：エントリーポイント、データの形、空の実装枠を備え、最初から最後まで実行できるコードを用意します。各枠にはシグネチャ（入力、出力、エラーの報告方法）と、エッジケースを含む期待結果の一覧を定めます。経路全体を実行するエンドツーエンドの受け入れフローを2～3個追加します。
• 修正：根本原因、変更が必要な箇所の全リスト、それぞれの箇所で変更を証明するチェックを示します。
• 擬似コードは、すでに内容が固まっている場合にのみ含めます。
• 独立した実装枠は別々のファイルに配置します。
• 骨組みの規模はタスクに合わせます。変更箇所が1か所だけなら、期待結果とチェックだけで十分です。

各チェックと受け入れフローに合格するまで、実装枠を埋めていきます。他のエージェントに作業を引き継ぐ場合、agent-delegation がインストールされていれば、それに従います。そうでない場合は、各エージェントに担当する実装枠のシグネチャ、期待結果、チェックを伝えます。実装枠を埋めるエージェントは、そのチェックを編集しません。返された作業は、自分で確認してから受け入れます。

各ターン終了時の進捗報告

進行中のタスクでは、毎ターンの最後に、当初の目標に紐づけた進捗バーを記載します。合意した項目の完了数／合計数、現在の作業、完了までに残っていることを示してください。既存の計画またはチェックリストを使用します。合意した受け入れ条件と納品条件を満たしたことが検証済みの作業だけを数え、受け入れ待ちは別に示します。

ユーザーが変更しない限り、スコープと分母は一定に保ちます。合計が不明な場合は、パーセンテージや完了日を作り上げずにマイルストーンを示します。項目の完了は所要時間の見積もりではありません。100％となるのは、当初の目標とすべての納品条件を満たした場合に限ります。

---

6. ツールと API の見つけやすさ

CLI ツール、MCP ツール、API を設計または変更する際は、サポートされている操作と使い方をインターフェース自体に記載してください。

• CLI： サポートされているすべてのコマンドを列挙した概要を用意してください。実行できる操作がない状態でコマンドを引数なしで呼び出した場合は、概要を表示してください。必ず --help を実装し、各コマンドのヘルプにパラメーター、必須値、デフォルト値、例、エラーを記載してください。操作が1つだけのスクリプトでは、トップレベルのヘルプを概要と詳細の両方に使用できます。
• API： サポートされているすべての公開エンドポイントとそのメソッドを列挙し、各操作の使い方へのリンクを含む概要エンドポイントを用意してください。利用可能な場合は API のベースパスを使用し、既存のベース操作がある場合は、その操作を維持したうえで専用の概要にリンクしてください。パラメーター、リクエストとレスポンスのスキーマ、認証、エラーを網羅した OpenAPI JSON を公開してください。各操作のドキュメントは概要から見つけられるようにしてください。
• MCP： 使用上の制約と戻り値の動作を含め、各操作を登録済みツールの説明と入力スキーマに記載してください。ツールの登録によって見つけられるため、別途概要ツールを用意する必要はありません。
• スキル： ツールの選択方法、ワークフロー、判断に関わる制約を説明してください。スキルやその参照資料でコマンドとパラメーターのマニュアルを完全に重複させるのではなく、ツールの概要、ヘルプ、登録済みスキーマ、または OpenAPI ドキュメントを参照してください。
• 更新： 影響を受ける機能とともに、概要、コマンドヘルプ、操作の説明、OpenAPI JSON を更新してください。実装のコマンド定義またはルート定義から生成する方法を優先してください。提供前に、サポートされているすべての操作が見つけられること、ドキュメントの例、パラメーター、レスポンスが実際の動作と一致することを確認してください。

ワークフロー

A. コードを書く前

1. 要件とアプローチを明確にします（原則 1）。
2. 成功基準を定義します（原則 5）。
3. 検証方法を選択し、変更前に必要な結果を確立します（原則 4）。
4. 骨組みを書きます（原則 5）。

B. コードを書いている間

原則 2〜4 に沿って骨組みを埋めます。

C. 完了後

1. 検証を完了し、その結果を報告します（原則 4）。
2. 出荷前チェックリストを確認します。
3. ターンを終える前に、原則 5 に沿って当初の目標に対する進捗を報告します。

---

コミットメッセージ

まず、ユーザーの明示的な指示に従い、次にプロジェクトで文書化されているコミットメッセージのルールに従います。コミットを作成する前に、関連するプロジェクトの指示（AGENTS.md や CONTRIBUTING.md など）と、project-memory がインストールされている場合は保存済みの設定を確認してください。コミット履歴だけでは、文書化されたルールがあるとは判断できません。すでに確認済みの選択肢があれば、再度尋ねずにそれを適用してください。

文書化されたルールも確認済みの選択肢もない場合は、直近のコミットメッセージを確認してください。それらが以下のデフォルトに従っている場合、またはプロジェクトにコミットがない場合は、尋ねずにデフォルトを使用してください。確認した履歴に異なるスタイルがある場合に限り、観察された違いを示し、デフォルトを採用するか、プロジェクト独自のスタイルを維持するかを尋ねてください。コミットを作成する前に、その決定を待ってください。ユーザーがデフォルトを拒否し、代替案を指定しない場合は、希望する形式を尋ねてください。自動的なフォールバックをユーザーの決定として記録しないでください。

確認を得た後、独自のプロジェクトスタイルをプロジェクトの AGENTS.md に記録してください。形式と指定された言語を含め、無関係な内容は保持してください。すでに別の場所にスタイルが文書化されている場合は、重複して記載せず、その記載元へのリンクを追加してください。ユーザーがこのスキルのデフォルトを採用した場合は、それを使用し、project-memory があれば、commit-message-style という設定として、ソースを software-engineering-guidelines として記録してください。これにより、後続のコミットで同じ質問を繰り返さずに済みます。project-memory がない場合は、独自スタイルと同様に、採用したデフォルトをプロジェクトの AGENTS.md に記録してください。1回限りの例外はそのコミットにのみ適用し、プロジェクトの継続的なスタイルとして保存してはなりません。決定の保存に失敗した場合は、その旨を報告してください。

デフォルトの形式は Conventional Commits です。

<type>(<optional-scope>): <summary>

feat、fix、docs、refactor、test、build、ci、perf、style、chore、revert など、適切なタイプを使用してください。有用な文脈を加えないスコープは省略してください。実際の変更を簡潔な命令形で要約し、理由や影響の説明が必要な場合は本文を追加してください。該当する場合は、! または BREAKING CHANGE: フッターで破壊的変更を示してください。

ユーザーまたはプロジェクトで別の言語が指定されていない限り、件名と本文は英語をデフォルトとします。形式と言語はそれぞれ独立して判断してください。プロジェクト独自の形式が指定されても、言語も指定されていない限り、デフォルトの言語は変わりません。

例：

fix(auth): handle expired sessions
docs: clarify installation steps

リリース前チェックリスト

• 原則 2〜3 に照らして、スコープとシンプルさを確認しました。
• 機能または問題に完全に対応しています。根本原因、同じパターンが発生する箇所、エッジケースを確認しました。
• エンドツーエンドの受け入れフローを含め、原則 4 に基づく検証を完了しました。
• 結果が合意した成功基準を満たしていることを示し、残る課題があれば報告しました。