ForgeCraft

あなたはAIエンジニアを雇った。優秀だ。しかし、今日だけで同じVS Code拡張機能を14個も2回インストールし、絶対に掃除しないDockerコンテナを6個も立ち上げ、ディスクは空き12 GBから0 KBまで1セッションで減った。

ディスク満杯は優雅には失敗しない。VS Code、ターミナル、Docker、データベースを同時に殺す。

ForgeCraftは、あなたのAIコーディングアシスタントが従う品質契約です。つまり、速く構築しつつ、家を燃やさないことを保証します。

npx forgecraft-mcp setup .

対応ツール: Claude (CLAUDE.md) · Cursor (.cursor/rules/) · GitHub Copilot (.github/copilot-instructions.md) · Windsurf (.windsurfrules) · Cline (.clinerules) · Aider (CONVENTIONS.md)

AI支援ソフトウェア開発のための品質フレームワーク

すべてのセッション、すべてのプロジェクト、すべてのAIアシスタントを、同じ7つのプロパティからなるジェネレーティブ・スペックモデルで評価します。雰囲気ではありません。リンターのスコアでもありません。ギャップがどこにあり、なぜなのかを正確に示す14点満点のスコアです。

$ npx forgecraft-mcp verify .

| Property        | Score | Evidence                                        |
|-----------------|-------|-------------------------------------------------|
| Self-Describing | ✅ 2/2 | CLAUDE.md — 352 non-empty lines                |
| Bounded         | ✅ 2/2 | No direct DB calls in route files              |
| Verifiable      | ✅ 2/2 | 64 test files — 87% coverage                   |
| Defended        | ✅ 2/2 | Pre-commit hook + lint config present           |
| Auditable       | ✅ 2/2 | 11 ADRs in docs/adrs/ + Status.md              |
| Composable      | ✅ 2/2 | Service layer + repository layer detected       |
| Executable      | ✅ 2/2 | Tests passed + CI pipeline configured           |

Total: 14/14 ✅ PASS · Threshold 11/14

Related MCP server: MCP Policy Gatekeeper

開発環境の衛生管理 — 規約で強制

ForgeCraftは、環境汚染をインシデントではなく規約違反にするための強制可能なルールを、すべてのプロジェクトのAI指示に注入します。

VS Code拡張機能 インストール前に: code --list-extensions | grep -i <name>。必要なメジャーバージョン範囲のバージョンがすでに存在する場合のみインストールします。同じ拡張機能は同じ日に2回ダウンロードされません。

Dockerコンテナ 作成前に確認: docker ps -a --filter name=<service>。存在する場合は、作成せずに起動します。裸のdocker run（常に新規作成）よりもdocker compose up（再利用）を優先します。ログは500 MBに制限されます。docker system prune -fは、緊急時ではなく定期的なメンテナンス手順として文書化されています。

例外: 同じサービスの複数のコンテナは、プラグインセットまたはメジャーバージョンが有意に異なる場合に許可されます。たとえば、標準のpostgresコンテナと並ぶpostgres-pgvectorコンテナなどです。コンテナにはバリアントを反映した名前を付けます（例: db-pgvector、db-timescale）。それ以外の場合は、重複排除ルールが適用されます。

Python仮想環境 プロジェクトルートごとに1つの.venv。Pythonのメジャー.マイナーバージョンが一致する場合は再利用します。スタンドアロンのインストール可能なパッケージでない限り、サブディレクトリにvenvを作成しないでください。pip list --not-requiredでフラグが立てられた未使用の依存関係。

合成データと時系列データ 生成データを100 MBを超えて書き込む前に、AIは尋ねます: 生データを保持するか、統計的に凝縮するか、実行後に削除するか？コード参照がなく7日以上経過した合成データセット: 削除を依頼します。

一般 ワークスペースが既知のビルド成果物（node_modules/、.venv/、dist/）以外で2 GBを超えて成長した場合、警告を表示して停止します。ワークスペースを黙って拡張しないでください。

プロジェクトセットアップを一文で

Read the spec in docs/specs/, set up this project with ForgeCraft,
scaffold it with the right tags, recommend the tech stack, start building.

これがオンボーディングプロンプト全体です。ForgeCraftはスペックを読み取り、AIがタグを割り当て、ForgeCraftが指示ファイルを書き込み、Status.md、docs/adrs/、docs/PRD.md、docs/TechSpec.md、フック、スキルを生成します。AIは完全なコンテキストを持ちます。あなたは構築を開始します。

ForgeCraftはプロジェクトをスキャンし、スタックを自動検出し、116のキュレーションされたブロック（SOLID、ヘキサゴナルアーキテクチャ、テストピラミッド、CI/CD、24のドメイン固有ルールセット）から調整された指示ファイルを数秒で生成します。

品質ゲート

品質ゲートは、AIアシスタントが定義された瞬間（コミット前、リリース前、デプロイ後）に実行する構造化されたパス/フェイルチェックです。リンタールールではありません。各ゲートには、条件、証拠要件、人間によるレビューが必須かどうかのフラグがあります。

ゲートはリリースフェーズごとに整理されているため、グリーンフィールドプロジェクトの初日にリリース前のカオステストを実行する必要はありません:

requires_human_review: true タグが付いたゲートは自動合格できません。一部のチェックは人間が必要です。

完全なゲートライブラリ、コントリビューションガイド、スキーマは品質ゲートリポジトリ →にあります。

ADR、自動的にシーケンス化

すべての非自明なアーキテクチャ上の決定が記録されます。ForgeCraftはdocs/adrs/NNNN-slug.mdをMADR形式で自動的にシーケンス化します。コンテキスト、決定、代替案、結果。あなたのAIアシスタントは過去の選択について推論します。あなたのチームはそれらを再議論するのをやめます。

npx forgecraft-mcp generate_adr . --title "Use event sourcing for order history" \
  --status Accepted \
  --context "Order mutations need full audit trail for compliance" \
  --decision "Append-only event log, project current state on read"
# → docs/adrs/0004-use-event-sourcing-for-order-history.md

AIアシスタントのセットアップとForgeCraftの比較

claude init、Cursorのワークスペースルール、またはCopilotの指示ファイルで開始できます。ForgeCraftは、すべてのAIアシスタント、すべてのセッション、チームのすべてのエンジニアにわたって、本番標準に到達させます。

ワークフロープレイブック

セットアップ後、あなたのAIはコンテキストを持っています。これらのプロンプトが作業を指示します。コピー、ペースト、実行。

→ 完全なワークフロープレイブック · オンラインバージョン

仕組み

# First-time setup — auto-detects your stack
npx forgecraft-mcp setup .

flowchart TD
    A["<b>setup .</b><br/>npx forgecraft-mcp setup ."] --> B["Phase 1 — Analyze<br/>Reads spec · infers tags"]
    B --> C{AI assistant\nin the loop?}
    C -->|"Yes (MCP)"| D["Phase 2 — Calibrate<br/>LLM corrects tags from spec<br/>Writes forgecraft.yaml · CLAUDE.md<br/>PRD.md · hooks · ADR-000"]
    C -->|"No (CLI only)"| E["⚠️ CLI-only mode<br/>Directory heuristics only<br/>→ configure an AI assistant"]
    D --> F["<b>check_cascade</b><br/>5-step readiness gate<br/>1 · Functional spec<br/>2 · Architecture + C4<br/>3 · Constitution<br/>4 · ADRs<br/>5 · Use cases"]
    F --> G{All 5 passing?}
    G -->|"Stubs / missing"| H["Fill artifacts<br/>docs/PRD.md · docs/adrs/<br/>docs/use-cases.md"]
    H --> F
    G -->|"✅ All pass"| I["<b>generate_session_prompt</b><br/>Bound context for next task"]
    I --> J["Implement with TDD<br/>RED → GREEN → REFACTOR<br/>+ Documentation Cascade"]
    J --> K["<b>audit_project</b><br/>Score 0 – 100"]
    K --> L{Score ≥ 90?}
    L -->|"Violations found"| M["WORKFLOWS.md remediation<br/>file_length · layer_violation<br/>hardcoded_url · missing_prd"]
    M --> J
    L -->|"✅ Score ≥ 90"| N["<b>close_cycle</b><br/>Re-check cascade · assess gates<br/>promote to registry · bump version"]
    N --> O{Roadmap\ncomplete?}
    O -->|"More features"| I
    O -->|"All done"| P["<b>start_hardening</b><br/>Mutation tests · OWASP · load test"]
    P --> Q["🚢 Ship"]

    style A fill:#1a2e1a,color:#90ee90,stroke:#3a6e3a
    style Q fill:#1a2a3e,color:#87ceeb,stroke:#3a5a8e
    style E fill:#2e1a1a,color:#ffaa88,stroke:#6e3a3a
    style M fill:#2e2a00,color:#ffd700,stroke:#6e6000

ForgeCraftはセットアップ時CLIツールです。プロジェクトを設定するために一度実行し、その後削除します。ランタイムフットプリントはありません。

オプションでMCPセンチネルを追加して、AIアシスタントが診断してコマンドを推奨できるようにします:

claude mcp add forgecraft -- npx -y forgecraft-mcp

センチネルは単一のツール（約200トークン）です。forgecraft.yaml、CLAUDE.md、.claude/hooksの3つの成果物を読み取り、正しい次のCLIコマンドを導出して返します。それだけです。これは、ステートレスなリーダー、有限の成果物セット、導出されたアクションという、方法論の核となる原則をツール設計として表現したものです。初期セットアップ後に削除して、トークン予算を取り戻します。

あなたが得るもの

npx forgecraft-mcp setupの後、あなたのプロジェクトには:

your-project/
├── forgecraft.yaml        ← Your config (tags, tier, customizations)
├── CLAUDE.md              ← Engineering standards (Claude)
├── .cursor/rules/         ← Engineering standards (Cursor)
├── .github/copilot-instructions.md  ← Engineering standards (Copilot)
├── Status.md              ← Session continuity tracker
├── .claude/hooks/         ← Pre-commit quality gates
├── docs/
│   ├── PRD.md             ← Requirements skeleton
│   └── TechSpec.md        ← Architecture + NFR sections
└── src/shared/            ← Config, errors, logger starters

指示ファイル

これがコアバリューです。キュレーションされたブロックから組み立てられ、以下をカバーします:

• SOLID原則 — 具体ルール、決まり文句ではない

• ヘキサゴナルアーキテクチャ — ポート、アダプター、DTO、レイヤー境界

• テストピラミッド — ユニット/統合/E2Eターゲット、テストダブル分類法

• クリーンコード — CQS、ガード節、不変性、純粋関数

• CI/CDとデプロイ — パイプラインステージ、環境、プレビューデプロイ

• ドメインパターン — DDD、CQRS、イベントソーシング（プロジェクトが必要とする場合）

• 12-Factor運用 — 設定、ステートレス性、破棄可能性、ロギング

すべてのブロックは、確立されたエンジニアリング文献（Martin、Evans、Wiggins）からソースされ、AI支援開発に適応されています。

24タグ — AI検出、ユーザー調整可能

タグはForgeCraftにプロジェクトが何であるかを伝えます。最初のセットアップ時に、AIがあなたのスペックとコードベースを分析してタグを割り当てます。forgecraft.yamlでレビューして上書きできます。ブロックは競合なくマージされます。プロジェクトの進化に合わせてタグを追加または削除します。

完全なタグリストとコントリビューションガイドは品質ゲートリポジトリ →にあります。

コンテンツ深度ティア

すべてのプロジェクトが初日からDDDを必要とするわけではありません。

forgecraft.yamlで設定:

projectName: my-api
tags: [UNIVERSAL, API]
tier: recommended

CLIコマンド

npx forgecraft-mcp <command> [dir] [flags]

共通フラグ

--tags UNIVERSAL API     Project classification tags (or read from forgecraft.yaml)
--tier core|recommended  Content depth (default: recommended)
--targets claude cursor  AI assistant targets (default: claude)
--dry-run                Preview without writing files
--compact                Strip explanatory bullet tails and deduplicate lines (~20-40% smaller output)
--apply                  Apply changes (for refresh)
--language typescript    typescript | python (default: typescript)
--scope focused          comprehensive | focused (for review)

MCPセンチネル

オプションでForgeCraft MCPセンチネルを追加すると、AIアシスタントがプロジェクトを診断し、適切なCLIコマンドを提案できるようになります:

センチネルは単一の最小ツールです（リクエストあたり約200トークン、フルツールスイートの約1,500トークンに対して）。forgecraft.yaml、AI指示ファイル、フックが存在するかどうかを確認し、プロジェクトの現在の状態に応じたターゲットCLIコマンドを返します。

この設計は意図的です。 ForgeCraftの完全なコマンドサーフェス（21のアクション）はMCPサーバーではなくCLIにあります。MCPサーバーは、3つのアーティファクトを読み取り、1つの推奨事項を返す、まさに1つのツールのみを公開します。これは、ツール自身のアーキテクチャにおけるGenerative Specificationの原則です。ステートレスなリーダー、境界のあるアーティファクトセット、導出されたアクション。このツールは、指示ファイルに書き込む内容を自ら実践しています。

副作用として、宣言されたすべてのMCPツールは、呼び出されるかどうかに関係なく、毎ターンモデルに読み込まれます。1つのツールは200トークン。21のツールは1,500トークン。センチネルは、方法論が推奨するMCP予算（アクティブサーバー≤3）を設計上維持します。

推奨ワークフロー:

1. AIアシスタントにセンチネルを追加（以下の設定例を参照）

2. AIアシスタントにnpx forgecraft-mcp setup .を実行させる

3. アクティブなMCP設定からセンチネルを削除

4. リフレッシュや監査が必要になったら再度追加

.claude/settings.jsonに追加:

{
  "mcpServers": {
    "forgecraft": {
      "command": "npx",
      "args": ["-y", "forgecraft-mcp"]
    }
  }
}

プロジェクトルートの.vscode/mcp.jsonに追加（存在しない場合は作成）:

{
  "servers": {
    "forgecraft": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "forgecraft-mcp"]
    }
  }
}

次にCopilot Chatパネルを開き、Agentモードに切り替えると、ツールリストにforgecraftセンチネルが表示されます。

.cursor/mcp.jsonに追加:

{
  "mcpServers": {
    "forgecraft": {
      "command": "npx",
      "args": ["-y", "forgecraft-mcp"]
    }
  }
}

MCPクライアントがない場合? 問題ありません — 必要ありません。ターミナルでnpx forgecraft-mcp setup .を直接実行してください。MCPセンチネルはオプションです。CLIがすべてを実行します。

すでにclaude initを実行済みですか? npx forgecraft-mcp generate . --mergeを使用して、既存のCLAUDE.mdとマージし、カスタムセクションを保持しながら本番標準を追加してください。

無料・オープンソース

ForgeCraftは無料です。制限なし、ティアなし、APIキー不要。

品質ゲートライブラリはコミュニティの貢献によって成長します。ゲートを提案して承認された場合、あなたの名前はCONTRIBUTORS.mdに記載され、AIで構築するすべての人のための基準を引き上げることに貢献したことになります。

ゲート提案を開く → · コントリビューターを見る →

チームで使用していますか? → forgeworkshop.dev

理論的基盤

ForgeCraftはGenerative Specificationモデルを実装しています — AI生成コード品質を評価するための形式的な7プロパティフレームワークです。このモデル、S_realized収束式、リリースフェーズフレームワークはホワイトペーパーに文書化されています。

Generative Specification: A Discipline of Derivability for the Stateless Reader — Zenodo (V4.0, 2026)。オープンアクセス、DOI: 10.5281/zenodo.21726017。verifyスコアの背後にある学術的基盤。

ホワイトペーパーは理論です。ForgeCraftはツールチェーンです。ライブラリに提案された品質ゲートのうち、理論的洞察に一般化できるものは、将来のホワイトペーパー改訂に組み込まれる可能性があります。

業界の文脈: Spec-Driven Developmentの収束（ThoughtWorks Tech Radar 2025「Adopt」; Addy Osmani / Google Cloud AI agent-skills）は実践者のムーブメントです。Generative Specificationは、その実践が何であるか、なぜ機能するかを命名する形式的モデルです。

GSハーネス — AIアシスタントのための入門

ForgeCraftは**Generative Specification (GS)**を実装しています。このセクションはこのファイルを読むAIアシスタント向けに書かれています: GSとは何か、適切にスキャフォールドされたハーネスがどのようなものか、何を確認すべきかを説明します。

拘束条件 — ステートレスリーダー

すべてのAIセッションは、以前のセッションの記憶、共有コンテキスト、蓄積された規約、明確化の質問をする能力なしに始まります。アーティファクトにないものはすべて存在しません。

GSはこれを欠陥ではなく設計上の制約として扱います。導出可能性 — 新しいAIインスタンスがアーティファクトだけから正しく決定できること — が仕様が満たさなければならない基準です。ステートレスリーダーがアーティファクトから正しい出力を導出できない場合、仕様が不完全なのであって、AIが悪いのではありません。

センチネルシステム

アーキテクチャ憲法（CLAUDE.md、.cursor/rules/、.github/copilot-instructions.md、.windsurfrules）は、すべてのAIセッションのエントリーポイントです。これらは集合的に5つの必須カテゴリを含まなければなりません:

ツールシーケンスは最も一般的に欠落しているカテゴリであり、最も重大なギャップです。 ツールを列挙するだけで、いつどちらを優先すべきかを述べない仕様は、毎セッション信頼性の低い推論を強制します。

センチネルはナビゲーションツリーです: ルートは常に読み込まれ、各子ノードは自身のスコープとルーティング条件を宣言し、AIは現在のタスクに関連するブランチのみに降りていきます。すべてのリーフを結合すると完全な仕様が得られます — ロスレスです。この設計は、コンテキストの肥大化と、無関係なコンテンツの読み込みによる精度低下を防ぎます。

ブリッジ — ナビゲーションポリシーとしての構造的規律

SOLID、ヘキサゴナルアーキテクチャ、TDDはエンジニアリング規律であるだけでなく、GSプロジェクトではアクティブなナビゲーションポリシーになります:

• 実装よりもインターフェースを先に読む。 ポート/アダプター境界が明確であれば、インターフェースが契約となる。契約が不十分でない限り、実装はスキップされる。

• グリーンテストを信頼する。 TDDが徹底されていれば、テストスイートの成功は正しい動作の証拠となる。それを検証するための実装の読み取りは不要である。

• ADRは「なぜ」を記録する。 明白でない決定がすべて記録されていれば、AIはコードから意図を推測する代わりに記録を読む。

このブリッジは、従来の規律が受動的に持つ構造的利点を、トークン使用量とコンテキスト消費の測定可能な削減に変換する。

トークンのサニテーション

コンテキストウィンドウのサイズと位置的な配置は、どちらもAIの精度を低下させる（Liu et al., 2023）。GSは設計上、不要なトークン消費を最小限に抑える：

• センチネルツリーは遅延評価である。 タスクごとに関連するブランチのみが読み込まれ、仕様全体が一度に読み込まれることは決してない。

• 実装よりも契約を優先する。 インターフェース、スキーマ定義、テストのアサーションが最初に読まれる。実装ファイルは、契約だけでは答えを導き出せない場合にのみ読まれる。

• 憲法はすべてのセッションの先頭に置かれる。 最も重要なコンテンツがコンテキストの先頭位置を占める——そこは位置的な精度が最も高い場所である。

• MCPツールの表面積は制限されている。 宣言された各MCPツールは、呼び出されるかどうかに関係なく、毎ターンモデルに読み込まれる。ForgeCraftセンチネルは、完全なコマンド表面（約1,500トークン）ではなく、1つのツール（約200トークン）を公開する。このツールは、プロジェクトに書き込む方法論を実践する。

ドキュメントタクソノミー — 完全なGSプロジェクトに含まれるもの

スキャフォールドされたプロジェクトには、以下のアーティファクトタイプが含まれる。いずれかが欠けている場合、ハーネスは不完全である：

初期化カスケード：仕様は順番に生成される——それぞれは先行するものの出力であり、後続するものの生成規則である。機能仕様 → アーキテクチャ → 憲法 → ADR → ユースケース。5つのアーティファクトセットすべてを与えられたステートレスエージェントが、さらなる人間の指示なしに任意の有効な実装状態を導き出せるようになったとき、カスケードは完了する。

7つの属性 — 検証すべきこと

適切にスキャフォールドされたGSプロジェクトは、7つすべてを満たす。これらはverifyコマンドが評価するプロパティである：

設定

AIアシスタントが見る内容を微調整する

# forgecraft.yaml
projectName: my-api
tags: [UNIVERSAL, API, FINTECH]
tier: recommended
outputTargets: [claude, cursor, copilot]  # Generate for multiple assistants
compact: true                             # Slim output (~20-40% fewer tokens)

exclude:
  - cqrs-event-patterns    # Don't need this yet

variables:
  coverage_minimum: 90      # Override defaults
  max_file_length: 400

コミュニティテンプレートパック

templateDirs:
  - ./my-company-standards
  - node_modules/@my-org/forgecraft-flutter/templates

標準を最新に保つ

監査（いつでも、またはCIで実行）

Score: 72/100  Grade: C

✅ Instruction files exist
✅ Hooks installed (3/3)
✅ Test script configured
🔴 hardcoded_url: src/auth/service.ts
🔴 status_md_current: not updated in 12 days
🟡 lock_file: not committed

リフレッシュ（プロジェクトのスコープが変わった？）

npx forgecraft-mcp refresh . --apply

または、まずプレビューモードで（デフォルト）：

npx forgecraft-mcp refresh .   # shows before/after diff without writing

コントリビューション

テンプレートはYAMLであり、コードではない。TypeScriptを書かずにパターンを追加できる。

templates/your-tag/
├── instructions.yaml   # Instruction file blocks (with tier metadata)
├── structure.yaml      # Folder structure
├── nfr.yaml            # Non-functional requirements
├── hooks.yaml          # Quality gate scripts
├── review.yaml         # Code review checklists
└── mcp-servers.yaml    # Recommended MCP servers for this tag

PR歓迎。形式についてはtemplates/universal/を参照。

MCPサーバーディスカバリー

npx forgecraft-mcp configure-mcpは、プロジェクトのタグに一致する推奨MCPサーバーを動的に発見する。サーバーはタグごとにmcp-servers.yamlでキュレーションされており、PRを通じてコミュニティがコントリビュートできる。

組み込みの推奨には、Context7（ドキュメント）、Playwright（テスト）、Chrome DevTools（デバッグ）、Stripe（フィンテック）、Docker/K8s（インフラ）などが含まれ、全24タグにわたって提供されている。

セットアップ時にリモートレジストリから取得することも任意で可能：

# In forgecraft.yaml or via tool parameter
include_remote: true
remote_registry_url: https://your-org.com/mcp-registry.json

開発

git clone https://github.com/jghiringhelli/forgecraft-mcp.git
cd forgecraft-mcp
npm install
npm run build
npm test   # 610 tests, 42 suites

ライセンス

MIT

Generative Specificationの一部

**Generative Specification（GS）**を支える無料ツール——ドリフトしないAIによるソフトウェア構築のための規律：ステートレスなAIが正しいコードを導き出せるほど正確な仕様を作成し、ハーネスがそれを実稼働システムに対して検証する。

• 📄 ホワイトペーパー（オープンアクセス）：https://doi.org/10.5281/zenodo.21726017

• 🧭 ここから始める — メソッド、ツール、お客様の声：https://pragmaworks.dev

• 🔨 The Forge — チーム向け2日間のハンズオンGSワークショップ：https://forgeworkshop.dev