5.3 KiB
5.3 KiB
name, description, argument-hint
| name | description | argument-hint | |
|---|---|---|---|
| doc-lint | ドキュメントがAGENTS.mdの運用ルール1〜5に沿っているか検査する。推測タグと未確認事項の対応漏れ、保留課題の書式・参照・必須欄、journalへのリンク、比較表の混入などを検出する。 |
|
ドキュメントのルール違反を検査する
機械的に判定できる項目はスクリプトで検出し、判断が要る項目だけ目視で見る。 検出して報告するだけで、勝手に直さない。 修正は内容を確認してもらってから。
1. スクリプトを走らせる
python .Codex/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 | backlogの項目IDが不正・検査対象内で重複する、必須5欄がない・空である |
| ERROR | backlogに推測タグがある、参照先ファイルが存在しない |
| ERROR | journal へのリンク / journal から他ファイルへのリンク |
| ERROR | ## 検討済み・非採用 の項目が journal ファイル名を参照していない |
| ERROR | journal のファイル名が YYYY-MM-DD-<topic>.md 形式でない |
| WARN | ## 検討済み・非採用 が5件を超えた |
| WARN | journal の冒頭20行に結論が見当たらない |
| WARN | メインドキュメントに比較表・優先度評価・却下案の記述らしきもの |
本文タグのない ## 未確認事項 の項目はエラーにしない。 実装前に判断が必要な未解決の問いとして正当。
設計判断は「完了条件」でよい。タグなしの項目が事実確認なのか設計判断なのかは、目視で確認する。
backlogでは ### PHY-P-14 題名 のように区分付きIDを使い、関連仕様・未決事項・保留できる理由・再開条件・完了条件を必須とする。
仕様書側の書式は - [PHYの保留課題](backlog/README.md#phy)。
backlogは短い候補・制約を保持できるため、メインドキュメント向けの散文ヒューリスティックは適用しない。
WARN の散文検出は当たりが粗い。取りこぼしも誤検出もあるので、出た/出ないを結論にしない。
2. スクリプトで見られない項目を確認する
こちらが本体。ファイルを読んで判断する。
- 「なぜBではないのか」が理由として残っていないか。
却下理由ではなく、現在効いている制約として書かれているか。
- ✗
階層構造はKLEが非対応なので諦めた - ○
階層クラスターはKLE JSONに出力しない(KLE互換性の制約)
- ✗
- 本文が前提にする未確認の記述にタグが付いているか。 検査項目の中で最も重要で、
機械では判定できない。「〜できるはず」「〜と考えられる」「実現可能」で実際に試していない
記述を探し、
[推測:P-n]が付いているか確認する。 - 同じ事実が複数ドキュメントに複製されていないか。 片方だけ古くなる。
- 保留中の対応範囲が仕様本文にあるか。 現在の実装が答えに依存する前提をbacklogへ隠していないか。
- 再開条件・完了条件が具体的か。 仕様書の保留課題リンクは該当区分に向き、解決済みの課題が残っていないか。
- journal の冒頭20行で、結論と選択肢が分かるか。 見出しの有無ではなく中身を読む。
- コミット規約(必要なら
git log --onelineを見る)- 1コミット1決定になっているか
- journal を伴う決定のメッセージに
Journal:行があるか
3. 報告する
ERROR / WARN / 目視で見つけたもの を分けて出す。 修正案は出してよいが、適用は確認を取ってから。事実関係の誤りを見つけた場合も、直さず指摘する。
注意
- 既存ドキュメントへのルール適用は段階的に進めている。
WARN が大量に出るのは想定内で、再編(
/restructure-doc)のタイミングで解消する。 再編前のファイルの WARN を個別に直そうとしない。
スクリプトを変更した場合の回帰検査:
python -B -m unittest discover -s .Codex/skills/doc-lint -p test_doc_lint.py