specs-code-cleanup

コードのクリーンアップ

概要

レビュー後にコードを見た目の面で整え、本番環境で使える状態にします。このワークフローは、現在 /developer-kit-specs:specs.task-implementation のフェーズ T-7 として統合されています。--action=cleanup を使って手動で実行することもできます。

入力：docs/specs/[id]/tasks/TASK-XXX.md（レビュー済みのステータス）
出力：クリーンアップ済みのコード、タスクのステータスを completed に更新

使用するタイミング

• レビュー承認後に、コードのクリーンアップ、磨き上げ、仕上げ、整理、または技術的負債の解消を依頼された場合に使用します。
• タスクを完了できる状態にするため、デバッグログや不要なコードを削除し、インポートを最適化して、可読性を高める場合に使用します。
• 仕様駆動開発のワークフローにおける、最終品質ゲートとして使用します。
• ロジックのリファクタリングやバグ修正には使用しません。見た目とコードの健全性の改善のみに焦点を当てます。

引数

引数	必須	説明
--lang	いいえ	java、spring、typescript、nestjs、react、python、general
--task	はい	タスクファイルへのパス
--action	いいえ	手動で実行する場合は cleanup を指定します

ベストプラクティス

• 変更ではなくクリーンアップ：削除または整理のみを行い、機能は決して変更しないでください。
• 動作を維持：クリーンアップ後もコードがまったく同じように動作する必要があります。
• プロジェクトのツールを使用：./mvnw spotless:apply、npm run lint:fix、black などを優先してください。
• TodoWrite を使用：8 つすべてのフェーズの進捗を記録してください。
• 失敗したら停止：テストが失敗した場合は停止して報告し、先に進まないでください。

言語固有のフォーマッターコマンド、インポート順序、grep パターンについては references/language-patterns.md を参照してください。

手順

フェーズ 1：タスクの確認

1. $ARGUMENTS を解析して、パラメーターを確認します。

   • --lang（任意）：対象の言語またはフレームワーク
   • --task（必須）：タスク ID またはファイルパス
   • --spec（任意）：仕様フォルダーのパス（タスク ID と併用）

   次の 2 つの形式に対応します：

   • 形式 1（直接パス）：--task=docs/specs/001-feature/tasks/TASK-001.md
   • 形式 2（仕様＋タスク）：--spec=docs/specs/001-feature --task=TASK-001

   形式 2 を使用する場合、タスクファイルのパスを {spec}/tasks/{task}.md として構成します。

2. タスクファイルを読み込み、次の点を確認します。

   • ステータスが reviewed または implemented であること（completed ではないこと）
   • レビューレポート TASK-XXX--review.md が存在し、承認済みであること

3. レビュー済みでない場合は停止し、先に /developer-kit-specs:specs.task-review を実行するようユーザーに伝えます。

4. タスク ID、タイトル、provides ファイルを抽出します。

フェーズ 2：クリーンアップ対象ファイルの特定

1. TASK-XXX--review.md を読み込み、作成または変更されたファイルを確認します。
2. タスクの provides フィールドからファイルパスを読み取ります。
3. ファイルの存在を確認し、クリーンアップ対象のリストを作成します。
4. ソースファイル、テストファイル、設定ファイルに分類します。

フェーズ 3：技術的負債の解消

Grep を使用して、ファイル内の一時的なコードやデバッグ用の記述を検索します。

• console.log、System.out.println、print(、// DEBUG:、// temp、// hack
• 解決済みの TODO／FIXME コメント（未解決のものは残します）

各検出箇所のコンテキストを確認します。負債であることが確認できたものを削除し、削除内容を記録します。

フェーズ 4：インポートの最適化

1. 利用可能な場合は、言語固有のインポート最適化ツールを実行します（参考資料を参照）。
2. ツールがない場合は、未使用のインポートを手動で削除します。
3. 変更したファイルを記録します。

フェーズ 5：コードの可読性向上

1. 利用可能な場合は、言語固有のフォーマッターを実行します（参考資料を参照）。
2. フォーマッターがない場合は、インデントを整え、長い行（>120）を分割し、スペースを調整します。
3. 明らかに安全な場合に限り、不要なコードを削除します。
4. 変更内容を記録します。

フェーズ 6：ドキュメントの確認

1. クラスやファイルのヘッダー、および公開 API のドキュメントを確認します。
2. 残っている TODO が引き続き妥当で、コンテキストを伴っていることを確認します。
3. 古くなったコメントを削除または更新します。
4. ドキュメントの変更内容を記録します。

フェーズ 7：最終確認

1. 利用可能な場合はリンターを実行します。
2. 利用可能な場合はテストを実行します。
3. ロジックやシグネチャに変更が加えられていないことを確認します。
4. テストが失敗した場合は停止し、失敗内容を報告します。

フェーズ 8：タスクの完了

1. タスクのステータスを自動更新する：

   • タスクファイルに ## Cleanup Summary セクションを追加します
   • DoD セクションの未チェックの項目にチェックを付けます
   • フックによってステータスが自動的に completed に更新され、completed_date と cleanup_date が設定されます

2. タスクファイルに ## Cleanup Summary を追加し、以下を記載します：

   • クリーンアップしたファイル
   • 実施した変更
   • 検証チェックリスト（リンター、テスト、機能変更がないこと）

3. すべての ToDo を完了にします

例

Spring Boot のクリーンアップ

/developer-kit-specs:specs.task-implementation --lang=spring --task="docs/specs/001-user-auth/tasks/TASK-001.md" --action=cleanup

作業：

1. TASK-001 のステータスが reviewed であることを確認します
2. ファイル：UserController.java、UserService.java、UserRepository.java
3. System.out.println を 5 件、解決済みの TODO を 2 件削除します
4. ./mvnw spotless:apply を実行します
5. ./mvnw test -q を実行します
6. タスクを completed にします

TypeScript のクリーンアップ

/developer-kit-specs:specs.task-implementation --lang=typescript --task="docs/specs/002-dashboard/tasks/TASK-003.md" --action=cleanup

作業：

1. TASK-003 のステータスが reviewed であることを確認します
2. ファイル：Dashboard.tsx、useDashboard.ts、Dashboard.test.tsx
3. console.log ステートメントを 8 件削除します
4. npm run lint:fix と npm run format を実行します
5. npm test を実行します
6. タスクを completed にします

制約と警告

• クリーンアップ中にロジックやシグネチャを変更しないでください
• テストに失敗した場合は、直ちに作業を中止して報告してください
• 完了にする前に、動作に変更がないことを確認してください