Skip to content

docs(agents): 複数リポジトリの .claude 設定調査を反映する - #66

Merged
msageha merged 4 commits into
mainfrom
docs/claude-agents-conventions-refinement
Aug 14, 2026
Merged

docs(agents): 複数リポジトリの .claude 設定調査を反映する#66
msageha merged 4 commits into
mainfrom
docs/claude-agents-conventions-refinement

Conversation

@msageha

@msageha msageha commented Aug 14, 2026

Copy link
Copy Markdown
Owner

概要

AGENTS.md / CLAUDE.md / agent 定義への継続的な改善。まず新規実装前に GitHub 上の
類似 OSS プロジェクトを調査する規約を追加し、続けて ~/Works/src/github.com
配下の .claude 設定 (Sakana 系プロジェクト、anthropics 公式リポジトリ) と
Claude Code 公式ドキュメントの最新動向を調査し、複数箇所で独立に観測された、
または一次情報で裏付けられた知見のみを反映した。
レビュー指摘 (事実誤認 1 件・構成・表記) を反映済み。さらに追加レビューの
Minor / Nit 6 件 (bullet の自己完結性・配置・例外条項・機序の厳密化・
相互参照・重複統合) も反映した。

変更内容

  • 独立したツール・スクリプト・ライブラリ相当の新規実装に着手する前に GitHub 上の
    類似 OSS プロジェクトを調査する規約を AGENTS.md コード規約に追加
  • AGENTS.md git: pathspec 限定 staging (git add -A 禁止)、fetch 済み最新ベース
    からのブランチ作成 (ユーザーが派生元を明示した stacked PR 等は例外)、
    PR 説明文の後続更新
  • AGENTS.md 安全: アクセス権・ID 変更時の diff 提示+確認、sandbox 解除後の
    出力確認の追加 (「SSL エラー → sandbox を疑う」の既存行は維持)
  • AGENTS.md コード規約: pre-existing な失敗のベースライン化
  • AGENTS.md インフラ: terraform plan レビューの厳密化
  • AGENTS.md レポート: instance/class の抽象度較正、「確認済み (confirmed)」には
    実行証拠を要求する規則 (エージェント共通規約のためここに配置。追加レビューで
    隣接する「主張は一次証拠で裏付ける」bullet に統合)
  • AGENTS.md 委譲: 高コスト fan-out 前のゲートチェック、分離コンテキストへの
    委譲設計
  • CLAUDE.md: JIT 参照読込、Read 劣化時の cat フォールバック、長時間タスクの
    状態永続化設計、信頼できない文字列のファイル渡し、subagent_type の明示指定
    (省略時は general-purpose になり、エージェント定義のモデル・effort・ツール
    制限が効かないため)、capability omission によるスコープ強制 (追加レビューで
    スキル・コマンド作成規範として Operating principles へ移動)、検証への
    情報遮断設計 (適用条件が独立検証に限る旨の相互参照付き)
  • debugger agent: 成功シグナルを鵜呑みにしない、パッチ後の敵対的自己検査
  • security-reviewer agent: read-only 前提を踏まえ、ログ・スキャナ出力の再読に
    よる「confirmed」を禁止し、呼び出し元が実行できる検証手順の提示を要求

関連 Issue

なし

動作確認

  • mise run pre-commit が通った
  • mise run test が通った (bats 46 件 pass)
  • mise run dry-run で意図した差分のみであることを確認した (変更対象ファイルに絞った chezmoi apply --dry-run で実施。追加レビュー反映後も同手順で再確認)

チェックリスト

  • テストを追加・更新した (markdown 指示書の追記のため対象外)
  • ドキュメントを更新した
  • 破壊的変更が含まれる場合、その影響範囲を明記した (破壊的変更なし)

補足情報

反映は前回 (#64) と同様、複数プロジェクトで独立に観測された、または一次情報で
明確に裏付けられた知見のみに厳選している。レビューで「subagent_type 省略時は
親会話を継承する fork になる」という記述が公式ドキュメント
(sub-agents.md: "When Claude
doesn't request a type, it gets the general-purpose subagent") と矛盾すると
判明したため、正しい機序に修正した。skill の context: fork が会話履歴を
持たない点は skills.md で裏取り済み。

追加レビュー (Minor / Nit 6 件) では、bullet の隣接順序に依存した記述の
自己完結化 (sandbox 解除後の出力確認)、無条件規則への例外条項 (ブランチ作成)、
heredoc 回避の機序の厳密化 (unquoted は変数展開、quoted でもデリミタ衝突)、
「遮断」と「必要情報を全て渡す」の適用条件の相互参照、confirmed 規則の
重複統合、capability 絞り込み bullet のセクション移動を行った。

独立したツール・スクリプト・ライブラリ相当の新規実装に着手する前に、
GitHub 上の類似 OSS プロジェクトのメンテナンス状況・導入コスト・
機能充足度を確認し、採用/改変/自前実装を判断してから着手するよう
コード規約に追加する。
~/Works/src/github.com 配下の .claude ディレクトリ (Sakana 系プロジェクト、
anthropics 公式リポジトリ) と Claude Code 公式ドキュメントの最新動向を調査し、
複数箇所で独立に観測された、または一次情報で裏付けられた知見のみを反映した。

- AGENTS.md git: pathspec 限定 staging (git add -A 禁止)、fetch 済み最新ベース
  からのブランチ作成、PR 説明文の後続更新
- AGENTS.md 安全: アクセス権・ID 変更時の diff 提示+確認、sandbox 解除後の
  出力確認の拡張
- AGENTS.md コード規約: pre-existing な失敗のベースライン化
- AGENTS.md インフラ: terraform plan レビューの厳密化
- AGENTS.md レポート: instance/class の抽象度較正
- AGENTS.md 委譲: 高コスト fan-out 前のゲートチェック、分離コンテキストへの
  委譲設計
- CLAUDE.md: 実行証拠なしに「確認済み」と呼ばない、JIT 参照読込+cat フォール
  バック、長時間タスクの状態永続化設計、subagent_type 省略時の fork 挙動、
  capability omission によるスコープ強制、検証への情報遮断設計
- debugger agent: 成功シグナルを鵜呑みにしない、パッチ後の敵対的自己検査
- security-reviewer agent: 「confirmed」は実行証拠限定と明確化
- CLAUDE.md: subagent_type 省略時の挙動を公式ドキュメントに合わせて修正
  (省略時は fork ではなく general-purpose。sub-agents.md で確認)
- CLAUDE.md: 「確認済み (confirmed)」の実行証拠規則を AGENTS.md レポート節へ
  移設 (エージェント共通の規約であり、重複を解消)
- CLAUDE.md: 複数規則が同居していた bullet を分割 (JIT 読込 / Read 劣化時の
  cat フォールバック、状態永続化 / 信頼できない文字列のファイル渡し)。
  heredoc 回避の理由 (変数展開・デリミタ衝突) を明記
- AGENTS.md 安全: 「SSL エラー → sandbox を疑う」の旧行を復元し、
  sandbox 解除後の出力確認の行と併記
- AGENTS.md git: ブランチ作成と PR 説明文更新の bullet を分割し、
  和欧間スペースを既存文体に統一 (委譲節の「1 体」も同様)
- security-reviewer agent: read-only 前提に合わせ、PoC 発火要求を撤回し
  「ログ再読での confirmed 禁止 + 呼び出し元が実行できる検証手順の提示」に変更
- debugger agent: バイパス経路が見つかった場合の断定を likely に緩和
- AGENTS.md 安全: sandbox 解除後の出力確認 bullet を直前 bullet への
  暗黙依存 (「SSL / 証明書エラーに限らず」) のない自己完結な条件節に書き換え
- AGENTS.md git: ブランチ作成規則に例外条項 (ユーザーが派生元を明示した
  stacked PR 等) を追記し、無条件規則との板挟みを解消
- AGENTS.md レポート: confirmed の実行証拠規則を隣接する「主張は一次証拠で
  裏付ける」bullet に統合 (守備範囲の重複を解消)
- CLAUDE.md: capability 絞り込みの bullet をスキル・コマンド作成規範として
  Operating principles (JIT 読込の直後) へ移動 (「Subagent への委譲」節との
  ずれを解消)
- CLAUDE.md: heredoc 回避の機序を厳密化 (unquoted は変数展開、quoted でも
  デリミタ衝突)
- CLAUDE.md: 「遮断」bullet に適用条件の相互参照を追記 (情報の最小化は
  独立検証に限る。一般の委譲では AGENTS.md のとおり必要情報を全て渡す)
@msageha
msageha enabled auto-merge (squash) August 14, 2026 02:11
@msageha
msageha merged commit fd86cdd into main Aug 14, 2026
8 checks passed
@msageha
msageha deleted the docs/claude-agents-conventions-refinement branch August 14, 2026 02:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant