reverse-engineering-specs

リバースエンジニアリング仕様書

概要

ドキュメントがない既存のプロジェクトやレガシープロジェクト向けに、このスキルは既存のコードを徹底的に分析し、実装に依存しない仕様書を生成します。出力されるのは、既存のコードベース上で自律的な開発を進めるための、完全な動作説明です。これにより、安全なリファクタリング、機能追加、モダナイゼーションを実現できます。

基本原則： バグも含め、実際の動作を記録します。明示的に修正対象とされるまでは、バグも「文書化された機能」です。

これは厳格なスキルです。 すべてのコードパスを追跡してください。推測も省略も禁止です。

フェーズ 1：徹底的なコード調査

［厳格なゲート］ すべてのコードパスを追跡してください。推測も省略も禁止です。

Agent ツールを使って並列サブエージェント（最大 500、subagent_type="Explore"）を起動し、次の項目を分析します。

分析対象	記録する内容	優先度
エントリーポイント	システムを起動するすべての方法（HTTP、CLI、イベント、cron）	P0
コードパス	すべての分岐、ループ、条件判定、早期リターン	P0
データフロー	各パイプラインの入力 → 変換 → 出力	P0
状態の変更	状態が読み取り、書き込み、削除されるすべての箇所	P0
エラー処理	try/catch ブロック、エラーコード、フォールバック動作	P0
副作用	外部呼び出し、ファイル I/O、データベースへの書き込み、イベントの発行	P1
設定	環境変数、設定ファイル、機能フラグ	P1
依存関係	利用する外部サービス、ライブラリ、API	P1
並行処理	非同期操作、競合状態、ロック機構	P2
暗黙の動作	規約に基づくルーティング、ミドルウェアチェーン、デコレーター	P2

調査戦略の判断表

コードベースの規模	戦略	サブエージェント数
小規模（50 ファイル未満）	一度に全体をスキャン	5-10
中規模（50-500 ファイル）	モジュールごとにスキャン	50-100
大規模（500 ファイル以上）	エントリーポイントを優先し、その後に深掘りスキャン	200-500

調査が終わったら停止し、発見したエントリーポイント、データフロー、動作の概要を提示します。仕様書の生成を始める前に、確認を得てください。

フェーズ 2：動作仕様書の生成

コード分析の結果を、spec-writing スキルの形式に従った実装に依存しない仕様書に変換します。

変換ルール

ルール	説明
実装の詳細をすべて取り除く	関数名、変数名、技術への言及を含めません
「何をするか」を記述し、「どうするか」は記述しない	観察可能な動作のみを記述します
実際の動作を記録する（バグを含む）	バグは仕様書で「現在の動作」として扱います
Given/When/Then 形式を使う	すべての受け入れ基準に適用します
データコントラクトを含める	入力の形式、出力の形式、不変条件を記載します
既知の問題を分離する	バグはインラインではなく、KNOWN_ISSUES.md に記載します

実装の詳細の除去

コードの要素	目にするもの	仕様書に記述する内容
jwt.verify(token, secret)	JWT によるトークン検証	「認証システムに照らして認証情報を検証します」
redis.get(cacheKey)	Redis キャッシュの参照	「以前に計算された結果をキャッシュから取得します」
if (user.role === 'admin')	ロールの確認	「特権操作には管理者アクセスが必要です」
res.status(429).json(...)	レート制限の応答	「過剰なリクエストにはレート制限エラーを返します」
bcrypt.hash(pw, 12)	パスワードのハッシュ化	「パスワードは元に戻せない形式で保存されます」

仕様書の生成後は停止し、整理を始める前に完全性チェックリストを実行します。

フェーズ 3：仕様書の整理

次の命名規則に従って仕様書ファイルを作成します。

specs/
├── 01-[first-capability].md
├── 02-[second-capability].md
├── ...
├── NN-[last-capability].md
└── KNOWN_ISSUES.md

KNOWN_ISSUES.md の形式

# Known Issues

## [Issue Title]
- **Current behavior:** [What actually happens]
- **Expected behavior:** [What should happen, if known]
- **Affected specs:** [Which spec files reference this behavior]
- **Severity:** [Critical | High | Medium | Low]
- **Notes:** [Additional context]

重大度の分類

重大度	基準	対応
Critical	データ損失、セキュリティの脆弱性、システムクラッシュ	新機能の追加前に修正
High	結果が正しくない、ワークフローが壊れている	次のリリースで修正
Medium	UX が悪い、パフォーマンスの問題	今後の修正として計画
Low	見た目の問題、軽微な不整合	機会があれば修正

組織化の後は停止し、レビュー用に仕様ファイルの一覧と KNOWN_ISSUES を提示してください。

フェーズ 4：品質検証

[HARD-GATE] このフェーズを完了する前に、すべてのチェックに合格する必要があります。

#	チェック	質問	状態
1	エントリーポイント	すべてのエントリーポイントが文書化されていますか？	[ ]
2	コードパス	すべての分岐と条件を追跡していますか？	[ ]
3	データフロー	すべての入力→出力パイプラインを記述していますか？	[ ]
4	状態の変更	すべての状態変更を記録していますか？	[ ]
5	エラー処理	すべてのエラーパスを文書化していますか？	[ ]
6	副作用	すべての外部とのやり取りを記録していますか？	[ ]
7	エッジケース	境界条件を記述していますか？	[ ]
8	並行処理	非同期の動作を文書化していますか？	[ ]
9	設定	すべての設定オプションを列挙していますか？	[ ]
10	依存関係	すべての外部依存関係を特定していますか？	[ ]
11	実装に依存しないこと	仕様にコード、技術名、アーキテクチャが一切含まれていませんか？	[ ]
12	Given/When/Then	すべての受け入れ基準が正しい形式ですか？	[ ]

具体例：コードから仕様への変換

コード（入力 — 分析するもの）：

function checkAuth(req, res, next) {
  const token = req.headers.authorization?.split(' ')[1];
  if (!token) return res.status(401).json({ error: 'No token' });
  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.user = decoded;
    next();
  } catch (e) {
    return res.status(403).json({ error: 'Invalid token' });
  }
}

仕様（出力 — 作成するもの）：

# Request Authentication

## Job to Be Done
When a request arrives at a protected endpoint, I want to verify the
caller's identity, so I can ensure only authorized users access the system.

## Acceptance Criteria

### Valid Credentials
- Given a request with valid credentials in the authorization header
- When the request is processed
- Then the request proceeds to the next handler
- And the authenticated user identity is available to downstream handlers

### Missing Credentials
- Given a request without credentials
- When the request is processed
- Then a 401 status is returned
- And an error message indicates missing credentials

### Invalid Credentials
- Given a request with invalid or expired credentials
- When the request is processed
- Then a 403 status is returned
- And an error message indicates invalid credentials

## Edge Cases
- Malformed authorization header (missing "Bearer" prefix): treated as missing credentials
- Expired credentials: treated as invalid credentials

## Data Contracts
- Input: Authorization header in "Bearer <credential>" format
- Output on success: User identity object attached to request context
- Output on failure: JSON error response with appropriate status code

注：JWT、ミドルウェア、Express、環境変数などの実装詳細には触れていません。

アンチパターン／よくある間違い

間違い	問題となる理由	代わりにすべきこと
「つまらない」コードパスを省略する	動作が文書化されていないと、リファクタリング中にバグが発生します	エラーハンドラーも含め、すべてのパスを追跡する
仕様に実装詳細を漏らす	動作仕様の目的が損なわれます	技術名、関数名、コードをすべて取り除く
バグを「正しい動作」として扱う	バグであるという情報が失われます	重大度とともに KNOWN_ISSUES.md に記録する
非同期処理／並行処理の分析を省略する	競合状態は最も発見が難しいバグです	すべての非同期動作を文書化する
正常系のパスだけを分析する	バグの多くはエラーパスに潜んでいます	すべてのエラー処理パスを文書化する
コードを追跡せず、動作を推測する	仕様がフィクションになります	仮定せず、すべての行を読む
ユーザーレビューなしで仕様を生成する	誤解が引き継がれていきます	各フェーズの後にレビュー用として提示する

正当化を防ぐためのガード

• [HARD-GATE] コードパスを省略しないでください。すべての分岐、条件、エラーハンドラーを追跡する必要があります
• [HARD-GATE] 仕様に実装詳細を一切含めないでください。コード、技術名、アーキテクチャは含めないでください
• [HARD-GATE] 12項目すべてに合格するまで、完全性チェックリストを完了としてマークしないでください
• 並行処理の分析を省略しないでください。コードが「同期的に見える」場合も同様です
• 設定の分析を省略しないでください。環境変数や機能フラグによって動作が変わります
• 関数名から動作を推測しないでください。実際のコードを読んでください
• リバースエンジニアリング中にバグを修正しないでください。KNOWN_ISSUES.md に記録してください

統合ポイント

スキル	関係
spec-writing	出力は spec-writing の形式に従います。生成後の監査に使用してください
autonomous-loop	仕様を計画モードに渡し、ギャップ分析に使用します
acceptance-testing	リバースエンジニアリングした受け入れ基準からテストを作成します
self-learning	発見したプロジェクトのコンテキストをメモリファイルに追加します
planning	仕様ができたら、改善や新機能を計画します
systematic-debugging	既知の問題をデバッグの優先順位付けに活用します

リバースエンジニアリング後のワークフロー

ステップ	スキル	目的
1	reverse-engineering-specs（このスキル）	コードから動作仕様を生成する
2	spec-writing（監査モード）	品質と完全性を確認する
3	planning	不足点を特定し、改善を計画する
4	autonomous-loop	仕様を指針として、機能や修正を実装する

検証ゲート

リバースエンジニアリングが完了したと申告する前に、次の項目を確認してください。

1. 完全性チェックリスト（全12項目）に合格していることを確認する
2. 仕様ファイルに実装の詳細が一切含まれていないことを確認する
3. すべての受け入れ基準が Given／When／Then 形式であることを確認する
4. KNOWN_ISSUES.md が存在し、発見されたすべてのバグを分類していることを確認する
5. ユーザーが仕様一式と KNOWN_ISSUES を確認済みであることを確認する

スキルの種類

柔軟 — 網羅的な調査と実装を含めない出力というルールを守りながら、コードベースの規模に応じて調査の深さとサブエージェントの数を調整してください。コードパスを省略してはなりません。