AgentSkillsCN

doc-enricher

在代码阅读或任务执行完成后，仅将持久性强且高杠杆的知识条目提交至目录的 README 中。默认情况下仅进行建议，只有在用户确认后才更新 README 或 docs。禁止新建或创建新的文档。

SKILL.md
--- frontmatter
name: doc-enricher
description: "コードリーディング/タスク遂行後に、永続性が高く高レバレッジな知識だけをディレクトリREADMEに提案する。デフォルトは提案のみ。ユーザー承認後にのみREADME/docsを更新。新規docs/作成は禁止。"
allowed-tools: Read, Grep, Write, Edit

skill: doc-enricher（ディレクトリREADME知識の強化）

目的（Goal）

コードリーディングやタスク遂行の後に、次回以降の読み解き／探索／レビューを楽にするための 「永続性が高く、効果が大きいナレッジ」だけをドキュメント化する。

主な置き場所は ディレクトリ配下の README。 やむを得ない場合のみ、既に存在する上位ディレクトリの docs/ に置く（※新規に docs/ を作るのは禁止）。

運用モード（重要）

  • •デフォルト動作は Phase 1: 提案のみ とする（ファイル変更はしない）
  • •README/docs の作成・修正は ユーザーが承認した後のみ 実施する
  • •当面は常に承認を要求する（出力が安定して不要になったら、別途ルール変更で緩和可能）
  • •日本語で会話すること

対象外（Non-goals：絶対にしない）

  • •“薄いナレッジ”（当たり前・低レバレッジ・行単位の説明）を書かない
  • •“調査スナップショット”（数値・ログ・現状の羅列など、腐りやすいもの）を残さない
  • •ドキュメント置き場を勝手に増やさない（新しい docs/ を作らない）
  • •ユーザー合意なしに、ファイル作成／修正をしない

実行タイミング（When to run）

  • •タスク完了後
  • •レビュー対応後
  • •まとまったコードリーディングの後

必要な入力（Inputs required：作業場から取得するもの）

  • •ディレクトリ構造と、読んだ／触った関連ファイル
  • •（あれば）レビュー指摘と、「どのナレッジがコード上に書かれていなかったか」
  • •コードリーディング中に「どこ見ればいいの？」が何度も発生した箇所

出力（Output：3フェーズ）

Phase 1: 提案（ファイル変更なし）

  1. •候補ナレッジ一覧（生の素材）
  2. •自己レビュー（ゲート）による絞り込みと、落とした理由
  3. •最終提案（ドキュメント更新案）
    • •追記／更新するファイルパス（README優先）
    • •追加／更新するセクション（日本語テンプレに沿う）
    • •追記する箇条書き（簡潔に、確定文で）
  4. •誤った／腐るドキュメントになりそうで回避不能な場合のみ、最小限の質問

Phase 2: 適用（ユーザー承認後のみ）

  • •承認された内容だけ README / docs を作成・更新する
  • •変更は最小（関係ない箇所の大規模リライトは禁止）
  • •置き場所の優先順位：
    1. •対象ディレクトリの README
    2. •既存の上位 docs/（※存在する場合のみ。新設禁止）

Phase 3: 振り返り

  • •このスキル定義ファイルについて、変更の必要があるか確認
    • •不要であれば、修正は禁止

残してよいナレッジの型（Knowledge types allowed）

A) モジュールの役割（Why/What）＋明確な非責務（やらないこと） B) 探索・読解の索引（どこから読むか／入口／grepで引っかかるキーワード） C) 不変条件・制約（守るべき契約／破ると事故る条件） D) 安全な変更ガイド（Xを変えるならYも見る、影響範囲の“型”）

自己レビュー・ゲート（全て通過必須）

Gate A: 永続性が高い（6ヶ月後でも正しい確率が高い） Gate B: レバレッジが高い（時間を大きく節約／レビュー指摘の再発を防ぐ） Gate C: 非自明（1ファイル読めば分かる程度の内容ではない） Gate D: 探索性が上がる（grep／スキャンの導線になり、安定キーワードを提供する） Gate E: 低メンテ（頻繁な更新が必要にならない）

どれか1つでも落ちたら：DROP（捨てる）し、理由を1行で記録する。

文体・書き方ルール（Style rules）

  • •短い箇条書き優先。長文エッセイ禁止。
  • •コードに存在する安定した用語・名前を使う（grepに強くする）。
  • •MUST/SHOULD/MAY を意図的に使う：
    • •MUST：不変条件／契約／安全要件（破ると止まる）
    • •SHOULD：強い推奨（例外があるなら条件も書く）
    • •MAY：任意のヒント（原則レア）
  • •日付、"currently"（現状）、メトリクス、実装トリビアを避ける。
  • •“いま観測できたこと”より、“こうでなければならない制約”を優先する。

READMEテンプレ（日本語・提案）

1. 概要

  • •このディレクトリ（モジュール）が担う役割（Why/What）
  • •非責務（ここではやらないこと / やるべきでないこと）

2. クイックマップ（読む順・入口）

  • •最初に見るべき入口（例：エントリポイント、主要クラス、主要関数）
  • •「だいたいここを見れば分かる」読み順
  • •grep用の安定キーワード（コードに存在する名前を使う）

3. 不変条件・契約（Invariants / Contracts）

  • •MUST：破ると事故る・レビューで必ず止まる条件
  • •SHOULD：強い推奨（例外があるなら条件も書く）

4. 変更ガイド（安全に変える）

  • •よくある変更パターン（例：「Xを追加する」「Yを差し替える」）
  • •そのとき一緒に確認・修正すべき場所（if X then check Y）
  • •影響範囲の“型”（スナップショットの列挙ではなく関係性）

5. 参照

  • •既存ドキュメントへのリンク（新しい docs/ は作らない）
  • •関連する上位READMEや設計資料への導線（存在する場合のみ）

安全指針（Safety）

  • •永続性に自信がない記述は「弱める」か「捨てる」。
  • •迷ったら DROP（薄い・腐る・保守コスト高いものを優先的に捨てる）。
  • •“観測”を残す必要がある場合は、原則として残さない。どうしても必要なら：
    • •観測ではなく「契約」「制約」「関係性」に抽象化できないか再検討する
    • •抽象化できないなら、その項目は DROP する