AgentSkillsCN

Doc Health Check

开展健全性检查,及时发现并修正文档与实现之间的偏差。当被要求对文档进行维护与更新时,可使用此方法。

SKILL.md
--- frontmatter
description: "ドキュメントと実装の乖離を検出・修正する健全性チェックを行う。ドキュメントのメンテナンス・最新化を求められたときに使用"
user-invocable: true

ドキュメント健全性チェック

packages/*/docs/ のドキュメントと packages/*/src/ の実装を突き合わせ、乖離を検出・修正する。

チェック対象

各パッケージの docs/ 配下の全 .md ファイルを対象とする:

  • packages/engine/docs/*.md
  • packages/input/docs/*.md
  • packages/stroke/docs/*.md

チェック手順

Step 1: パッケージごとに並行調査

3パッケージを Task tool で並行に 調査する。各エージェントに以下を指示:

  1. docs/ 配下の全 .md ファイルを読む
  2. 各ドキュメントに記載された関数・型について src/ のソースコードと突き合わせる
  3. 以下の観点で不一致を検出:
    • 関数シグネチャ: 引数名・型・オプショナル・デフォルト値
    • 型定義: フィールド名・型・readonly 修飾子
    • エクスポート: index.ts から export されているか
    • 存在確認: ドキュメントに書かれた関数・型がソースに存在するか
    • 記載漏れ: index.ts で export されているがドキュメントに未記載のシンボル
  4. 構造化されたレポートを返す(日本語)

Step 2: 結果の分類

発見した乖離を以下の類型に分類する:

類型説明対応
A. コード変更の未反映シグネチャ変更・デフォルト値変更・型拡張がドキュメントに反映されていないドキュメントを修正
B. 型表記の不正確readonly 欠落、エイリアス型の展開ミスなどドキュメントを修正
C. 新規APIの記載漏れエクスポートされているがドキュメントに未記載ドキュメントに追記
D. 設計時構想の残存実装されなかった関数・型がドキュメントに残っているドキュメントから削除

Step 3: 修正の適用

  • 乖離をユーザーに報告し、修正の方針を確認してから適用する
  • 修正はドキュメント側に対して行う(コード側が正)
  • 修正後、変更したファイルの一覧を提示する

レポート形式

markdown
## ドキュメント健全性チェック結果

### サマリ

| パッケージ | ファイル数 | OK | 乖離あり | 乖離件数 |
|-----------|----------|-----|---------|---------|
| engine    | N        | N   | N       | N       |
| input     | N        | N   | N       | N       |
| stroke    | N        | N   | N       | N       |

### 乖離一覧

#### [類型A] コード変更の未反映

- **ファイル**: `packages/xxx/docs/yyy.md`
  - ドキュメント: `(ドキュメントの記述)`
  - 実装: `(実際のソースコード)`
  - 修正案: (具体的な修正内容)

(類型ごとにグループ化)