spec-mining

仕様のマイニング

実際に実行されるコードを読み、利用可能なドキュメントがないシステムから仕様を抽出します。

出力の信頼性を高めるための原則は、観察したことと推測したことを分けることです。読者はこのドキュメントをもとに、サービスの再構築や移行計画の策定、オンボーディングを行います。自信に満ちた推測は、未確認であると明記された不明点よりも危険です。誰も確認に戻らなくなるからです。

アプローチ

外側から内側へ進めます。エントリーポイント、ルート、背後にあるサービス、そしてデータレイヤーの順です。実際のリクエスト経路をたどることで、システムの実際の構造がわかります。これは、ディレクトリ名が示す構造とは異なることがよくあります。

テストも読みましょう。テストには意図された動作や、本番環境で誰かが遭遇したエッジケースが記録されています。通常、リポジトリ内のコメントや README よりも、テストのほうが率直です。

マイグレーションの履歴も読みましょう。マイグレーションには日付と順序があるため、スキーマがどのように現在の形になったかがわかります。どのカラムが切迫した状況で追加されたか、何がバックフィルされたか、何が名称変更されたものの削除されずに残っているかを確認できます。この経緯は、データモデルが現在の形になった理由を伝える、唯一残された記録であることも少なくありません。

すべての観察事項には、その根拠となる箇所を記載します — src/auth/jwt.strategy.ts:42。場所が示されていなければ、読者は主張を検証できません。検証できない主張こそ、リバースエンジニアリングで作成された仕様を劣化させる原因です。

観察した要件を書く — EARS

EARS は、トリガーと状態を文に含めることで、要件を明確にします。そのため、「システムはトークンを検証する」という文で、 いつ 検証するのかが曖昧になることはありません。

パターン	形式
ユビキタス	システムは［アクション］を実行するものとします。
イベント	［トリガー］が発生したとき、システムは［アクション］を実行するものとします。
状態	［状態］の間、システムは［アクション］を実行するものとします。
条件付き	［状態］の間に［トリガー］が発生したとき、［アクション］を実行するものとします。
オプション	［機能が有効な場合］、［アクション］を実行するものとします。

後から参照できるように、領域ごとに番号を付けます — OBS-AUTH-001、OBS-USER-002：

OBS-AUTH-001
While credentials are valid, when POST /auth/login is called, the system
shall return a JWT access token (15m) and a refresh token (7d).
Evidence: src/auth/auth.controller.ts:31, src/auth/auth.service.ts:88

不明点も成果物の一部です

コードから判断できなかったことは、推測ではなく質問として独立したセクションに記載します。たとえば、ステータス遷移のトリガー、削除が論理削除かどうか、フィールドの所有元となる外部システムなどです。このセクションは、ドキュメントの中で最も価値のある部分になることがよくあります。ほかの内容を誰かが信頼する前に、保守担当者に確認しなければならない事項の一覧だからです。

出力

specs/{project_name}_reverse_spec.md に保存します。構成とセクションの順序は、references/specification-template.md に従います。