設計書をAgentに渡し、変更を自然文で伝える。影響判断はEvidenceで検証する。
設計書をLLMとGraphRAGで構造化し、自然文の変更要求から 影響候補・依存経路・該当セル・必要作業を提示するローカルファーストOSSです。
5分で試す · Cursor · Antigravity · マニュアル
Important
v1.3.0はAlphaです。出力は影響の確定結果ではなく、人間が確認するレビュー候補です。
SIerの設計書では、同じ項目が画面、入力チェック、API、DB、外部IF、テスト仕様へ分散し、 日本語名・camelCase・snake_caseも混在します。単純な全文検索では「見つかった箇所」は分かっても、 なぜ変更対象なのか、どの経路で依存しているのか、どこまで確認したかが残りません。
SpecImpactは設計書をevidence付きgraphへ変換し、変更管理を次の形にします。
| 入力 | SpecImpactが行うこと | レビュー結果 |
|---|---|---|
| Dirty Excel / Markdown / OpenAPI / DDL / CSV | セル・表・項目・relationを抽出 | Artifact / Entity / Evidence Graph |
| 表記揺れ | LLMと周辺relationでalias候補を比較 | same / related / different / unsure |
| Agentへの自然文変更要求 | Host LLMでChange Atom化して関連subgraphを探索 | 影響候補、graph path、required actions |
| 再取り込み | source hashとrelation差分を比較 | staleなrelation / impactを再レビュー |
flowchart LR
HOST["Cursor / Antigravity"] --> MCP["SpecImpact MCP"]
subgraph Onboarding["初期導入"]
A["設計書<br/>Excel / Markdown / API / DB"] --> B["正規化<br/>Workbook・Sheet・Cell・Region"]
B --> C["Host LLM構造抽出<br/>Node・Relation・Alias候補"]
C --> D["Evidence Graph<br/>local JSONL"]
D --> E["人間レビュー<br/>Proposal / Alias"]
end
subgraph Change["継続的な変更管理"]
F["自然文の変更要求"] --> G["Change Atom"]
G --> H["GraphRAG retrieval"]
D --> H
H --> I["LLM Impact Hypothesis"]
I --> J["Evidence Verifier"]
J --> K["Impact Review Board"]
K --> L["accepted → implemented<br/>→ tested → closed"]
end
MCP --> B
MCP --> G
LLMの出力は確定情報ではなくproposal / hypothesisです。直接evidenceとgraph pathを検証できる候補だけを 強く提示し、最終判断は人間が行います。
- Dirty Excel理解: 結合セル、複数表、改訂履歴、コメント、リンク、非表示行列、同上、別紙参照を保持
- Agent Host標準: Cursor / AntigravityのLLMをMCP samplingまたはprepare/submitで利用
- Provider fallback: Codex CLI、OpenAI API、Ollama、最後にheuristicへfallback
- Alias解決:
利用限度額、requestedCreditLimit、REQUESTED_CREDIT_LIMITを根拠付きで比較 - 変更影響分析:
impact_type、required_actions、warnings、uncertaintyを作業仮説として生成 - Evidence Verifier: LLMだけの主張を
must_reviewへ昇格させない - 設計書ビューア: 影響候補から該当行・Excelセルへ移動し、検索結果のようにハイライト
- 統一Review Queue: Graph Proposal、Alias、Relation、Impact、Graph Diffを同じ画面で判断
- Freshness管理: 再取り込み時のsource version、graph diff、stale dependencyを永続化
- Obsidian連携: Wiki link、frontmatter、Dataview、Canvas付きのknowledge graphを出力
- Headless engine: CLI、Admin Console、MCPが同じApplication ServiceとJSONLを共有
- ローカルファースト: localhost承認、10分・1回限りGrant、送信監査metadata
git clone https://github.com/kanan6377/SpecImpact.git
cd SpecImpact
python -m pip install -e ".[gui,mcp]"
specimpact --versionPython 3.11以降が必要です。配布版ではuv tool install "specimpact[mcp,gui]"またはpipxを使えます。
CursorのMarketplace repositoryとしてplugins/cursorを追加し、specimpact Pluginをinstallします。
対象workspaceで確認します。
cd C:\work\my-system-impact
specimpact init
specimpact agent doctor --host cursor --project .Cursorで/specimpact-onboardを実行して設計書を選びます。その後はチャットへ、たとえば次のように入力します。
入会申込画面の「利用限度額」の上限を999万円から9999万円に変更したい。
影響箇所と必要作業をEvidence付きで調べて。
Host LLMがChange AtomとImpact Hypothesisを作り、SpecImpactがEvidence ID、graph path、property、 before値を検証します。provider API keyをSpecImpactへ設定する必要はありません。
specimpact gui --project C:\work\my-system-impacthttp://127.0.0.1:8765で、設計書viewer、Graph、統一Review Queue、Jobs/Audit、Privacy、
Obsidian exportを確認できます。日常の自然言語操作はAgent host、Consoleは監査・設定・一括レビュー用です。
specimpact onboard .\examples\dirty_sier_excel\docs `
--no-llm `
--aliases .\examples\dirty_sier_excel\aliases.yml
specimpact analyze `
.\examples\dirty_sier_excel\changes\利用限度額上限変更.md `
--llm-first --no-llm
specimpact impacts list
specimpact report --format markdownAgent hostを使わない場合だけ、既存providerを設定します。
specimpact onboard .\examples\dirty_sier_excel\docs `
--provider codex --model default `
--aliases .\examples\dirty_sier_excel\aliases.yml外部providerを利用する処理では、送信先・目的・件数を表示して承認を求めます。
CursorやAntigravityには、workspaceごとにstdio serverを登録します。
specimpact mcp --stdio --project C:\work\my-system-impactMCPは用途別Tool、Evidence Resource、4つのworkflow Promptを公開します。mutationには
idempotency keyが必須で、workspace外のpathとsymlink escapeを拒否します。未初期化案件では
specimpact://projects/{id}がonboarding手順だけを返します。詳細はMCP/Agent Hostガイドを参照してください。
Cursorを標準フロントとして使う導入手順はCursor Integrationにあります。
PluginはPythonを内包せず、uv toolまたはpipxで導入したspecimpact[mcp]をstdioで起動します。
高度な並列調査にはAntigravity Integrationを使えます。両hostとも同じ
Change Sessionとverifierへ結果を統合します。
既存GUIは削除せず、監査・設定・一括レビュー用Admin Consoleとして維持します。
| 画面 | 用途 |
|---|---|
| 概要 | graph件数、次のレビュー、案件healthを確認 |
| 設計書 | 原本追加、検索可能な一覧、押下して開くインラインビューア、Excelシート切替 |
| 変更レビュー | 自然文入力、影響候補、設計書ハイライト、Evidence Inspector |
| ナレッジグラフ | node / relation探索、stale表示、キーボード選択 |
| レビュー | Proposal、Alias、Relation、Impact、Graph Diffの判断 |
| Obsidian | Vault export、LLM送信監査、review replay |
| ジョブと監査 | 非同期処理、失敗理由、復旧手順 |
GUIは127.0.0.1だけにbindし、runtime CDNやremote fontを使用しません。frontendはwheelへ同梱済みです。
flowchart TB
HOST["Cursor / Antigravity<br/>Host LLM"] --> MCP["Typed MCP<br/>Tools・Resources・Prompts"]
MCP --> PREVIEW["TransmissionPreview<br/>elicitation / localhost Grant"]
PREVIEW --> APP["Application Service"]
UI["Admin Console / CLI"] --> APP
APP --> INGEST["Loaders<br/>Dirty Excel・Markdown・OpenAPI・DDL・CSV"]
INGEST --> EGRAPH["Evidence Graph<br/>file・sheet・cell・quote"]
EGRAPH --> DGRAPH["Domain Graph<br/>Artifact・Entity・Relation"]
APP --> LLM["Host / provider adapter"]
LLM --> PROPOSAL["Graph Proposal<br/>Change Atom・Impact Hypothesis"]
DGRAPH --> RETRIEVAL["Hybrid retrieval"]
RETRIEVAL --> PROPOSAL
PROPOSAL --> VERIFY["Evidence verifier"]
VERIFY --> IGRAPH["Impact Graph / Change Session"]
IGRAPH --> REVIEW["Host projection / Review Queue"]
REVIEW --> STORE[".specimpact/<br/>local JSONL"]
EGRAPH --> STORE
DGRAPH --> STORE
STORE --> OBSIDIAN["Obsidian Vault<br/>Notes・Dataview・Canvas"]
CLIとFastAPIは、UI非依存のspecimpact.application.ApplicationServiceを共有します。
Pydanticで定義した公開contractからREST/MCP共通のJSON Schemaを生成でき、保存形式と既存CLI出力は変更しません。
- 既定backendは案件内の
.specimpact/に保存するlocal JSONL - 原本は
.specimpact/sources/original/へ保持 - Excel evidenceはworkbook / sheet / cell / range / quoteへ戻れる
- LLM traceはprovider、model、purpose、hashなどの監査metadataだけを保存
- source hashが変わると、依存するrelation / impactを
staleとして再レビューへ戻す
| Priority | 意味 |
|---|---|
must_review |
直接evidenceと明示graph pathがある |
should_review |
強い関連があるため確認すべき |
may_review |
LLM推論または弱い関連を含む |
hidden |
verifier条件を満たさず通常表示しない |
must_reviewは「影響確定」ではありません。レビュー優先度です。
| Provider | 用途 | 外部送信 |
|---|---|---|
| Cursor / Antigravity host LLM | MCP samplingまたはprepare/submitの標準導線 | Grant必須 |
| Codex CLI | Agent hostを使わないCLI fallback | 承認必須 |
| OpenAI API | structured extraction / impact hypothesis | 承認必須 |
| Ollama localhost | ローカルモデル | 不要 |
--no-llm |
heuristic / graph-only fallback | なし |
specimpact llm configure --provider codex --model default
specimpact llm statusAgent hostではSpecImpact側のprovider設定は不要です。sampling対応hostではhost modelを呼び、
非対応hostではprepare_change / submit_change_atomsと
prepare_impact_context / submit_impact_hypothesesをAgent Skillが往復します。
どちらも保存前にSpecImpact verifierを通ります。詳細はHost LLMフローを参照してください。
specimpact export-obsidian .\vault次の構成を生成します。
SpecImpact/
├── Dashboard.md
├── Artifacts/
├── Evidence/
├── Changes/
├── Impacts/
└── Canvases/
Artifact間のrelationは[[Wiki Link]]へ変換され、Impact statusやsource locationはfrontmatterへ入ります。
SpecImpactのlocal JSONLがsource of truthで、Obsidianは探索とレビュー用のprojectionです。
- Evidence-first: confidenceではなく、引用とrelation pathを示す
- Review-assist: 設計書を自動編集せず、最終判断を自動化しない
- Local-first: 外部host/providerへはpreviewと一回限りGrantなしで文書を送らない
- Inspectable: proposal、判断、source version、graph diff、traceを永続化する
- Alias-aware: 文字列一致だけで同一概念と決めない
外部送信前には氏名、メール、電話番号、顧客番号、口座番号、URL、API key形式を検出・maskします。 ただしredactionは補助策であり、送信previewと明示承認を省略しません。
| 対応 | 状態 |
|---|---|
| Markdown / text | 対応 |
Dirty Excel .xlsx |
セル・region・style・comment・hyperlink・hidden情報に対応 |
| OpenAPI / DDL / CSV | structured loader対応 |
| 画像・図形を含むExcel | 存在を警告し、意味解析は限定的 |
| 画像だけのER図 | 未対応 |
SpecImpactは設計書の見た目を完全理解するツールではありません。文字・表・セル構造を主な解析対象とします。
pytest -q
ruff check .
python -m compileall -q specimpact
specimpact release-check .\examples\evaluation\release_cases.ymlv1.3.0では206 testsと21件のrelease benchmarkを継続しています。テストは外部LLMを呼ばず、 Fake Host / FakeLLMClientでsampling、structured output、Grant、evidence検証、alias判断、impact hypothesisを固定します。