accelint-ts-audit-all

Audit All

進捗を追跡し、対話形式で承認を得ながら、複数の監査スキルを体系的に適用する包括的な TypeScript ファイル監査システムです。

監査の実行中に絶対にしてはいけないこと

• 最初のテストカバレッジの手順を絶対に省略しないでください - 先にテストカバレッジを確認せずにリファクタリングすると、気づかないまま不具合を引き起こす可能性があります。コードを変更する前に、必ず accelint-ts-testing を実行してください。
• ベストプラクティスとパフォーマンスの監査を順番に実行しないでください - 別々に実行すると、同じコードに対して矛盾した提案が生じます。統合された提案を確認できるよう、必ず並行して実行してください。
• 問題を一つずつ提示して承認を求めないでください - まずすべての問題を番号付きの表で示し、次に各問題の変更前と変更後の詳細なコードを表示し、その後で番号付きリストによる採否を尋ねてください。これにより、提示内容の一貫性が大きく損なわれるのを防ぎ、並行処理で見つかった問題同士の矛盾をユーザーが確認できます。
• 概要表の表示を絶対に省略しないでください - 必須です。詳細な変更を示す前に、すべての問題を含む、重要度を絵文字で示した表を必ず表示してください。例外はありません。
• すべての詳細な変更を示す前に承認を求めないでください - 必須です。「どの問題を適用しますか？」と尋ねる前に、すべての問題について変更前と変更後のコードをすべて表示してください。
• 提案をすべて自動適用しないでください - コードの所有権を維持し、望まない変更を防ぐため、変更ごとにユーザーの承認（採用／拒否／その他）が必要です。
• 文書化された検証コマンドの代わりに、その場限りのコマンドを実行しないでください - audit-process ファイルには、正確な検証コマンドが記載されています。そのコマンドを一字一句そのまま使用してください。記載されたコマンドと完全に一致する場合を除き、npm test、bun test などを即興で実行しないでください。
• 手順を完了した後、進捗の保存を絶対に省略しないでください - 各手順が完了したら、次の手順に進む前に、詳細な進捗をすぐに audit-process ファイルへ保存してください。そうしないと、コンテキストの上限に達したときに進捗が失われます。
• PBT の 100 回連続検証を絶対に省略しないでください - プロパティベーステストを追加した場合は、安定性を確認するためにテストスイートを 100 回実行する必要があります。PBT ではランダムな失敗がよく発生します。これは必須要件です。100 回連続で成功するまで先に進まないでください。速度と安定性を高めるため、カバレッジレポートを無効にしてテストを実行してください。
• コンテキストが上限に達したときに進捗を失わないでください - 各手順の後に、詳細な進捗を audit-process ファイルへ保存してください。大規模な監査では、コンテキストの上限に必ず達します。
• プロパティベーステストが安定していると決めつけないでください - PBT ではランダムなテスト失敗がよく発生します。新しいプロパティテストは、採用する前に安定性を確認するため 100 回実行してください。速度と安定性を高めるため、カバレッジレポートを無効にしてテストを実行してください。
• あらゆる場所に PERF コメントを追加しないでください - 将来の開発者が自力では気づけない、有意義な知見を示す場合に限り、// PERF: コメントを追加してください。
• 9 つすべての手順を完了せずにファイルを完了扱いにしないでください - 監査の一部だけを完了すると、ファイルの状態に一貫性がなくなります。9 つすべての手順を完了するか、進行中として記録してください。
• ビルドの問題を残したまま先に進まないでください - 次の手順に進む前に、コンパイルエラー、テストの失敗、lint の問題をただちに修正してください。
• main ブランチで監査を実行しないでください - 並行する監査との競合を防ぎ、安全に試行できるよう、必ず分離した worktree を作成してください。

監査を始める前に確認すること

包括的な監査を開始する前に、次の項目を確認してください。

スコープの検証

• このパスは有効でアクセス可能ですか？ TODO リストを作成する前に、ファイルまたはディレクトリが存在することを確認してください。
• 利用可能なテストコマンドとビルドコマンドはありますか？ 開始前に package.json を確認するか、ユーザーに検証コマンドを尋ねてください。
• この監査の対象ファイルはいくつですか？ 大きなディレクトリ（5 ファイル超）の監査には、複数回のセッションが必要です。あらかじめ見通しを伝えてください。

セッション管理

• 新しい監査ですか、それとも再開ですか？ 新しいファイルを作成する前に、.agents/audit/ に既存の監査プロセスファイルがないか確認してください。
• 1回のセッションで完了できますか？ 1セッションあたり最大約1〜5ファイルを目安に見積もってください。それ以上になる場合は、再開を前提に計画してください。
• 検証コマンドは把握していますか？ 正確なテスト／ビルド／リントのコマンドを、最初から監査プロセスファイルに記録してください。

変更の方針

• ユーザーのリスク許容度はどの程度ですか？ 提案をすべて取り入れたいユーザーもいれば、重大な修正だけを望むユーザーもいます。最初の対話形式のプロンプトを表示する前に確認してください。
• パフォーマンスの微細な最適化も含めますか？ 1.05〜1.15倍の改善は、すべてのプロジェクトでコードに手を加える価値があるとは限りません。

使い方

このスキルは、セッションをまたいで進捗を追跡する監査プロセスファイルを作成・管理します。対話形式で承認を得ながら、各ファイルに対して4つの監査スキルを体系的に実行します。

ワークフローの概要

1. 初期化 - TODO リストと監査追跡ファイルを作成します
2. 各ファイルについて - ユーザーの承認を得ながら、9ステップの監査プロセスを実行します
3. 進捗の追跡 - コンテキストの上限に備えて、各ステップの完了後に保存します
4. 完了したファイルのアーカイブ - 完了したファイルを履歴ファイルに移動します

監査のメインワークフロー

ステップ 1：監査を初期化する

既存の監査を確認する： 元のリポジトリのルートにある .agents/audit/ ディレクトリを調べ、既存の監査プロセスファイルがないか確認します。

注意： 監査追跡ファイルがコミットされないように、プロジェクトの .gitignore に .agents/audit/ が含まれていることを確認してください。

既存の監査を再開する場合は、監査プロセスファイルを読み、現在の状況を把握します。

1. 完了状況を確認する：

   • 「Current Status」セクションを確認し、完了したファイルと残りのファイルを把握します
   • 「Files to Audit」セクションを確認し、保留中と完了済みの内訳を把握します
   • すべてのファイルが「Completed」となっている場合、監査は完了しています

2. worktree の状況を確認する（後方互換性）：

   • 「Worktree Information」セクションがある場合：worktree がまだ存在することを確認して切り替えます
   • worktree の記載がない場合：これは worktree のサポート以前の従来の監査です。worktree を作成せず、現在のブランチで続行します。
   • 注：worktree を使用するのは、この機能の追加後に作成された新しい監査のみです

3. 「Resume Instructions」セクションから続行します

監査を再開する場合は、ステップ 2 に進みます。

新しい監査の場合は、分離された worktree を作成します：

必須：並行する監査との競合を防ぎ、安全にロールバックできるように、監査作業はすべて分離された worktree で行う必要があります。

1. タイムスタンプ付きブランチで worktree を作成します：

   timestamp=$(date +%Y%m%d-%H%M%S)
   git worktree add .agents/worktrees/audit-${timestamp} -b audit/${timestamp}
   

2. worktree ディレクトリに切り替えます：

   cd .agents/worktrees/audit-${timestamp}
   

3. worktree のパスを記録します - 監査全体を通じて、このディレクトリで作業します

重要： worktree は .agents/audit/ ではなく .agents/worktrees/ に作成されます。追跡ファイルが保存される、Git の追跡対象外である .agents/audit/ ディレクトリとの競合を避けるためです。

追跡ファイルを作成します：

必須 - ファイル全体を読むこと： 追跡ファイルを作成する前に、必要な正確な形式と構造を把握するため、assets/audit-process-template.md を最初から最後まで必ず読みます。 このファイルを読む際、範囲制限を設定してはいけません。

同様に、アーカイブ形式を把握するため、assets/audit-history-template.md も必ず読みます。

初期設定後は、これらのテンプレートを再度読み込まないでください。新しい監査の開始時に一度だけ必要です。

タイムスタンプ付きの追跡ファイルを元のリポジトリ（worktree ではありません）に作成します：

• 元のリポジトリのルートに戻ります：cd $(git rev-parse --show-toplevel)
• .agents/audit/audit-process-${timestamp}.md を作成します（worktree と同じタイムスタンプを使用）
• .agents/audit/audit-history-${timestamp}.md を作成します（同じタイムスタンプ）
• worktree に戻ります：cd .agents/worktrees/audit-${timestamp}

重要： 追跡ファイルは、元のリポジトリの .agents/audit/ ディレクトリ（Git の追跡対象外にしておく必要があります）に置かれるため、監査の変更とともにコミットされることはありません。

TODO リストを作成します：

対象ディレクトリ内にあるすべての TypeScript ファイルを検索します。ただし、.test.ts、.spec.ts、.bench.ts ファイルは除外します。単一のファイルが指定されている場合は、それがテストファイルまたはベンチマークファイルではないことを確認します。

監査プロセスファイルに内容を記入します：

• 「Worktree Information」セクションに worktree のパスとブランチを追加します
• 「Files to Audit」セクションにすべてのファイルを「Pending」として追加します
• 正確な検証コマンド（テスト／ビルド／lint）を記録します
• 「Current File」を最初の保留中ファイルに設定します
• ファイルを保存します

ステップ 2：各ファイルを監査する（8 ステップのプロセス）

保留中リストの各ファイルについて、次の手順を順番どおりに実行します。

フェーズ 1：初期テストカバレッジ

ステップ 1：accelint-ts-testing スキルを実行

Invoke the accelint-ts-testing skill.

[file-path]

ステップ 2：対話形式で変更

ブロッキング要件 — 対話形式での承認が必要です：

先に進む前に、次の 3 つのチェックポイントをすべて完了する必要があります：

1. ✅ すべての問題を含む、絵文字付きの重大度テーブルを表示する（「対話型変更承認パターン」を参照）
2. ✅ すべての問題について、変更前と変更後のコードを詳しく示す
3. ✅ 番号付きリストを示して「どの問題を適用しますか？」と尋ねる 例外はありません。いずれかのチェックポイントを省略すると、ワークフローに違反します。

• 承認された変更を適用する
• ブロッキング要件： プロパティベーステストを追加した場合は、次の検証を実行する：

  # Run test suite 100 times to verify PBT stability
  for i in {1..100}; do <test-command> || break; done
  

  • カバレッジの競合を防ぐため、カバレッジレポートを出力せずにテストを実行する
  • 実行が 1 回でも失敗した場合は、失敗したシードを調べる
  • テストのプロパティを修正する（任意値に制約を追加する：日付範囲、NaN の除外、安全な文字列）
  • 100 回連続で成功するまで、100 回ずつ再実行する
  • この検証に合格するまで、ステップ 3 に進まない
• 「現在のファイル — 詳細な進捗」セクションに調査結果を記録する
• ステップ 1 ✅、ステップ 2 ✅ と表示されるようにステータスを更新する
• 続行する前に、今すぐ進捗を監査プロセスファイルに保存する

フェーズ 2：コード品質とパフォーマンスの分析

ステップ 3：両方のスキルを並行して実行

重要：矛盾する提案を避けるため、これらを同時に実行してください：

Invoke the accelint-ts-best-practices skill.

[file-path]

ステップ 8：対話形式で変更

ブロッキング要件 — 対話形式での承認が必要です：

先に進む前に、次の 3 つのチェックポイントをすべて完了する必要があります：

1. ✅ すべてのドキュメントの問題を含む、絵文字付きの重大度テーブルを表示する（「対話型変更承認パターン」を参照）
2. ✅ すべての問題について、変更前と変更後のコードを詳しく示す
3. ✅ 番号付きリストを示して「どの問題を適用しますか？」と尋ねる 例外はありません。いずれかのチェックポイントを省略すると、ワークフローに違反します。

• 承認された変更を適用する
• ドキュメントに問題がないことを確認するため、最終検証を実行する（監査プロセスファイルに記載されたコマンドを正確に使用する）
• 「現在のファイル — 詳細な進捗」に記録する
• ステップ 7 ✅、ステップ 8 ✅ と表示されるようにステータスを更新する
• ステップ 3（アーカイブ）に進む前に、今すぐ進捗を監査プロセスファイルに保存する

ステップ 3：完了したファイルをアーカイブする

ファイルの 9 つのステップがすべて完了したら：

1. 詳細な進捗を履歴ファイルに移動する

   • 「現在のファイル — 詳細な進捗」セクション全体をコピーする
   • 監査履歴ファイルに追記する
   • ファイルのセクション末尾に概要統計を追加する

2. 監査プロセスファイルを更新する

   • 「監査対象ファイル」セクションで、ファイルを「完了」としてマークする
   • 「現在のファイル — 詳細な進捗」セクションをクリアする
   • 「現在のファイル」を次の未処理ファイルに設定する
   • 次のファイルに向けて「再開手順」を更新する
   • 「現在のステータス」の件数を更新する

3. 両方のファイルを保存する

ステップ 4：続行または完了

未処理のファイルが残っている場合：

• 次のファイルについてステップ 2 に戻る
• コンテキストの使用量を監視し、上限に近づいた場合は中断して進捗を保存する

すべてのファイルが完了している場合：

1. ワークツリーで最終検証を実行する：

   • テストスイート全体の最終実行と lint 検証を行う
   • マージ前にすべての変更が合格することを確認する

2. ワークツリーを元のブランチにマージする：

   # Extract timestamp from current worktree directory name
   # We're in .agents/worktrees/audit-YYYYMMDD-HHMMSS
   timestamp=$(basename $(pwd) | sed 's/audit-//')
   
   # Get the original branch from this audit's process file (in original repo)
   repo_root=$(git rev-parse --show-toplevel)
   audit_process_file="${repo_root}/.agents/audit/audit-process-${timestamp}.md"
   original_branch=$(grep "^**Original Branch:**" ${audit_process_file} | cut -d'`' -f2)
   
   # Commit all changes in worktree
   git add -A
   git commit -m "refactor: complete TypeScript audit
   
   - Improved test coverage across all files
   - Applied type safety and best practice improvements
   - Optimized performance where beneficial
   - Enhanced documentation
   
   Co-Authored-By: {current_model}"
   
   # Switch back to original branch
   cd "${repo_root}"
   git checkout ${original_branch}
   
   # Merge the audit branch
   git merge --no-ff audit/${timestamp}
   

3. ワークツリーをクリーンアップする：

   # Remove the worktree (use the timestamp extracted earlier)
   git worktree remove .agents/worktrees/audit-${timestamp}
   
   # Optionally delete the audit branch
   git branch -d audit/${timestamp}
   

4. 完了を監査プロセスファイルに記録する：

   • 合計統計を含む完了概要を追加する
   • マージコミットのハッシュを記録する
   • 監査を「✅ 完了 — ${original_branch} にマージ済み」とマークする

5. 結果を報告する：

   • 全ファイルの合計統計
   • マージコミットの情報
   • ワークツリーのクリーンアップ完了の確認

進捗トラッキング形式

ファイルステータスマーカー：

• [ ] - 保留中（未着手）
• [x] - 完了（9 ステップすべて完了し、履歴に移動済み）

ステータスマーカー：

• ✅ - 完了
• 🔄 - 進行中
• ⏸️ - 保留中（未着手）

詳細な進捗テンプレート：

### filename.ts - Audit Status 🔄 IN PROGRESS

**Overall Progress:** X% complete (Step Y of 8)

#### ✅ Step 1: Test Coverage - COMPLETE
[Findings, changes applied, test results]

#### 🔄 Step 2: Interactive Changes - IN PROGRESS
[Current change being reviewed, user decision needed]

#### ⏸️ Step 3: Code Quality Analysis - PENDING
[Not started yet]

対話型変更承認パターン

重要： 常に 2 段階の提示パターンを使用してください。問題を 1 つずつ提示したり、すべての変更を示す前に承認を求めたりしてはいけません。

フェーズ 1：概要表（クイック確認）

すべての問題を、重要度を示す絵文字付きの番号付き表で提示します。

## Found Issues Summary (X total)

| # | Severity | Type | Lines | Description |
|---|----------|------|-------|-------------|
| 1 | 🛑 Critical | Type Safety | 45-47 | Missing null check on user object |
| 2 | ⚠️ High | Performance | 89 | N+1 query in loop - use batch fetch |
| 3 | ⚡ Medium | Performance | 120-125 | Filter+map → single pass with reduce |
| 4 | 🔵 Low | Best Practice | 78 | Use const assertion for readonly array |
| 5 | ✅ Info | Documentation | 12 | Missing JSDoc return type |

重要度の凡例：

• 🛑 重大 - 実行時エラー、セキュリティ上の脆弱性、またはデータ損失を引き起こします
• ⚠️ 高 - 型エラー、重大なパフォーマンスの問題、または API の互換性を損なう変更です
• ⚡ 中 - 中程度のパフォーマンス向上、保守性の改善です
• 🔵 低 - 軽微な最適化、スタイルの改善です
• ✅ 情報 - ドキュメント、コメント、機能に影響しない改善です

フェーズ 2：詳細な変更（全コンテキスト）

概要表の後に、各問題の変更前と変更後のコードをすべて表示します。

---

### Issue #1: Missing null check (🛑 Critical - Type Safety)
**Lines:** 45-47
**Problem:** Function doesn't handle null user case
**Impact:** Runtime TypeError when user is null

❌ **Before:**
```typescript
function getUsername(user: User | null) {
  return user.name; // TS error + runtime crash
}

✅ 変更後：

function getUsername(user: User | null) {
  return user?.name ?? 'Anonymous';
}

期待される効果： 実行時の TypeError を防ぎ、TS のコンパイルエラーを修正します

---

問題 #2：N+1 クエリのパフォーマンス（⚠️ 高 - パフォーマンス）

[... 各問題について同じ詳細形式を使用 ...]

---

問題 #3：filter+map の最適化（⚡ 中 - パフォーマンス）

[... 各問題について同じ詳細形式を使用 ...]

---

[すべての問題について続けてください...]

---

どの問題を適用しますか？ 番号を入力してください（例：「1, 2, 5」、「all」、または「skip」）：

**Key Benefits:**
- Overview table allows quick scanning for conflicts across parallel processes
- Numbered list makes acceptance explicit and trackable
- All code changes shown upfront before any approval
- Emoji severity indicators enable instant visual prioritization
- Consistent format prevents wildly varying presentations

Wait for user response with numbered list before applying any changes.

## Verification Commands

The audit-process file MUST document exact verification commands. Common patterns:

**Node.js projects:**
```bash
cd <project-root>; npm test
cd <project-root>; npm run build
cd <project-root>; npm run lint

Bun プロジェクト：

cd <project-root>; bun run test
cd <project-root>; bun run build
cd <project-root>; bun run lint
cd <project-root>; bun run bench  # if applicable

モノレポのパッケージ：

cd <workspace-root>/packages/<package-name>; npm test

監査プロセスファイルに記載されたコマンドを必ずそのまま使用してください。推測してはいけません。

重要な注意事項

• README.md を読み込まないでください - ユーザー向けドキュメントが含まれており、このファイルの内容と重複します。エージェントへの指示はすべて SKILL.md に記載されています。
• ワークツリーの場所： 監査作業はすべて .agents/worktrees/audit-${timestamp} で行い、Git で無視される .agents/audit/ ディレクトリとの競合を避けます。
• 追跡ファイルの場所： 監査プロセスと履歴のファイルは、元のリポジトリの .agents/audit/ ディレクトリ（Git で無視されます）に保存され、監査による変更と一緒にコミットされることはありません。
• プロパティベーステストの安定性： プロパティベーステストがランダムに失敗する場合は、失敗した正確なシードを確認し、そのシードで修正を検証してください。アービトラリーに制約（日時の範囲、NaN の除外、安全な文字列など）を追加し、誤検知を防いでください。
• スキルの並列実行： ts-best-practices と ts-performance を並列実行する場合は、推奨事項を提示する前に両方の完了を待ってください。これにより、重複する提案を特定して統合できます。
• コンテキストウィンドウの管理： 監査プロセスのファイルは、コンテキスト制限を超えても作業を継続できるように設計されています。各ステップの完了後に進捗を保存してください。ファイルの途中で作業を中断する必要がある場合は、現在のステップと次に行うべき操作を正確に記録してください。
• ビルドの失敗は作業を止めます： 検証コマンドが失敗した場合は、次のステップに進まないでください。まず問題を修正するか、変更をロールバックしてください。
• PERF コメントのガイドライン： 最適化が自明でない場合にのみ、パフォーマンスに関するコメントを追加してください。「map の代わりに for...of を使用する」にはコメントは不要です。「JSON の繰り返しパースを避けるためにデシリアライザーをメモ化する」にはコメントが必要です。
• 履歴ファイルは書き込み専用です： 過去の判断を理解したり、変更のロールバックを検討したりする必要がある場合にのみ、audit-history ファイルを読んでください。それ以外の場合は、アーカイブとしてのみ扱ってください。