ewderna/Beyond-KLE
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
54f292b08ef05014ec3a791a69aa04c0e02a825b
Beyond-KLE/.agents/skills/doc-lint/SKILL.md
T
ewdernaandClaude Opus 5 54f292b08e agent: decide/doc-lintを更新し、.agents と .claude を同期 
codexが .agents 側で更新した内容を .claude へ取り込み、名前依存の箇所だけ
置換した。両ツリーの差分はCLAUDE.md/AGENTS.mdとパスの表記のみ。

- 非採用一覧の掲載基準をルール1の変更に合わせる
- 本文の「未決」はリンク・課題追加・言及削除のいずれかを判断する(ルール4)
- 責務を外へ移したあと、担当範囲が分かる一文と参照が残っているか確認する
- doc-lintに未確認事項リンクの参照先・ラベル整合の検査(ERROR)と、
  リンクのない課題番号・参照なしの「未決」「未定」の検出(WARN)を追加
- load() のコードフェンス処理が ~~~ や長さ違いを扱えていなかったのを修正
- .Codex という実在しないパスの参照を .agents に修正

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MtVk8W4yK6j3eCqQpEQBLS
2026-09-22 22:32:18 +09:00

7.4 KiB
Raw Blame History

name, description, argument-hint
name description argument-hint
doc-lint ドキュメントがAGENTS.mdの運用ルール1〜5に沿っているか検査する。推測タグと未確認事項の対応漏れ、保留課題の書式・参照・必須欄、journalへのリンク、比較表の混入などを検出する。
ファイル...

ドキュメントのルール違反を検査する

機械的に判定できる項目はスクリプトで検出し、判断が要る項目だけ目視で見る。 共通の運用ルールは、AGENTS.mdの参照先であるCLAUDE.mdを正とする。 検出して報告するだけで、勝手に直さない。 修正は内容を確認してもらってから。

1. スクリプトを走らせる

python .agents/skills/doc-lint/doc-lint.py [ファイル...]

Python 3.9以上で実行する。引数なしでリポジトリ直下の *.md、journal/*.md、backlog/**/*.md を全部見る。 実行場所にかかわらずリポジトリを基準に分類し、明示したパスは実行ディレクトリから解決する。 ERROR があれば終了コード 1。存在しない引数のファイルもERRORにする。

検出する項目:

種別 内容
ERROR 本文の [推測:P-n] に対応する ## 未確認事項 の項目がない
ERROR 本文の推測タグに対応する項目に - 格上げ条件: の内容がない
ERROR タグのない未確認事項に - 格上げ条件: または - 完了条件: の内容がない
ERROR ## 未確認事項 のIDが重複している
ERROR 未確認事項へのローカルリンクの参照先ファイル・見出しがない、または個別項目へのリンクが未確認事項の項目を指していない
ERROR リンクラベルの課題番号と参照先の課題番号が一致しない
ERROR 仕様書の ## 保留課題 がリンク箇条書き以外を含む、空である、参照先ファイル・見出しがない
ERROR 末尾の管理セクションが重複する、保留課題 → 検討済み・非採用 → 未確認事項の順でない
ERROR backlogの項目IDが不正・検査対象内で重複する、必須5欄がない・空である
ERROR backlogに推測タグがある、参照先ファイルが存在しない
ERROR journal へのリンク / journal から他ファイルへのリンク
ERROR ## 検討済み・非採用 の項目が journal ファイル名を参照していない
ERROR journal のファイル名が YYYY-MM-DD-<topic>.md 形式でない
WARN ## 検討済み・非採用 が5件を超えた
WARN 本文の段落・箇条書き項目に、リンクのない課題番号や、課題への参照を伴わない「未決」「未定」がある
WARN journal の冒頭20行に結論が見当たらない
WARN メインドキュメントに比較表・優先度評価・却下案の記述らしきもの

本文タグのない ## 未確認事項 の項目はエラーにしない。 実装前に判断が必要な未解決の問いとして正当。 設計判断は「完了条件」でよい。タグなしの項目が事実確認なのか設計判断なのかは、目視で確認する。

backlogでは ### PHY-P-14 題名 のように区分付きIDを使い、関連仕様・未決事項・保留できる理由・再開条件・完了条件を必須とする。 仕様書側の書式は - [PHYの保留課題](backlog/README.md#phy)。 backlogは短い候補・制約を保持できるため、メインドキュメント向けの散文ヒューリスティックは適用しない。

WARN の散文検出は当たりが粗い。取りこぼしも誤検出もあるので、出た/出ないを結論にしない。 未確認事項リンクの検査対象は [P-3](#p-3-...)・[MAPのP-3](MAPレイヤー.md#p-3-...) 等の インラインリンク。Markdown全般のリンク検査ではない。 「未決」「未定」のWARNは、次行の参照も同じ段落として扱う。コード例、末尾の管理セクション、 journal、backlog、ルールブック自体はこのWARNの対象外とする。 WARNから課題の追加や本文の削除を自動決定しない。

2. スクリプトで見られない項目を確認する

こちらが本体。ファイルを読んで判断する。

  • 「なぜBではないのか」が理由として残っていないか。 却下理由ではなく、現在効いている制約として書かれているか。
    • ✗ 階層構造はKLEが非対応なので諦めた
    • ○ 階層クラスターはKLE JSONに出力しない(KLE互換性の制約)
  • 本文が前提にする未確認の記述にタグが付いているか。 検査項目の中で最も重要で、 機械では判定できない。「〜できるはず」「〜と考えられる」「実現可能」で実際に試していない 記述を探し、[推測:P-n] が付いているか確認する。
  • 同じ事実が複数ドキュメントに複製されていないか。 片方だけ古くなる。
  • 他の担当の説明を移した結果、責務の境界まで消えていないか。 この文書だけで担当範囲が分かるための一文と参照は残し、他の担当の詳細仕様は参照先で管理する。
  • 非採用一覧の各項目は、将来のどんな再提案を防ぐか。 本文の制約で十分か、実際に検討した別方針として経緯への入口が必要かを判断する。 件数・古さ・重複だけで一律に追加・削除しない。
  • 本文の未決記述は、読者に何を伝えるためにあるか。 現在の対応範囲は本文に残し、問いの詳細は未確認事項へ集約する。 対応項目へのリンク、必要な課題の追加、不要な言及の削除のいずれかを判断する。 リンクが存在しても、その問いが本文の内容に対応するかは目視で確認する。
  • 保留中の対応範囲が仕様本文にあるか。 現在の実装が答えに依存する前提をbacklogへ隠していないか。
  • 再開条件・完了条件が具体的か。 仕様書の保留課題リンクは該当区分に向き、解決済みの課題が残っていないか。
  • journal の冒頭20行で、結論と選択肢が分かるか。 見出しの有無ではなく中身を読む。
  • コミット規約(必要なら git log --oneline を見る)
    • 1コミット1決定になっているか
    • journal を伴う決定のメッセージに Journal: 行があるか

3. 報告する

機械検査のERROR / WARNと、目視で確認した内容・未確認の範囲を分けて報告する。 機械検査が0件でも、内容の分類・責務の境界・記録の必要性が適切だった証明にはしない。 目視確認を省いた場合はその旨を明記する。 修正案は出してよいが、適用は確認を取ってから。事実関係の誤りを見つけた場合も、直さず指摘する。

注意

  • 既存ドキュメントへのルール適用は段階的に進めている。 WARN が大量に出るのは想定内で、再編(/restructure-doc)のタイミングで解消する。 再編前のファイルの WARN を個別に直そうとしない。

スクリプトを変更した場合の回帰検査:

python -B -m unittest discover -s .agents/skills/doc-lint -p test_doc_lint.py
Reference in New Issue View Git Blame Copy Permalink