ewdernaandClaude Opus 5.5
85f333cb24
継続行がスペース2つだと、VS Codeがインデント幅を2と自動判定する。 .vscode/settings.json でMarkdownの自動判定を切って幅4に固定し、 既存の継続行もリストの記号から4つ下げた位置に揃える。 変更したファイルに markdownlint --fix をかけた分(journalのURL囲みと空行)も含む。 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VbfgHT848s3JbuFw8MKFF8
105 lines
7.4 KiB
Markdown
105 lines
7.4 KiB
Markdown
---
|
|
name: doc-lint
|
|
description: ドキュメントがAGENTS.mdの運用ルール1〜5に沿っているか検査する。推測タグと未確認事項の対応漏れ、保留課題の書式・参照・必須欄、journalへのリンク、比較表の混入などを検出する。
|
|
argument-hint: [ファイル...]
|
|
---
|
|
|
|
# ドキュメントのルール違反を検査する
|
|
|
|
機械的に判定できる項目はスクリプトで検出し、判断が要る項目だけ目視で見る。
|
|
共通の運用ルールは、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
|
|
```
|