エージェント運用プロトコル
運用プロトコル
自明でない変更を行う前に、AI エージェントは次の手順を踏むこと。
- ユーザーの本来の意図を理解する。
- 既存の実装を調査する。
- 関連するプロジェクトドキュメントを読む。
- アーキテクチャの不変条件と関連する ADR を確認する(アーキテクチャガバナンス)。
- 既存のツールチェーンとプロジェクトの規約を確認する。
- 既存の依存関係とパターンを優先して使う。
- 要件を完全に満たす範囲で、変更を最小限にする。
- 無関係なクリーンアップは行わない。
- 関連する検証を実行する。
- 変更後の diff をレビューする。
- 意図せず追加されたファイルや無関係な変更がないことを確認する。
- アーキテクチャ、依存関係、セキュリティ、振る舞いに関わる重要な変更を説明する。
自分の好みのスタイルというだけで、動作しているコードを書き直してはならない。
似たコードが 2 か所に現れただけで抽象化を導入してはならない。保守性、正しさ、アーキテクチャの実際の問題を解決するときに限って導入する。
メモリの扱い
永続メモリを持つ AI エージェントは、このプロジェクトが本ガイドラインを採用していることを記憶しておくこと。
メモリは関連する指針を探す手がかりとして使う。信頼できる唯一の情報源は、リポジトリ内のガイドラインとプロジェクトドキュメントである。記憶した規則や要約より常に優先する。
大きな作業の間は、現在のガイドラインを随時読み返すこと。特に次の場面では関連する節を確認する。
- 重要なプロジェクト作業を始めるとき
- アーキテクチャを変更する前
- 依存関係を追加または置き換える前
- CI/CD を変更する前
- ツールチェーンの設定を変更する前
- UI 言語の動作を変更する前
- 既存のプロジェクト規約が不明確なとき
- 記憶とリポジトリの内容が食い違うとき
リポジトリに現在の規則があるのに、記憶した要約に頼ってはならない。
ハードルール早見表
次の行為は禁止である。各項目には、規則を定義するドキュメントへのリンクを付けている。規則を変更したときは、このリストも必ず更新すること。
- ユーザーの明示的な承諾なしに、必須の標準ツールを置き換える(エンジニアリング基本原則)。
- pnpm の代わりに npm や yarn を使用する(TypeScript ツールチェーン)。
- 標準のプロジェクトリンターとして、oxlint の代わりに ESLint を使用する(TypeScript ツールチェーン)。
- oxfmt の代わりに Prettier を使用する(TypeScript ツールチェーン)。
- uv の代わりに Pipenv や Poetry を使用する(Python ツールチェーン)。
- ruff の代わりに flake8 や black を使用する(Python ツールチェーン)。
- prek の代わりに pre-commit や Lefthook を使用する(品質ゲート)。
- 正当な理由と承諾なしに、Cocogitto を別の Conventional Commits バリデーターに置き換える(Git ワークフロー)。
- 内容を理解しないまま、lint や検証の問題を無視する(エンジニアリング基本原則)。
- チェックを通すためだけに、有用なルールを無効化する(エンジニアリング基本原則)。
- 迅速な検証が求められるプロジェクトを過剰に設計する(エンジニアリング基本原則)。
- 不要な依存関係を導入する(依存関係の規律)。
- 冗長なファイルやモジュールを作成する(コーディング規約)。
- ADR を黙って破る(アーキテクチャガバナンス)。
- アーキテクチャの不変条件を誤って変更する(アーキテクチャガバナンス)。
- ソースコードに英語以外の識別子やコメントを使用する(言語ポリシー)。
- ローマ字(romaji)やピンイン(pinyin)をコード識別子として使用する(言語ポリシー)。
- 会話言語から UI 言語を推測する(言語ポリシー)。
- 複数言語にまたがる UI 作業で、品質の低い直訳を作る(言語ポリシー)。
- 互換性を確認せずに GitHub Actions を安易にアップグレードする(GitHub Actions)。
- シークレットや機密情報をコミットする(セキュリティ)。
- 適切な承認を得ずに、共有履歴へ force push する(Git ワークフロー)。
- CI が緑だからといって、実装の正しさの確認を怠る(変更の規律)。
- 明示的なサプライチェーンポリシーがないのに、GitHub Actions を現在のメジャーバージョンタグではなくコミット SHA に固定する(GitHub Actions)。