AGENTS.md でチームの挙動を標準化する

AGENTS.md は、OpenCode（およびあらゆる AI エージェント）がリポジトリでどのように振る舞うべきかの単一の信頼できる情報源です。うまく書かれていれば、すべての貢献者（人間でも AI でも）が同じベースラインから始められます。

このレシピを使う場面

• すべての AI 生成 PR で一貫したコードスタイルとレビュー品質を確保したい。
• 新しいチームメンバー（人間・AI）のオンボーディングに時間がかかりすぎている。
• チームの異なる部分で規約が異なり、PR が往復している。

前提条件

• リポジトリに OpenCode がインストールされている。
• チームの現行規約（スタイル、テスト、エラーハンドリング）についての大まかなアイデアがある。
• 反復する意欲がある — 最初のドラフトは間違っている。

手順

1. スタブから始める

   リポジトリルートに最小限の構造で AGENTS.md を作成します。

   # AGENTS.md
   
   ## Project overview
   [One paragraph: what this project does and the stack]
   
   ## Build, test, lint
   - Build: `npm run build`
   - Test: `npm test`
   - Lint: `npm run lint`
   
   ## Code style
   [Your language-specific style rules]
   
   ## Testing rules
   [When to add a test, what to cover, mocking policy]
   
   ## Commit and PR rules
   [Commit message format, PR template, who reviews what]

2. ギャップを埋めるよう OpenCode に依頼する

   既存のコードベースとスタブを OpenCode に示します。コードから規約を推測します。

   プロジェクトルートとスタブの AGENTS.md を読んでください。各セクションについて、既存コードから具体的な例を使ってルールを埋めてください。コードベースが一貫していない場合は、私たちが従うべきルールを提案し、その一貫性のなさをフラグしてください。

3. 「禁止事項」セクションを追加する

   明示的な禁止事項は、最も一般的なエージェントのミスを防ぎます。

   ## Do not
   - Do not add new top-level dependencies without discussion.
   - Do not commit generated files (build/, dist/, node_modules/).
   - Do not bypass the linter to make CI green.

4. 「行き詰まった時」セクションを追加する

   正しい答えが分からない時にエージェントが何をすべきかを伝えます。

   ## When stuck
   - Search the codebase first (`rg`, `grep -r`).
   - Read the related test file for the expected behavior.
   - If still stuck, ask in #dev-help rather than guessing.

5. コミットして PR テンプレートで参照する

   AGENTS.md をコミットし、.github/pull_request_template.md からリンクしてレビュアーがドリフトを検知できるようにします。

6. 学びながら反復する

   繰り返される PR コメントを見たら、AGENTS.md にルールを追加します。ルールが摩擦を生むなら、それを削除します。

重要なプロンプト

プロジェクトルートとスタブの AGENTS.md を読んでください。各セクションについて、既存コードから推測した具体的なルールを、ファイルと行の例とともに埋めてください。エージェントに避けさせたい最も一般的な間違いを含む「禁止事項」セクションを追加してください。このリポジトリの信頼できる情報源（検索コマンド、テストファイル、チャットチャネル）を指す「行き詰まった時」セクションを追加してください。

検証

• 新しいエージェントセッションが起動時に AGENTS.md を読み、ルールに従う。
• 一般的なレビューコメントが減る（スタイル、見逃されたテスト、誤ったコミット）。
• ファイルが短い（200 行未満） — もしそれを超えるなら、ルールが細かすぎて有用でない。

よくある落とし穴

• 過剰に詳細化する: 1000 行の AGENTS.md は無視されます。短く保ち、詳細なドキュメントにはリンクで誘導してください。
• 古いルール: 規約はドリフトします。カレンダー通知で四半期ごとのレビューを設定してください。
• 「禁止事項」がない: 禁止事項がなければ、エージェントは独自の好みを発明します。明示的にしてください。

関連ドキュメント

• ルール — すべてのタスクで OpenCode が従うプロジェクトレベルの指示
• 設定 — OpenCode の動作を規定する opencode.json ファイル

関連レシピ

• custom-skill — reason.agents.to-skill
• explore-unfamiliar-codebase — reason.agents.to-explore
• project-scaffold — reason.agents.to-scaffold

関連ドキュメント

• ルール
• 設定
• ポリシー

次のステップ

• custom-skill — next.agents.to-skill