cli-self-check

cli-self-check

te-cli の「新機能の妥当性」をセルフチェックするスキルです。人手によるコードレビューで繰り返し使われてきた構造化チェックを、繰り返し実行できるスクリプトと判定ルールとして定着させます。

どんなときに使うか

• 新しいコマンドドメイン（src/commands/te-*）または新しいコマンドをマージしたとき
• skills/ 以下のスキルを追加／変更したとき
• リリース前のセルフチェック、または特定のブランチの CLI 機能が「完成しているか」を評価するとき

実行方法

# 全量扫描（推荐发版前用）
node self-check/scan.mjs

# 只看相对某分支的变更域（推荐合并/提 PR 后用，聚焦本次改动）
node self-check/scan.mjs --since master

# 机器可读，便于接 CI
node self-check/scan.mjs --json

終了コード：P1 が存在する場合は 1、それ以外は 0 を返すため、CI のゲートとしてそのまま使用できます。

スクリプトは純粋な Node で動作し、新たな依存関係はなく、リポジトリを読み取るだけで変更しません。判定と修正は、以下のルールに基づいてあなた（エージェント）が行います。スクリプトは「検出」を担当し、あなたは「確認＋修正」を担当します。

6 つの検査項目

項目	名前	検査内容	不備があるとどうなるか
D1	コマンド登録	新しいドメインが src/index.ts に登録されているか。MCP service に mapping が登録されているか	コマンドがまったく読み込まれない。buildMcpUrl が実行時にエラーをスローする
D2	ドメイン↔スキルの対応	各業務ドメインに対応するスキルがあるか。ツールコマンドにスキルが設定されていないか	エージェントが新しいコマンドの使い方を把握できない
D3	スキルのドキュメント網羅性	コマンド ↔ references/*.md が一対一で対応しているか	エージェントにコマンドのドキュメントがなく、パラメーターを推測せざるを得ない
D4	スキル内の整合性	CRITICAL ルール「+cmd→cmd.md」が実際のファイル名と一致しているか。SKILL.md 内のリンクが切れていないか	エージェントがルールに従ってドキュメントを読んでも内容が空で、ID／パラメーターを推測してしまう
D5	ドキュメントの同期	README（中／英）がすべての service を網羅しているか。バージョン番号と CHANGELOG が一致しているか	ユーザーが README に従って使い、新機能が存在しないと思い込む
D6	エンジニアリングの堅牢性	各ドメインに verify スクリプトがあるか。tsc --noEmit が組み込まれているか	回帰が自動で検出されない。型エラーが build 時に初めて明らかになる

重大度と対応方針

• 🔴 P1（ブロッカー）：コマンドの読み込み失敗、またはエージェントの動作エラー（ドキュメントが空のまま読まれ、推測してしまう）につながります。必ず修正し、CI でブロックしてください。
• 🟡 P2（ユーザー／エージェントに明らかな影響）：ドキュメントの欠落／遅れ、リンク切れです。リリース前に修正してください。
• 🟢 P3（エンジニアリングの堅牢性）：verify／typecheck の不足、スタイルの不統一です。適宜補い、リリースをブロックしません。
• ℹ️ info：規約に沿っていることの確認項目（ツールコマンドにスキルがない場合など）であり、対応は不要です。

各項目の判定と修正方法

D1 コマンド登録

• 「ドメインが src/index.ts に登録されていない」：src/index.ts の loadCommands()（業務ドメイン）または registerXxxCommand()（ツールコマンド）に import('./commands/<dir>/index.js') を追加します。
• 「MCP service に mapping が登録されていない」：MCP transport を引き続き使用するドメインの index.ts の先頭で registerMcpMappings({ '<service>': { componentName, mappingPath } }) を呼び出します（te-community/index.ts を参照）。Analysis ドメインでは Capability Gateway のみを使用でき、MCP mapping を登録してはいけません。
• 2 種類の「service」を区別してください。commander のグループ名（例：engage）≠ MCP のルーティングキー（例：engage_config）です。スクリプトは後者のみをチェックし、リテラルの引数だけを抽出します。変数を渡している場合は報告しません（誤報を避けるため、見逃しは許容します）。

D2 ドメイン↔スキルの対応

• 規約：業務ドメインにはスキルを設定し、ツールコマンド（対話型／運用）には設定しません。sync、model、auth、config、api にスキルがないのは正しい状態です。
• 業務ドメインを追加する場合は、scan.mjs の先頭にある DOMAIN_TO_SKILL に対応関係を登録する必要があります。ツールコマンドを追加する場合は TOOL_DIRS に登録します。登録漏れは P2 として報告され、対応関係の追加、または分類の確認を促します。

D3 スキルのドキュメント網羅性

• 判定には「正規化＋部分一致」を使い、create-team.md が +create をカバーするケースも認識します。そのため、ここで報告されるのは実際にドキュメントが不足している場合です。
• 修正方法：該当するスキルの references/ に .md を追加し、SKILL.md のコマンド一覧からリンクを設定します。
• 「グループ化／インラインドキュメント」方式を採用しているスキル（ae-dataops、ae-kb）は、GROUPED_DOC_SKILLS に登録され、コマンドごとのチェックが免除されています。新しいスキルでもこの方式を採用する場合は、ここに追加してください。

D4 スキル内の整合性（P1 になりやすい項目）

• ルールの矛盾：SKILL.md の先頭に「reference filename equals the command name（+cmd → references/cmd.md）」と記載されている場合、すべてのコマンドに厳密に同名のファイルが必要です。+list のドキュメント名が list-teams.md の場合、エージェントは存在しない list.md を読み込もうとします。
  • 修正方法は 2 つです（どちらかを選択）：① ファイル名をコマンドと厳密に同じ名前（list.md）に変更する——推奨。ルールの整合性が最も高くなります。② 先頭のルールを「以下のコマンド一覧にあるリンクを参照してください」に書き換え、「filename = command name」という断言を削除する。
• リンク切れ：SKILL.md 内の references/xxx.md が存在しないファイルを指しています。ファイルを追加するか、リンクを修正してください。

D5 ドキュメントの同期

• 新しいドメイン／コマンドを README.md と README.zh.md のコマンド一覧に反映してください。
• リリース時には、バージョン番号に対応する項目を CHANGELOG.md に追加してください。

D6 エンジニアリングの堅牢性

• 新しいドメインには scripts/verify-te-<domain>.mjs の追加を推奨します（既存の verify-te-analysis-tools.mjs を参照）。コマンドのソースを走査し、登録、flag、description、ドキュメントの契約を検証します。また、package.json に verify:<domain> スクリプトを追加してください。
• "typecheck": "tsc --noEmit" の追加を推奨します。型チェックを build より前に実行できるようになります。

スクリプトのメンテナンス

scan.mjs の先頭には調整可能な設定があります。モジュールを追加する際に、必要に応じて更新してください。

• DOMAIN_TO_SKILL：業務ドメインのディレクトリ → スキル名の対応
• COMMAND_SKILL_OVERRIDES：同じコマンドドメイン内で overlay スキルが担当するコマンドパス → スキル名の対応
• TOOL_DIRS：ツールコマンドのディレクトリ（スキルチェックの対象外）
• GROUPED_DOC_SKILLS：グループ化／インラインドキュメント方式を採用するスキル（コマンドごとの reference チェックの対象外）

判定の考え方：スクリプトは「人が一度確認する価値のある」手がかりだけを報告し、確認と修正はエージェントがソースを確認したうえで行います。検査項目を追加する際は、誤報をゼロにすることを最優先してください。P1 の誤報は、見逃しよりもツールへの信頼を損ないます。