CAPHTECH Spec-Gen: コードからSpec生成
核心原理
コードから生成できるのはAs-Is spec（現状仕様）のみ
- As-Is: 今このコードが"そう振る舞う"こと
- To-Be: 本来"そうあるべき"こと ← コードには書かれていない
To-Beを推測すると「整った嘘」になる。As-Isとして厳密に抽出し、不明は不明として残す。
3層構造
| 層 | 生成難易度 | 出力形式 | 説明 |
|---|---|---|---|
| A: インターフェース | 高精度 | YAML | 型/スキーマ/パス/ステータス |
| B: 振る舞い | 中精度 | YAML | 前提/事後/副作用/状態遷移 |
| C: 業務意味 | 低精度 | Markdown | 意図/理由/トレードオフ（草案止まり） |
詳細: references/spec-layers.md
確度ラベル
すべての断定に確度を付与:
| ラベル | 定義 | 扱い |
|---|---|---|
| Verified | テスト/実行で確認済み | 信頼可 |
| Observed | コードで確認（テスト未確認） | 要検証 |
| Assumed | 一般的推測 | 要確認 |
| Unknown | 判断不能 | 明示的に残す |
詳細: references/confidence-labels.md
実行手順
Step 1: 公開面（Surface）の特定
対象コードのエントリポイントを特定:
- HTTP: ハンドラ/ルーティング
- CLI: コマンド/サブコマンド
- Event: 購読/パブリッシュ
- Job: スケジューラ起点
- Library: public/export
Step 2: 層Aの抽出（インターフェースspec）
抽出対象:
- リクエスト/レスポンス型
- パス、メソッド、ステータスコード
- 必須/任意、デフォルト、列挙値
- エラーコード一覧
出力形式: YAML（OpenAPI互換推奨）
# 層A: インターフェースspec
endpoint:
path: /api/users/{id}
method: GET
confidence: Observed
evidence: src/api/users.ts:45
request:
params:
id:
type: string
required: true
confidence: Verified
evidence: tests/api/users.test.ts:23
response:
success:
status: 200
schema:
id: string
name: string
email: string
confidence: Observed
evidence: src/api/users.ts:52
errors:
- status: 404
code: USER_NOT_FOUND
confidence: Observed
evidence: src/api/users.ts:48
Step 3: 層Bの抽出（振る舞いspec）
抽出対象:
- 前提条件（preconditions）
- 事後条件（postconditions）
- 禁止条件
- 副作用（DB書込み、外部API、イベント発行）
- 状態遷移
出力形式: YAML
# 層B: 振る舞いspec
behavior:
preconditions:
- condition: "ユーザーIDが存在する"
confidence: Observed
evidence: src/services/user.ts:34
postconditions:
- condition: "ユーザー情報が返却される"
confidence: Verified
evidence: tests/services/user.test.ts:45
side_effects:
- type: db_read
target: users table
confidence: Observed
evidence: src/repositories/user.ts:23
state_transitions:
- from: null
to: null
note: "読み取り専用、状態変更なし"
confidence: Observed
evidence: src/api/users.ts:45-55
invariants:
- statement: "同一IDで常に同一ユーザーが返る"
confidence: Assumed
evidence: null
Step 4: 層Cの生成（業務意味spec）
注意: この層はコードから断定困難。草案として生成し、人間レビュー必須。
出力形式: Markdown
# 業務意味spec（草案）
## 概要
[Assumed] ユーザー情報取得API
## 目的
[Unknown] 具体的なビジネス目的は不明
## 使用コンテキスト
[Assumed] ユーザープロフィール表示に使用される可能性
## 設計判断
[Unknown] なぜこの実装になったかは不明
---
**レビュー依頼**: この層の内容は人間による確認が必要
Step 5: 根拠リンクの検証
すべてのevidenceを検証:
[ ] ファイルパスが存在する
[ ] 行番号が有効範囲内
[ ] シンボル名が一致する
[ ] confidence: Verified には対応テストがある
差分検出
手動比較ガイド
既存specとコードを比較:
- spec内のevidenceリンクを抽出
- 各リンク先が変更されていないか確認
- 変更があれば該当specを「要更新」としてマーク
git連携
# 変更ファイルからspec影響を検出
git diff --name-only HEAD~1 | xargs -I {} grep -l "{}" specs/*.yaml
# 特定コミット範囲のspec影響
git diff --name-only <from>..<to> | while read file; do
grep -r "evidence:.*$file" specs/
done
詳細: references/diff-detection.md
出力テンプレート
詳細: references/output-templates.md
品質チェックリスト
### 層A（インターフェース）
- [ ] すべてのエンドポイントを網羅したか
- [ ] 型情報に根拠リンクがあるか
- [ ] エラーコードを列挙したか
### 層B（振る舞い）
- [ ] 副作用を列挙したか
- [ ] 前提条件/事後条件を記述したか
- [ ] 状態遷移を図示したか（該当する場合）
### 層C（業務意味）
- [ ] 草案として明示したか
- [ ] Unknown/Assumedを正直に付けたか
- [ ] レビュー依頼を記載したか
### 全体
- [ ] As-IsとTo-Beを混同していないか
- [ ] 根拠のない断定がないか
- [ ] 確度ラベルが適切か
連携スキル
- eld-model: 層Bで発見した不変条件をLaw Cardへ昇格
- spec-observation: specから受入テストを生成
- doc-gen: 層A/Bを開発者ドキュメントに統合