--- name: agent-standards description: > コーディングエージェント向け文書（`AGENTS.md`・`CLAUDE.md`・`.agents/`配下・ `.claude/rules/`・`.claude/skills/`・hooks関連ファイルなど）の 新規作成・修正・計画・レビュー時、及びホスト機能の可否・入出力契約を調査するときに `agent-toolkit:writing-standards`と必ず併用して呼び出す。 セッション記録（`~/.claude/projects`配下）の集計・分析時も呼び出す （`references/session-records.md`が構造を定める）。 --- # コーディングエージェント向け文書品質 本スキルは、コーディングエージェントが直接読み込む文書（`AGENTS.md`・`CLAUDE.md`・ルール・`SKILL.md`・ サブエージェント定義・`references/`）の品質基準を提供する。 計画ファイルは対象外。 一般ドキュメントの品質は`agent-toolkit:writing-standards`が担当し併用する。 ## 完成条件 新規作成・改訂した文書は次のすべてを満たす。 ### 責務と構成 - agent定義・スキル・受信するタスク文書は、本文冒頭で受信者が担う責務、担わない責務、最初に行う行為を明示する。 最初の行動要求は主体・対象・拘束力を読み取れる形（命令形・依頼形・体言止め・規定文など）で示し、 拘束力を読み取れない動作説明文で要求を代用しない - 委譲元側の文書は受渡しと検収だけを担い、委譲先固有の手順を再掲しない。 委譲先は渡されたタスク文書と必要な作成・レビュー規範を自ら読む - 冒頭1〜2文で目的（適用判断の核となる動機）を述べる。frontmatter `description`には 対象作業と発火条件のみを書き、目的記述は本文側に置く - 新規挙動・制約は次のいずれかへ振り分ける。常時参照される横断標準は`AGENTS.md`・`CLAUDE.md`本文または paths未指定ルール、特定パス限定則はpaths指定ルール、手順・ワークフローはスキル、 決定論的強制・自動lintはhook、重い調査・冗長出力の隔離はサブエージェント - スキル・agent・受信するタスク文書の責務配置は`references/agent-skills.md`に従う ### 記述内容の取捨 - 既に自動ロード済み・呼び出し済みの規範を要約・反復しない。各行は「削除すると判断が 一貫しなくなる」と言えることを条件とする - 実行判断に寄与しないメタ情報（管理方針・編集判断・同期対象）はfrontmatterコメントへ置き、 本文には実行判断に直接寄与する記述のみを置く ### 条件と範囲の記述 - 判断条件・例外条件・許容条件は観測可能な事実（コマンド終了状態・ファイルの有無・ ユーザー合意等）のみで記述する。自己推定量（コンテキスト消費・作業量・所要時間等）を条件に含めない - 適用範囲・除外対象・前提条件を明示する。複数の対象が並ぶ文脈では対象ごとの適用可否を書き分け、 範囲は最も広く取れる案を初期案とする - 独立して変化し得る複数の制約は1つの箇条書きへ結合せず、制約ごとに項目を分けて記述する。 既定の禁止または許可とその例外を定める場合、例外が解除する制約を明示する（努力目標） - 禁止規定を追加する前に同じ再発防止を肯定形で表現できないか検討し、新規の禁止規定には 対応する推奨事項を併記する。新規又は変更する禁止・義務の条文は、実体的な義務を主節に置き、 当該条文が防ぐ事象を本文へ残す。同一命題が複数箇所へ分散する場合は単一の原則へ統合する（努力目標） - 既存規定の表現形式を変える場合は、変更前の原文と変更後の文面を1対1で照合する。 テーマ別の分組・決定表化・閉じた列挙への上位概念や範囲語の追加・否定形の肯定形化・条件文の再構成では、 適用条件、禁止範囲、要求する実行時機構が同値であることを確認する。 同値でない場合は形式変更とせず、適用範囲や要求手段の仕様変更として根拠と影響を明示する （厳守規定。要求する実行時機構を説明文又はコメントへ置換すると規定が技術的に成立しない） - 会話文脈依存の指示語（「今回」「先ほど」等）・自己参照の指示語（「本規則」「上記」等）を含めない ## 規範追記時の判定 規範文書へ新しい規定を追記する前に、次を確認する。 - 一般則で表現できる事象を個別事例の列挙で条文化していないか。既存の一般則の補強で十分な場合は追記しない - 是正指示を個別対象の列挙形式の規範へ反映する場合、列挙全体を貫く判定基準として表現できないかを 先に検討し、可能なら列挙を基準へ置き換える - 常時ロードされるファイル（rules・`AGENTS.md`・`CLAUDE.md`）に置く必要があるか。 特定作業時のみ必要な内容はスキルまたは`references/`へ置き、必要ならスキルの発火条件（`description`）を広げる - 数値の閾値・複雑な判定手順を、単純な原則で代替できないか。 閾値を置く場合は境界値の妥当性根拠を本文へ残す - 宣言だけで実行時に遵守されると期待していないか。作業手順の特定時点で必要な規範は、 観測可能な契機と結びつけた読込・起動指示（「〜を検知したら〜を読み込んでから編集する」等）として 当該工程へ埋め込む（努力目標） - 直接操作又は代替手段に関する要件を新設、改訂又は移設する場合は、操作開始に必要な対象と入力を列挙し、 同じ読込文脈から対象と入力を取得できる観測可能な手段を記載する - 品質要件を、起草時又は実装時の完成条件などの生成側と、レビュー観点、検査項目、機械検査などの検出側の いずれか一方へ追加する改訂では、同一改訂内でもう一方へも追加する。 要件が複数の記載要素（対象・条件・導出根拠など）から成る場合は、生成側が列挙する要素と 検出側が照合する要素を1対1で突き合わせ、片側にしか無い要素が0件であることを確認する。 片側へ置けない要素は理由を本文へ残す（努力目標） - 追記先の文書に、追記する規定と反対方向の判断を定める既存条文（除外規定・適用外リスト・重大度や分類の定義など）が無いかを本文検索で確認する。 ある場合は追加だけで終えず、同一改訂で当該条文を置換するか、例外関係と優先順を明示する（厳守規定。同一事象へ反対の判断を与える条文が併存すると規定を一意に適用できない） ## LLM読者特性の考慮 コーディングエージェント向け文書の読者はLLMであり、知識の想起・注意・推論に人間の読者と異なる傾向を持つ。 次のいずれかに着手する時点で`references/llm-characteristics.md`を`Read`で読み込み、特性別の記述指針に従う。 - 文書の新規作成 - 規範の主張・条件・適用範囲・例示を意味的に変更する改訂 （節・箇条書き項目・表の追加、削除、移動、分割・統合を含む） - 文書間の分割・統合・配置先（rules・スキル・`references/`・hook）の設計 - 前記いずれかの変更の計画・レビュー 意味を変えない誤字・句読点・リンクの修正だけの編集は対象外とする （「LLM読者特性の考慮」節の読込指示は努力目標）。 計画やレビュー契約へ、実装順序・単位分割・個別コマンドなどの手順詳細を記載する場合は、既存規範と確定済み外部仕様から一意に導出できないかを確認する。一意に導出できる詳細は省略し、安全性、データ保全、公開契約又は主体間の認可境界を守るために必要な場合だけ明示する。 ## 文書記述量の管理 対象は`agent-toolkit/rules/`・`agent-toolkit/skills/`・`agent-toolkit/agents/`配下のMarkdownとする。 `agent-toolkit/skills/*/scripts/`配下の機械チェック実装コードも対象に含む。 これらを新規作成・改訂する際は安易に記述量を増やさない。 既存記述との重複統合（除去・統合・`references/`分離のいずれか）を常に検討する。 本規定は努力目標とし、合計行数への機械的な上限は設けない。 規範量が作業へ影響する経路は、同一契約の分散で同期対象箇所が増えることと、判断に使わない記述を起動時に読んで初期コンテキストを消費することの2つとする。総バイト数だけで削減対象を決めない。 記述は、常時ロード（`rules/`とfrontmatterの`description`）、メイン起動時（`SKILL.md`本体）、明示Read時（`references/`）、サブエージェント注入（agent定義とfrontmatterの`skills`）の4階層から、読む主体と必要になる時点に合わせて配置する。 スキルの本数削減は常時ロード量をほとんど減らさない。削減では、消費主体が観測する起動経路を変える統廃合より、`SKILL.md`本体から`references/`への退避とagent定義の縮小を優先して検討する。 統合を検討する場合、削減判定は次のいずれかの根拠を満たすことを条件とする。 - SSOT違反: 他ファイルに正規の記述がありここは転記に過ぎない - 自明導出: 上位指針・学習データから自明に導出できる。 ただし知識として自明でも、明示されないとエージェントが安定して考慮しない種類の観点 （セキュリティ・エラー処理の作法など）は自明導出に当たらない - 公式ドキュメント代替可能: 公式ドキュメントの一次資料参照で同等の情報が得られる - 上位指針への統合: 細則列挙を束ねる上位指針へ昇格できる。 同一工程を扱うバレットが同一節配下へ並列蓄積している場合も統合を検討する 数値・閾値・境界値の判断根拠部分（由来・境界を分ける理由・トレードオフ）は削減対象から除外する。 削減後に規範性が失われる場合は他節での代替可否を確認し、代替不能なら圧縮せず残す。 既存規範を圧縮・統合する際は、元の規定が持っていた順序の制約・前提条件・除外条件を欠落させない。 圧縮・統合の直後に、圧縮前後で「先に確定させるべき事項が後段へ回っていないか」 「無条件と解釈され得る記述へ変わっていないか」 「対象外だったものが対象に含まれる書き方になっていないか」の3点を自己点検する 自作CLIの出力書式は当該CLIの契約テストを正本とし、読み手側の文書へ出力の再解析手順を書かない。 （手順の順序自体が誤った行動を防いでいる場合があるため）。 圧縮・統合・削除いずれの操作でも次を保護対象とし、削減の対象に含めない。 - 本文冒頭の目的記述（適用判断の核となる動機） - 開いた列挙表現（「等」「〜を含む」「〜など」）。閉じた列挙への書き換えは範囲を狭める操作のため行わない - 同一ファイル内の既存表記との整合が必要な用語と、並列表現の対称性 - 行数調整のみを目的とした機械的削減（意味内容の変化を伴わない字数除去は行わない） ## セッション状態フラグ Claude Codeのhookは状態ファイル`{tempdir}/claude-agent-toolkit-{session_id}.json`を共有する。 ## タスク固有で読み込む補足情報 - `references/agent-skills.md`: スキル編集時（公式リファレンスの参照先を含む） - `references/check-script-design.md`: 機械チェックスクリプト新設・改修時 - `references/claude-hooks.md`（hook編集時）・`references/auto-mode.md`（auto mode編集時・権限拒否時） - `references/hook-message-labeling.md`: hookのエンドユーザー向けメッセージを新設・改訂する時 - `references/session-records.md`: セッション記録の集計・分析時 - `references/tool-operations.md`: 大量の文書読込・大規模ブロック置換・plugin資源のroot失効時 - agent定義・スキル編集の入口では`agent-toolkit:agent-standards`の`agent-standards/references/agent-skills.md`を全文読む - hook編集の入口では`agent-toolkit:agent-standards`の`agent-standards/references/claude-hooks.md`を全文読む - hookメッセージ編集の入口では`agent-toolkit:agent-standards`の`agent-standards/references/hook-message-labeling.md`を全文読む - auto mode編集又は権限拒否時は`agent-toolkit:agent-standards`の`agent-standards/references/claude-hooks.md`及び`references/auto-mode.md`を読む - セッション状態フラグを扱う入口では`agent-toolkit:agent-standards`の`agent-standards/references/session-state-flags.md`を全文読む