AGENT SKILL

trace-cause

リポジトリで再現する 1 つの失敗(落ちるテスト・誤った出力)の根本原因を、確かめた事実の連なりとして特定する。「このテストが落ちる原因を突き止めて」「なぜこのコマンドがこの出力になるのか調べて」のように、再現手順のある失敗の原因調査を頼まれたときに使う。再現手順の無い相談、修正そのものの依頼、一般的な質問には使わない。

License 许可
MIT
最近更新
2026-11-14
Stars
★ 1
Forks
0

01 前言 Front Matter

name
trace-cause
description
リポジトリで再現する 1 つの失敗(落ちるテスト・誤った出力)の根本原因を、確かめた事実の連なりとして特定する。「このテストが落ちる原因を突き止めて」「なぜこのコマンドがこの出力になるのか調べて」のように、再現手順のある失敗の原因調査を頼まれたときに使う。再現手順の無い相談、修正そのものの依頼、一般的な質問には使わない。

02 资源文件 14

03 SKILL.md 正文

trace-cause

失敗の原因は、1 つ調べると次に調べる場所が変わる(呼び出し元を読むと設定の読み込みが怪しくなり、設定を読むと環境変数が怪しくなる)。そのため、調べる方向を計画役が周ごとに選び直し、実行役が方向ごとに並列に確かめ、検証役が確かめた事実だけを状態に積む。形をこう選んだ理由は references/design.md にある。

起動

最初に、状態を scripts/start.mjs で作る(run の外で作る理由は references/design.md の「部品」)。このコマンドは下の「必要な許可」に入れないので、実行のたびに利用者が確認する。run の中の役が実行しようとしても確認が出て、確認なしでは状態を作れない。commands には依頼文の再現手順のコマンドを、依頼文に書かれたとおりに挙げる。実行役と検証役が写しの中で実行できるのは、開始で記録したこの一覧のコマンドだけになる。応答の state(状態 ID)と resumeKey(再開の鍵)を、利用者に示してから使う(ヒントを足すときと、止まった run を続けるときに要る)。

node '<このスキルのディレクトリ>/scripts/start.mjs' <<'EOF'
{"repo": "<調べるリポジトリの絶対パス>", "request": "<依頼文>", "commands": ["<再現手順のコマンド>"]}
EOF

host に native Workflow があればそれを使い、無いとき(Codex)だけ runner を使う(native-first)。経路は起動のたびに、再開の起動でも選び直す。

経路 起動のしかた 起動数の上限 maxLaunches
native Workflow(Claude Code) Workflow({ scriptPath: "<このスキルのディレクトリ>/scripts/trace.js", args }) 渡さない(上限を置かない run にする)
Codex runner workflow:dynamic-workflow-runner に同じ scriptPath と args を渡す 必ず渡す。値はその起動の request の limits.maxAgents と同じ値(超えると runner が run 全体を失敗させる)

args の項目は次の表を正とする。最初の起動も再開も同じ項目を渡す。script は、必須の項目の欠けを BLOCKED で返し、agent を起動しない。

項目 必須か 中身
state 必須 状態 ID(最初の起動は開始の応答、再開は nextArgs にある)
repo 必須 調べるリポジトリの根(.git のあるディレクトリ)の絶対パス。状態と作業ファイルはこのリポジトリの外の置き場(以下「状態の置き場」。既定は ~/.local/state/trace-cause/、環境変数 TRACE_CAUSE_HOME で変える)に置く。状態は <状態の置き場>/states/ の下、作業ファイルは <状態の置き場>/runs/ の下(以下「作業ファイルの置き場」)に分ける
skillDir 必須 このスキルのディレクトリの絶対パス。役の指示と状態の CLI をここから読む
resumeKey 必須 再開の鍵(最初の起動は開始の応答、再開は nextArgs にある)。CLI は無いか違えば run を始めない
maxLaunches 経路の表に従う 1 以上の整数
maxTokens native の経路だけ渡す トークン量の上限(1 以上の整数)。渡さなければ上限を置かない。消費量を run の中に読めない Codex runner では渡さず、起動数の上限で費用を抑える

止まった run を続けるときは、返り値の nextArgs(state・repo・skillDir・resumeKey)をそのまま args に渡し、経路の表に従って maxLaunches を足すか決める。nextArgs は起動数の上限を含まない。

起動したら、次の「ヒントの足し方」を利用者に示す。

ヒントの足し方

run の実行中も、完了以外で止まっている間も、利用者はヒントを足せる。ヒントは計画役が次に呼ばれたときに読む(目標を固定する前に止まった run では、目標の固定役も読む)。run を止める必要は無い。state と resumeKey は開始の応答の値を使う。ヒントを足せるのは再開の鍵を持つ者だけで、run の中では運搬役しか再開の鍵を見ないので、他の役はヒントを足せない。

node '<このスキルのディレクトリ>/scripts/state.mjs' hint <<'EOF'
{"repo": "<調べるリポジトリの絶対パス>", "state": "<状態 ID>", "resumeKey": "<再開の鍵>", "text": "<ヒントの本文>"}
EOF

完了した状態へのヒントは CLI が拒否する(完了した run は再開しないので、足しても読まれない)。

必要な許可

run の途中で権限の確認が出ると、その間 run が進まない。auto mode では script が agent に渡す prompt は利用者の依頼として扱われず、このスキルの側からは変えられないので、起動の前に次の許可を allow rules に入れる。Bash の許可はコマンドの前方一致で効くので、CLI の許可は script が agent に渡すコマンドと同じ字面(パスを ' で囲む)で書く。これより広い許可は要らない(permission rules は run の全ての agent に同じく効く)。

  • Bash(node '<このスキルのディレクトリ>/scripts/state.mjs':*)(状態の読み書き。状態を書くのは CLI だけ)
  • Bash(node '<このスキルのディレクトリ>/scripts/copy.mjs':*)(試行ごとの写しを作業ツリーの今の内容から作り直し、開始で状態に記録した再現手順のコマンドだけを、写しの中で実行する。対象のリポジトリの作業ツリーにも .git にも書かない。写しは作業ファイルの置き場の下の決まった形のパスにだけ作る。リポジトリの外を指す symlink はリンク先の中身を写す。写せないもの(リポジトリを含む祖先を指すリンク、辿ると輪になるリンク、写しを指すリンク、解決できないリンク、外の中身のうち通常のファイルでもディレクトリでもないもの(FIFO・デバイス・ソケット))は写しに作らず、作り直しの応答の dropped に写しの中のパスで載せる)
  • Write(<状態の置き場>/runs/**)(作業ファイル。意図ごとの記録ファイルと大きな出力、各役の出力の写し、試行ごとの写しの置き場。状態のファイルのある <状態の置き場>/states/ は含めない)
  • Read(<状態の置き場>/runs/**)・Read(<リポジトリ>/**)・Read(<このスキルのディレクトリ>/**)(作業ファイル・調べるリポジトリ・役の指示を読む。どれも作業ディレクトリの外にありうる)
  • Bash(node '<このスキルのディレクトリ>/scripts/git-read.mjs':*)(リポジトリを git で読むだけの CLI。log・show・diff・blame・ls-files・grep に限り、操作ごとに受け付ける引数の一覧の引数だけを受け付け、リポジトリの外に解決するパスを拒否し、索引も書き換えない)

再現手順のコマンドをそのまま実行する許可と、git の生の許可は入れない(許可はコマンドの前方一致なので、実行する場所を縛れず、git も --output や -O を足すと書き込みやコマンドの実行に化ける)。scripts/start.mjs も入れない(run の中の役が状態を作れると、その状態に記録した任意のコマンドを写しの中で実行できる)。

役ごとの制限

状態を書けるのは運搬役の経路だけにする。CLI は再開のたびに run ごとの書き込みの鍵を発行し(状態には鍵の digest だけを残す)、script はその鍵を運搬役の prompt にだけ入れる。CLI は鍵の無い書き込みを拒否する(他の役が CLI で事実を直接書くと、検証を飛ばした内容が状態に入るため)。書き込みの鍵を作る再開は、開始の応答と nextArgs にだけ載る再開の鍵を要る。状態のファイルは書き込みの許可の外に置くので、CLI を通さずにも書けない。他の役は CLI を読み出しにだけ使う。利用者のヒントは例外で、書き込みの鍵でなく再開の鍵で足す。

役 書いてよい先
運搬役 CLI を通した状態だけ
実行役・回収役 作業ファイルだけ(リポジトリには書かない)
検証役・完了の照合の検証役・計画役・目標の固定役 作業ファイルだけ

対象のリポジトリに書き込む役は無い。修正は、このスキルの結果を入力にした別の作業として行う。

Claude Code では、plugin から読み込む agent の設定の一部が無視されるため、上の制限が配布先で効くかをこのスキルは確かめられない。Codex runner は agent ごとの道具の許可を持たず、権限は全ての呼び出しに一律に効く。確かめられなかった制限は全て、返り値の residualRisks に役の名前・制限の中身・配布先・確かめられなかった理由の 4 つで載せる。

停止と再開

停止 いつ 再開のしかた
完了 完了の照合を通った 再開しない
乾き 乾きの周数(scripts/trace.js の DRY_ROUNDS)続けて新しい事実が無く、読まれていないヒントも無い ヒントを足してから nextArgs で再開する
needs_input 目標の固定役が足りない入力を返したか、計画役が人間の入力が要ると返したか、完了の主張の却下が新しい事実を挟まずに続いた 問いへの答えをヒントとして足してから再開する
反復の上限 周の上限に達したか、起動数の上限で次の agent を起動できない nextArgs で再開する
BLOCKED 続けられない失敗か、方向を選び直しても全件失敗が続いたか、同じ事実の判定が意図の間で食い違った 原因を直してから再開する(判定の食い違いは、再開すると計画役が確かめ直しの意図を出し、その検証役の判定で決まる)

停止の記録を書けたかが分からないまま止まった run(運搬役の応答が失われたとき。返り値の理由に書かれる)も、nextArgs で再開する。CLI は状態に書かれた停止を読み、完了が書かれていれば再開せずに完了を返す。停止が書かれていないときは、その run がまだ何も書いていなければ(再開の応答だけが失われたとき)同じ run と同じ書き込みの鍵を返し、書き込みのあった run には BLOCKED の停止を足してから新しい run を始める。

どの停止でも、理由と、未着手の意図と打ち切った意図の一覧を状態に書く。再開した run は状態をそのまま読み、受理された事実・試行の回数・打ち切りを使い続ける。再開した run は必ず計画役から始め、止まっていた間に足されたヒントを読ませる。目標を固定する前に止まった状態では、その前に目標の固定役が、依頼文と止まっていた間に足されたヒントから目標を固定し直す。

返り値

  • stopKind・reason・nextArgs(完了以外)
  • reasonClass(BLOCKED のとき。理由の区分で、失敗なら failure。このスキルは対象のリポジトリを直さないと進めない停止を持たないので、BLOCKED は全て failure になる。起動の項目の欠けや上限の誤りも失敗に含める)
  • facts(受理した事実。事実ごとに検証方式と、示したツールの結果)
  • cause(完了のとき。原因の説明と、根拠の事実 ID)
  • coverage(台帳の資産のうち、実行役が見た割合)と skip(見なかった資産の一覧)
  • pending・aborted(未着手と打ち切った意図)
  • launches(この run の起動数)と roundLaunches(この run の周ごとの起動数。周の途中で止まったときは、その周も停止の運搬役を含めて載せる)
  • models(この run で起動した agent のモデル。起動した順に役とモデルを載せ、モデルを指定しなかった起動は host-default と載せる)
  • residualRisks(agent を起動した後のどの返り値にも載る)

04 同仓库更多 Skills

yoshiysh
yoshiysh/claude-plugins

coverage-build

文書でもプログラムでも、作る(create)・既にあるものを目標に合わせて直す(update)・作らずに目標に照らして確かめる(review)作業を、 目標の固定 →(update は現状の検査)→ 設計 → 設計レビュー → 実装 → 実装レビューの段で回し、見落としを構造で減らす汎用の仕組み。 1 体には 1 単位だけを任せ、テストは実装と別の担当が先に書き、レビューは coverage-audit を呼び、悪かった出来事を探索グラフで振り返って 欠陥を原因の層(目標・設計・実装)へ戻す(指摘の箇所だけを直す経路は持たない)。台帳は run をまたいで持ち越し、変わったものだけを見直す。 「この機能を設計からレビューまで通して作って」「このスキルを目標に合わせて直して(文書とコードが混ざってよい)」 「この実装が目標を満たすか確かめて、直すならどの層からかを返して」のような依頼で使う (Use when building or updating documents or code through goal, design, design review, implementation, and implementation review with layer-routed rework)。 対象外: 目標に照らした網羅的な検査だけで振り返りも要らないもの(coverage-audit)、1 体で 1 回で済む小さな変更、このリポジトリの差分・PR のレビュー(repo-review)。

★ 1
yoshiysh
yoshiysh/claude-plugins

coverage-audit

与えられた目的と対象(設計・計画・要求・仕様・コード・テストなどのファイル)を、資産 × 観点の枡に分けて網羅的に検査し、 確かめた指摘と、見ていない所(開示した枡)を台帳に残して返す検査専用の仕組み。1 体には 1 枡だけを渡し、 読んだ証拠を本文の区画ごとの逐語の引用で機械が照らし、読む役と別のモデル・反証側の検証役が指摘を確かめ、 悪かった出来事を振り返り、確かめた欠陥を根本原因で束ねて型を全ての資産へ横展開する。台帳は run をまたいで持ち越し、変わった枡だけを読み直す。 「修正の前にこの設計・計画を観点ごとに漏れなく検査して」「この実装が目的と仕様を満たすか網羅的に検証して」 「前回の台帳の続きから、変わった所だけ検査し直して」のような依頼で使う(Use when files must be audited for every part × every lens with machine-checked evidence, without fixing them)。 対象外: 修正・生成の実行(このスキルは指摘と網羅の記録までを返し、直すのは呼ぶ側)、1 体で 1 回で済む小さな確認、このリポジトリの差分・PR のレビュー(repo-review)。

★ 1
yoshiysh
yoshiysh/claude-plugins

summarizing-meeting-notes

会議後に書かれた議事録・会議メモ・文字起こしテキストと、会議の録音ファイル(.mp3 / .m4a)を読み、 決定事項・アクションアイテム・未決事項を区分した要約を作る。 「この議事録を要約して」「会議メモから宿題を抜き出して」「定例の決定事項をまとめて」 「先週の打ち合わせの要点を出して」のように、 会議の記録から決定・宿題・未決を知りたい依頼なら使うこと。 記録が箇条書き数行のメモでも使うこと。 対象外: 会議中のリアルタイムな記録取り、議事録以外の文書(企画書・報告書)の要約、 1on1・面談の記録の要約。

★ 1
yoshiysh
yoshiysh/claude-plugins

release-notes-editor

リリースノートの下書きを、利用者と 1 項目ずつ確かめながら書く。「次のリリースのリリースノートを書いて」「リリースノートを作って」という依頼で使う。リリースノートの翻訳と、コミットメッセージの書き直しには使わない。

★ 1
yoshiysh
yoshiysh/claude-plugins

glossary-sync

リポジトリの用語集 docs/glossary.md と、文書の中の用語の使い方の食い違いを洗い出す。「用語集と文書の食い違いを調べて」という依頼で使う。用語集の新規作成と翻訳には使わない。

★ 1
yoshiysh
yoshiysh/claude-plugins

review-document

[When] Use when a Japanese explanatory document (requirements, rules, README, skill text) needs a readability review or revision. または短く書き直したいとき。[What] 「短さ・平易さ・独自用語の不使用」の3軸で証拠つき採点を行い、 求められれば内容を落とさない改稿案を作って before/after を示す(native Workflow は staging、Codex runner は本文をインラインで返却)。 「この要求文書を読みやすさの観点で見て」 「この rule、冗長じゃないか採点して」「この README を短く書き直して」「PRD を渾身の言語化の 基準でレビューして」「独自用語が多すぎないか確認して」といった依頼で使うこと。 他のドキュメント生成スキル(prd-spec など)から監査の観点として呼ばれる場合にも使う。 文書の新規執筆、コードレビュー、翻訳は対象外。対象の文書パスが示されていない依頼では 採点に入らず、どの文書かを1回だけ聞き返す。

★ 1