dx-audit

DX 監査

問題が起きたときに開発者がインポート、実行、設定、参照するものを監査または改善します。

• 対象： 公開 API、開発者向けエラー、CLI コマンド、エクスポートされる型、インストールと初回実行時の動作、設定を範囲を限定してレビューします。修正は依頼があった場合にのみ行います。
• 対象外： リポジトリ全体の品質チェック（tidy）、エンドユーザー向け UI（ui-design の Audit モード）、エージェントの信頼性レビュー（ax-audit）、公開サイトやドキュメントのエージェント対応状況のスコア（agent-ready）、ドキュメントの文章や README（ghostwriter）、リポジトリのアーキテクチャ（codebase-architecture）、新しい CLI の構築（scaffold-cli）。

モード

依頼の範囲に合う最も限定的なモードを選び、コードを読む前に、対象範囲を示す一行の記録を書きます。

モード	適用される場合	出力
対象を限定（デフォルト）	名前が指定された、または変更された公開サーフェス	指摘事項レポート（読み取り専用）
修正	ユーザーが修正、改善、簡素化、実装を依頼した場合	記録した範囲内での局所的な編集と、その後の検証
網羅的	ユーザーがパッケージ全体またはすべての公開サーフェスを明示的に依頼した場合	サーフェスごとに分類した、重要な指摘事項すべて

Scope: <mode>; surfaces: <commands/exports/config>; prefixes: <err-, cli->; excludes: <UI, docs, architecture, private internals>

「DX」「ゴールドスタンダード」「全体的なレビュー」といった表現だけでは、対象を限定した監査を網羅的な監査に広げません。複数のスキルを併用する場合、このスキルが担当するのは上記のサーフェスのみです。

監査の進め方

DX audit progress:
- [ ] 1. Lock the public surface and write the scope receipt
- [ ] 2. Gather local evidence and run the safe probes
- [ ] 3. Select prefixes, then open candidate rules
- [ ] 4. Rank root causes
- [ ] 5. Report, or fix when asked
- [ ] 6. Verify on the same scope

1. 公開サーフェスを確定する

通常のベースとの差分を git diff で確認し、公開エントリーポイントから到達可能な変更ファイルだけを対象にします。公開エントリーポイントには、package.json の exports または bin、コマンドレジストリ、エクスポートされた型、文書化された設定ローダー、確認済みのエラーパスが含まれます。有用な差分がない場合は、ユーザーが指定したコマンド、エクスポート、エラー、設定を対象にします。プライベートヘルパーを対象に含めるのは、公開の呼び出し元を通じてのみです。

2. 根拠を集め、そこで止める

1. ローカルの指示、マニフェスト、差分、または指定されたエントリーポイント。
2. 直接依存する公開パッケージと、動作を保証する最も近いテスト。
3. ローカルビルドに対する安全な確認：
   • CLI：--help、--version、成功するケースを1つ、無効な入力のケースを1つ、さらに同じコマンドの標準出力をパイプで渡した場合（| cat）を実行し、TTY 以外での動作を確認します。DX のテストに実際の変更操作を決して発生させないでください。--dry-run がある場合は使用します。
   • パッケージ：ビルド後に pnpm dlx publint と pnpm dlx @arethetypeswrong/cli --pack . を実行します。これらはパッケージングを検査しますが、パッキングによってライフサイクルスクリプトが実行される場合があります。--pack を実行する前に、そのスクリプトを確認するか、使い捨てのチェックアウトを使用してください。
4. 差分によって公開エクスポート、シグネチャ、または戻り値の形状が変わる場合に限り、以前のリリース時の契約を確認します。

動作が証明または否定された場合、プライベートなものだと判明した場合、あるいは範囲外だと分かった場合は、確認を終えます。外部調査を行うのは、比較を明示的に依頼された場合、またはローカルの根拠では解決できない不確実性が明示された場合に限ります。このスキルが参照する標準は、references/standards-map.md に記載されています。

3. 候補優先のディスパッチルール

まず rules/_sections.md を読み、対象面に応じてプレフィックスを選択します。

優先度	プレフィックス	カテゴリー	デフォルトの影響度	ルール
1	api-	パブリック API と SDK	CRITICAL	7
2	err-	開発者向けエラー	CRITICAL	5
3	cli-	人間とエージェント向けの CLI UX	HIGH	13
4	types-	エクスポートされる型の使いやすさ	HIGH	5
5	onboard-	インストールと初回実行	HIGH	5
6	config-	設定の使いやすさ	MEDIUM	3

対象面	プレフィックス
パブリック API のエントリーポイント	api-、types-、該当する err- のパス
CLI コマンド	cli-、該当する err- のパス
エクスポートされる宣言	types-、動作が変更された場合は api- も
インストール、package.json、初回実行	onboard-
設定ローダー	config-、該当する err- のパス

適用可能性は優先度より上位です。CLI のみを対象とした監査では、API ルールの優先度が高くても api- は読み込みません。

対象指定モード：選択したプレフィックスのファイル名を一覧にします（名前がチェックリストです）。具体的な根拠を探し、指摘に必要なルールファイルだけを開きます。網羅モード：選択したプレフィックスのすべてのルールを読みます。

選択したプレフィックス内で適用する機能ゲート：

• 自動化またはエージェントによる利用が約束されている、要求されている、またはすでにサポートされている場合、構造化 JSON 入力、スキーマのイントロスペクション、コンパクトなポーリングスナップショットが適用されます。
• ドライランと確認は、破壊的、高コスト、または元に戻すことが難しい変更に適用されます。
• 進捗と再開は、処理がブロックする可能性がある場合、1 つのコマンドの実行時間を超える場合、または出力が曖昧な場合に再試行される場合に適用されます。
• stdin は、コマンドが意味的にファイルまたはストリームのデータを受け付ける場合に適用されます。
• 安定したコントラクトとの比較は、パブリックコントラクトが変更された場合にのみ適用されます。

4. 個別事例ではなく根本原因をランク付けする

• 引用した各ルールのフロントマターにある impact をそのまま使用して、CRITICAL、HIGH、MEDIUM の順に並べます。影響度はルールで宣言された結果であり、確信度のスコアではありません。たとえば、あるサブコマンドの失敗時に終了コードが 0 でも HIGH です。無効になる CI ゲートは同じだからです。引用する前にルールファイルを開いてください。ID を記憶に頼るとファイルの内容とずれる可能性があり、そのようなファイルが存在しない場合は引用を削除します。
• 同じ根本原因による繰り返しの事例は、代表的な場所を最大 3 つ挙げて 1 件の指摘にまとめます。JSDoc、エラーコード、または --json が対象面全体で欠けている場合、シンボルごとではなく 1 件の指摘とします。
• 現在利用する経路がない機能の欠如は、不具合ではありません。
• 対象指定モード：すべての CRITICAL の指摘を挙げ、その後、優先度の高いものから最大 5 件まで追加し、残りはカテゴリー別にまとめます。

5. 報告または修正

監査依頼は読み取り専用です。修正依頼では、隣接するドキュメント、UI、アーキテクチャを再設計するのではなく、受領範囲内の局所的な変更が許可されます。

## DX Audit

Scope: `tool status` CLI; `err-`, `cli-`; 4 files inspected.

### Findings
- [HIGH] `cli-idempotent-resume` at `src/start.ts:42`: retrying the same target creates a second job.
  Fix: return the existing job id and state unless the caller passes `--fresh`.

### Deferred
- 2 lower-impact config candidates were outside the locked CLI scope.

指摘があるファイルのみを一覧にします。問題のない対象面については、確認した対象面とルールファイルを記載したパス行を 1 行だけ記載します。修正モードでは、Deferred を Changed と Verification（成功した正確なコマンドまたはプローブ）に置き換えます。分量はテンプレートではなく、指摘の数に応じて調整します。

6. 同じ範囲で検証する

変更または引用したすべての箇所を再度開き、同じプローブと対象を絞ったプロジェクトチェックを再実行し、同じ候補ルールを再適用します。根拠を主張に対応させます。ビルドが成功しても CLI の動作は証明されません。実行時プローブではエクスポートされた型は証明されません。また、型の解決を証明できるのは attw または利用側の tsc インポートだけです。

参照ファイル

ファイル	読むタイミング
rules/_sections.md	すべての監査で、プレフィックスの適用可能性と優先度を確認するため
rules/<prefix>-*.md	候補に根拠がある場合、または網羅モードの場合
references/standards-map.md	指摘に外部の引用が必要な場合、ユーザーが何かがルールである理由を尋ねた場合、または判断が難しいケースの決め手が必要な場合
rules/_template.md	ルールを追加または編集する場合

注意点

• pnpm dlx <pkg>（または npx）やグローバルインストールでは、作業ツリーではなくレジストリ上のコピーが検証されます。 その場合、--help、終了コード、エラーメッセージはリリース済みバージョンの内容になります。ビルドしてから、ローカルのエントリーポイント（node ./dist/cli.js）を実行してください。
• パイプ経由では、process.stdout.isTTY は false ではなく undefined になります。 isTTY === false と書かれたガードでは、パイプ接続時にカラーやスピナーが無効にならず、ANSIコードがリダイレクト先のファイルに出力されます。ガードを信用せず、| cat で確認してください。
• console.log の直後に process.exit(1) を呼び出すと、説明のために出力した内容が途切れることがあります。 パイプ接続時、stdoutへの書き込みは非同期なので、使用方法を出力して exit() を呼び出すCLIは、| cat の下では何も出力しないことがあります。対処方法は、process.exitCode = 1 を設定して自然に戻ることです（cli-exit-codes）。
• 正しく読める exports マップでも、解決先が誤っていることがあります。 "type": "module" の下で "require" が .js ファイルを指すとCJSを装い、import より後に記述された types 条件には到達しません。publint と attw なら両方を検出できますが、マップを読むだけでは検出できません（onboard-exports-resolve-typed）。

関連スキル

• ui-design の監査モード：レンダリングされたエンドユーザー向けフロントエンドの品質とアクセシビリティ
• ax-audit：同じファイルを対象にしますが、読み手が異なります。このスキルでは開発者にとって使いやすい表層かを確認するのに対し、エージェントが操作や復旧を行えるかを確認します
• scaffold-cli：これらのパターンをあらかじめ組み込んだ新しいCLIを構築します。このスキルでは既存のものを監査します
• tidy：差分の一般的な正確性と構造
• agent-ready：公開HTTP／ドキュメントに関するエージェント向けスコア（AFDocs、Is Agentic、Is It Agent Ready）。このスキルでは、パッケージができた後に監査します
• ghostwriter：ドキュメントの文章、READMEの構造、初めて読む人向けのストーリー
• agents-md：AGENTS.md および CLAUDE.md の指示ファイル
• codebase-architecture：パッケージが外部に提供する表層ではなく、リポジトリ内の構造とモジュールの契約

保守専用：evals/evals.json と evals/evaluation-scenarios.md には、このスキルの変更に対する回帰シナリオが含まれています。どちらもユーザーのタスク中には読み込まれません。