Spec Value Finder

spec-value-finder

人が用意した元仕様書（Excel / Word / PowerPoint / PDF / Markdown / txt）から「記入すべき値」を探し、出典・確信度・要確認フラグ付きで記入シートに落とし込むスキル。

設計思想: Neo4j も Table Transformer も使わない。依存は pip 一発で入る純Python系ライブラリ（openpyxl / python-docx / python-pptx / pypdfium2 / PyYAML、数MB）だけで、サーバ起動も GPU も不要。どの環境でも init 一発で動く可搬性を最優先する。

役割分担

GraphRAG の自動マッチングは、人が渡すマッピング情報（keywords による表記揺れの明示）と Claude の意味判定に置き換えている。

モード一覧

scripts/
├── run.py        # エントリポイント（__file__ 基準でパス解決）
├── models.py     # データ構造（Cell.path = breadcrumb）
├── extract.py    # Excel/Word/PowerPoint/PDF/Markdown/txt → 構造化抽出
├── mapping.py    # マッピングファイルのスキーマ・検証・ドラフト
├── finder.py     # キーワード前段フィルタ → 候補抽出
├── filler.py     # テンプレート + findings → 新規ファイル生成
├── comparer.py   # 手動転記結果 × findings の突き合わせ判定
└── requirements.txt

run.py は __file__ 基準でパスを解決するため、スキルがどこに配置されていても動く。 コマンド例は python を使用する（環境により python3）。

標準ワークフロー

[init] ─→ [map-draft] ─→ 人がマッピング承認 ─→ [validate]
                                                    │
                              [extract] ←───────────┤
                                                    ▼
                                  [find] ─→ Claude が候補を吟味
                                                    │
                                            findings.json 作成
                                                    ▼
                          ┌─────────────────────────┴───────────────────┐
                          ▼ 生成したいとき                 検証したいとき ▼
              [fill] ─→ 人が成果物を検証      [compare] ─→ Claude が判定を吟味 ─→ 人が確認

fill は記入シートを新規生成する。compare は人が既に手で転記した記入シートを findings.json と突き合わせて転記の正しさを判定する。用途に応じてどちらか（または両方）を使う。

Step 0 — init（初回のみ）

python scripts/run.py init

Step 1 — マッピング情報を用意する

マッピングファイル（mapping.yaml）は「記入先の項目」と「元仕様書での探し方」を結びつける辞書。keywords が表記揺れ対策の要になる。

version: 1
source:
  folder: ./specs          # 元仕様書フォルダ（再帰走査）
  name_match: "HW仕様"      # ファイル名の部分一致パターン（空=全件）
items:
  - target: "MTU上限"                # 必須: 記入先の項目名
    keywords: ["MTU", "Maximum Transmission Unit", "最大転送単位"]  # 必須: 表記揺れを列挙
    section_hint: "ネットワーク"      # 任意: 章/シートのヒント（探索精度が上がる）
    unit: "bytes"                     # 任意: 期待単位
    type: number                      # 任意: number|text|enum|date
    note: "レイヤ2 のフレーム長"       # 任意: 補足

別ファイル（Excel等）に自然文で対応記述がある場合は map-draft でドラフトを起こす:

python scripts/run.py map-draft ./対応表.xlsx --out mapping.yaml

map-draft はスカフォールドと「元記述」を出力する。Claude は元記述を読んで items を埋め、人がレビューする。確定後に検証する:

python scripts/run.py validate mapping.yaml

Step 2 — 元仕様書を確認する（任意）

全文を読みたいときは extract で Markdown 化する。

python scripts/run.py extract ./specs --name-match HW仕様 --out ./.svf-cache

--out を付けると各ファイルの .md / .json を出力。省略時は単一ファイルなら標準出力に Markdown を表示する。

Step 3 — find（候補を抽出する）

python scripts/run.py find --mapping mapping.yaml --out candidates.json

各項目について、keywords に一致したセル/段落を 値・出典・breadcrumb・行文脈 付きで列挙する。source はマッピングから読むが --folder / --name-match で上書きできる。

Step 4 — Claude が候補を吟味して findings.json を作る（中核）

ここがスキルの中核。find の出力 candidates.json を Claude が読み、項目ごとに値を確定する。 candidates[0] を機械的に採用してはならない。

各候補について次を踏まえて判断する:

• path（breadcrumb）と section_hint が意味的に整合しているか
• セル一致のとき、欲しい値は一致セルそのものか、row_values の隣接セルか
• unit / type がマッピングの期待と一致しているか
• matched_keywords / score はあくまでヒント。最終判断は意味で行う

確信度の基準:

findings.json の形式:

{
  "items": [
    {
      "target": "MTU上限",
      "value": "1500",
      "source": "HW仕様書_v2.xlsx :: シート'Network' :: C2",
      "confidence": "high",
      "needs_review": false,
      "comment": ""
    }
  ]
}

confidence が high 以外、または単位・型の不一致がある項目は needs_review: true にする。候補が見つからない項目も value: "" / needs_review: true で必ず含める（人が気づけるように）。

Step 5 — fill（新規ファイルを生成する）

記入シート例（テンプレート）を複製し、確定値を埋めた新規ファイルを出力する。

python scripts/run.py fill --template 記入例.xlsx --findings findings.json --out 結果.xlsx

Excel テンプレート: 「項目」列の項目名と target を突合して各行に記入する。期待する見出し: 項目 / 値 / 出典 / 確信度 / 要確認（見出し名は --col-item などで変更可）。テンプレートに無い項目は末尾に追記される。

Word テンプレート: 本文・表中の {{項目名}} プレースホルダを値で置換する。

生成後、人が 出典 と 要確認 列を見て検証する。

Step 6 — compare（手動転記の正しさを判定する）

fill の代わりに、人が既に手で転記済みの記入シートを findings.json と突き合わせて検証する。

python scripts/run.py compare --manual 手動転記.xlsx --findings findings.json \
  --mapping mapping.yaml --out comparison.json

--manual には項目→値の表を含むファイルを渡す（Excel/Word/PowerPoint/Markdown の表に対応。項目 / 値 列の見出しは --col-item / --col-value で変更可）。--mapping は任意で、項目の並び順の参照に使う。

スクリプトは機械的判定（数値・正規化文字列の一致）まで行い、項目ごとに verdict を出す:

compare のあと、Claude は needs_review: true の項目を吟味する:

• mismatch — 単なる誤りか、セマンティック等価（例: 手動「有効」/ スキル「Enabled」）かを判定する
• missing_skill — マッピングの keywords が不足していないか、手動値の出典が妥当かを確認する
• missing_manual — 転記漏れか、対象外の項目かを判定する

そのうえで「転記が正しい項目／要修正の項目／人の最終裁定が必要な項目」に整理して人へ提示する。数値・単位の最終確認や専門的判断は人が行う。

マッピングファイル スキーマ

対応フォーマット（元仕様書）

• PDF はテキスト層からの抽出のみ。スキャン画像だけで本文テキスト層を持たない PDF は抽出が空になる（OCR は行わない）。
• 旧形式（.xls / .doc / .ppt）は非対応。新形式に変換して使う。
• 記入シート例（fill のテンプレート）は Excel / Word に対応する。

エラー対処