Skip to content

AGENTS.md

Latest commit

 

History

History
86 lines (70 loc) · 9.16 KB

AGENTS.md

File metadata and controls

86 lines (70 loc) · 9.16 KB
Raw

AGENTS.md

この repository では、AI エージェントが並行して作業しても品質と再現性を落とさないことを最優先にします。

Mandatory Routing

  • 大量出力、ログ、広い検索、集計、比較、parse は、生データを会話へ流さず要約してから判断する。使う手段は profile ごとの entrypoint に従う。
  • コード理解と refactor は symbol 単位の理解を優先する。手段は profile ごとの entrypoint に従う。
  • library/framework/SDK/API/CLI/cloud serviceのcode generation、setup、configuration、現行documentation確認はcontext7を優先する。library IDを解決してからqueryを単一conceptへ絞る。一般的なrefactor、business logicのdebug、repository固有codeのreviewには自動適用しない。
  • 仕様や product intent は Spec Kit の specify/plan/tasks/implement flow に寄せる。未導入なら plan mode で要件を書き docs/planning/requirements/ に残す。
  • raw secret、個人情報、production data を会話、ログ、fixture、commit に出さない。

Tool Requirements

  • ツールの must / recommended と未導入時の縮退先は docs/framework/toolchain-flow.md のツール要件表に従う。検査は ./scripts/check-agent-tools.sh。
  • must が未導入と分かったら、作業を止めて導入を促す。 縮退して進めない。
  • recommended は自発的に勧めない。 尋ねられたとき、または縮退のコストが明らかに高いときだけ提示する。
  • ツールを自動でインストールしない。 環境変更は人間の承認領域（docs/framework/quality-gates.md）。

Agent Roles

  • Coordinator: Issue readiness、scope、依存関係、担当分割を決める。
  • Implementer: 小さい差分で実装し、必要なテストと docs を更新する。
  • Reviewer: bug、regression、missing test、secret leak、acceptance criteria 対応を確認する。
  • Human Approver: destructive migration、auth、secret、billing、production deploy、legal/privacy を承認する。

Work Rules

  • 1 Issue = 1 branch = 1 PR を基本にする。
  • 並列作業は isolated worktree を使う。
  • 利用する AI 環境は .ai/active-profile と docs/framework/ai-environment-profiles.md で明示する。
  • AI 環境別の設定差分は .ai/profiles/<profile>/files/ に置き、手作業で混ぜない。
  • すべての Issue は、Done を検証コマンドまたは観測可能な状態で定義する。
  • 1 つの PR には 1 つの変更理由だけを入れる。依頼外の format、rename、refactor、cleanup は follow-up に分ける。
  • 新しい抽象化より既存パターンの拡張を優先する。現在の要求がない future-proofing は入れない。
  • PR には検証結果、関連 Issue、作業サマリー path、既知の未対応を必ず書く。
  • Spec Kit task と GitHub Issue が対応している場合、tasks.md と Issue state/comment/close を同じ作業セッションで同期する。
  • タスク完了時は scripts/complete-task.sh --issue <number> --stage-all --merge --close-issue を標準パイプラインとして実行する。人間承認が必要な領域は --merge --close-issue を外し、PR と objective review までで止める。
  • GitHub 操作の直前には必ず GitHub の実状態を再取得する。thread 内の記憶、local checkout、直前の推測だけで Issue comment、merge、close を実行しない。
  • closed Issue には原則コメントしない。Issue が既に closed なら、再 open が必要か新 Issue が必要かを確認する。
  • mock、fixture、stub、fake、demo の成功を product acceptance として扱わない。real user path または明示された user-facing fallback の検証を完了条件に含める。
  • 変更理由が後から議論になりそうなものは docs/decisions/ に残す。
  • 作業終了時は docs/work-notes/ に短いサマリーを残す。
  • 指示・Issue には What / Why / How を含める。重要な作業ほど Why（背景・経緯）を厚く書く。欠けたまま着手せず、補完を依頼する。詳細は docs/framework/collaboration-rules.md の Instruction Pattern。
  • 企画成果物（docs/planning/）は実装着手前に人間のインラインレビューを通す。指摘には差分で応答し、指摘のない箇所を作り直さない。詳細は同 Inline Review。
  • 複数の AI を有効化している場合、タスク種別ごとの担当を docs/framework/ai-environment-profiles.md の Task Routing に従って決める。迷ったら深い方に倒す。同一 Issue を複数エージェントで並行させない。
  • 同じ手順を work-note で 3 回以上繰り返したら .agents/skills/ への昇華を検討する。危険操作の skill は自動呼び出しを無効化し、SKILL.md は目次に留める。詳細は docs/framework/agent-settings-replication.md。
  • ツールチェーン（superpowers / Spec Kit / crit / skills / GitHub Issues / Linear）は docs/framework/toolchain-flow.md の標準フローに沿う。企画段を担うツールは profile によって異なる（同ファイルのツール要件表を参照）。実装の要件・分解は Spec Kit→GitHub Issue、人間検証は crit→対応 Issue にコメント、解決は Linear へロールアップ。企画書と Issue を相互リンクする。
  • Codex / Claude Code / hermes のいずれで作業しても同じ規約に従う。Issue の消化方式は異なり、Codex は Symphony で無人実行、Claude Code と hermes は skills のマルチエージェントで並列に進める。追跡先（GitHub Issue）と承認境界はどちらも共通。詳細は docs/framework/toolchain-flow.md。
  • 管理先の境界: アプリのソースコード（と、その改修・機能追加の要件定義・開発タスク）は GitHub の Issue/PR、ソースコードに反映しない企画・非開発のファイル変更は Linear（必要なら sub-issue に分割）で管理する。迷ったら「アプリのコードを変える or その要件・開発タスクか」を問い、Yes→GitHub、No→Linear。
  • 標準フローから外れた進め方を人間が選ぼうとしたら、黙って従わない。 非推奨である理由を明示し、標準に沿う代替案を提示する。それでも明示的に選ばれたら従うが、逸脱と理由を work note か Issue に残す。
  • 詳細な開発規律は docs/framework/software-engineering-practices.md に従う。

Knowledge Base（docs の維持）

  • ドキュメントは docs/ 配下に日本語で保存し、構造化する。システム開発に直接関係しない知識（マーケティング、ブランディング、競合、ビジネスモデル、法務・規制、説明資料、FAQ、カスタマーサポート）も docs/knowledge/ に置く。
  • 企画（調査・要件定義）と実作業（実装）を分離する。 企画は plan mode などで行い、成果物を docs/planning/（調査・要件）と docs/decisions/（意思決定）に残してから実装に入る。
  • 意思決定は情報ソース（URL・参照物）と理由を添えて docs/decisions/ に簡潔に残す。
  • 実装が product / engineering / business / support / 法務 などの知識に影響する場合、該当する docs/knowledge/ を同じ作業セッションで更新する。
  • どこに何を書くか迷ったら docs/index.md と docs/framework/knowledge-base.md を参照する。構造とスキーマの正本はこの 2 つ。
  • Codex と Claude Code のどちらで作業する場合も、docs/ を single source of truth として同じ規約で維持する。

Quality Gates

プロジェクトごとに検証コマンドを定義する。最低限:

  • format または lint
  • typecheck または static analysis
  • unit test
  • integration/e2e test if applicable
  • build/package
  • secret scan or manual secret checklist
  • open GitHub issues vs tasks.md pending count check, if Spec Kit is used
  • objective review report generated by scripts/complete-task.sh
  • real-use gate check, if feature claims usable/v1/production-ready behavior
  • local validation commands match CI, or differences are explicitly documented
  • docs 鮮度チェック: 変更が影響する docs/knowledge/ カテゴリと、企画に用いた docs/planning/ / docs/decisions/ が更新されているか

Safe Continuation

  • 不明な前提は repository 内の README、spec、plan、tasks、docs から確認する。
  • 大きな設計変更の前に docs/decisions/ に意思決定記録（情報ソース＋理由）を作る。
  • 他エージェントや人間の未関連変更を revert しない。
  • runtime、secret、deployment、permission、および product/business/support/法務 の前提が変わる場合は、該当する docs/knowledge/ を同時に更新する。
  • handoff 前に tasks.md の pending task と open GitHub Issues の mismatch がないか確認し、残る場合は理由を final report に書く。
  • mock-only / fixture-only の成功を「実利用完了」として報告しない。