ktaroabobon explain
プロジェクトを調べて説明する。読むだけ。 説明を README やオンボーディング文書として書き出す依頼があっても、このスキルの中では書かない(保存先を提案して、別ターンで明示的な指示を受けてから書く)。
disallowed-tools で Write / Edit を外している。「説明のついでに README を直す」が起きると、説明の正確さよりも書いた内容の正当化に引っ張られる。
原則
読んだものだけを事実として書き、読んでいないものは推測と明示する。
全部は読めない。だから「どこを読んで何が分かったか」と「読んでいないが構成からこう見える」を分けて書く。読み手はそれで、説明をどこまで信じて次に何を見るべきかを判断できる。
引数
path: 対象ディレクトリ。省略時はカレント--for user | agent: 読み手。省略時はuseruser: 人向け。プロジェクトの説明として読める文章agent: 自分(エージェント)向け。以後の作業に要る情報(コマンド、規約、触ってはいけない場所、次に読む場所)に寄せる
Step 1: プロジェクトの指示を先に読む
AGENTS.md / CLAUDE.md / .agents/ / .claude/ / .codex/ / README.md / docs/ の入口を読む。プロジェクトの指示は一般的な推測より優先する。ここに書かれたコマンドや規約は、後の節でそのまま使う。
Step 2: スタックを特定する
マニフェスト・設定ファイルから判断する: package.json / pnpm-lock.yaml / pyproject.toml / requirements.txt / go.mod / Cargo.toml / Gemfile / pom.xml / build.gradle / CMakeLists.txt / platformio.ini / compose.yaml / Dockerfile / .github/workflows/ / Makefile / Taskfile.yml / justfile。
実行・ビルド・テストのコマンドはドキュメントか設定ファイルに書かれているものを拾う。書かれていない推測コマンドは「(未確認)」と付ける。コマンドを実行して確かめない — 説明のためにビルドやテストを走らせると、副作用や時間がかかる。
Step 3: 構造を地図にする
git ls-files | head -200 # git 管理下なら。深さ 2〜3 までで全体像を掴む
node_modules/ / .venv/ / vendor/ / dist/ / build/ / target/ / キャッシュ / 生成物は読まない。巨大なツリーを丸ごと出力しない。
Step 4: 代表的なファイルを読む
構成を理解するのに必要な分だけ読む: エントリポイント、主要モジュール、ルーティング / コマンド定義、設定、テストの置き場所と書き方。プロジェクト種別で変える(Web アプリならルートとモデル、CLI ならコマンド定義、組み込みならターゲットと HAL、ライブラリなら公開 API)。
Step 5: 説明を書く
次の構成で、短い節を並べる。該当が無い節は「該当なし」と 1 行で残す(何を見なかったかが伝わる)。
- 概要 — 何をするものか、誰のためか(1〜3 文)
- スタック — 言語 / フレームワーク / パッケージ管理 / 主要な依存
- ディレクトリ — 主要なディレクトリと役割(表)
- 動かし方 — 実行 / ビルド / テスト / lint のコマンド。出典(ファイル名)を添える
- 重要なファイル — 最初に読むべきもの 5 個前後
- 構成の要点 — データの流れ、境界、規約、目立つ設計判断
- 注意点と不明点 — リスク、壊しやすい場所、読んでいない領域、矛盾して見える箇所
- 次に見るべき場所 — この説明の次に読む・試すと理解が進むもの
--for agent のときは 4・6・7・8 を厚く、1・2 を薄くする。
やらないこと
- ファイルを作らない・変えない。書き出しを求められたら保存先を提案して待つ
- ビルド・テスト・インストールを実行しない
- 読んでいないファイルの中身を断定しない
完了時に返すもの
Step 5 の構成の説明。末尾に 1 行で、読んだファイルの数と主要なもの、読んでいない領域を書く。