ForgeCraft

你雇了一位 AI 工程师。它很出色。但它今天把同样的 14 个 VS Code 扩展装了两遍，启动了 6 个永远不会清理的 Docker 容器，而你的磁盘在一个会话里从 12 GB 可用空间变成了 0 KB。

磁盘满不会优雅地失败。它会同时杀死 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 属性生成式规范模型来衡量。不是凭感觉。不是 linter 分数。而是一个满分 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>。仅当所需主版本范围内没有已安装的版本时才安装。同一个扩展不会在同一天被下载两次。

Docker 容器

创建前检查：docker ps -a --filter name=<service>。如果已存在，就启动它——不要创建。优先使用 docker compose up（复用）而不是裸 docker run（总是新建）。日志上限为 500 MB。docker system prune -f 被记录为定期维护步骤，而不是紧急措施。

例外： 当同一服务的多个容器在插件集或主版本上有显著差异时，是允许的——例如，一个 postgres-pgvector 容器与一个标准 postgres 容器并存。容器命名要体现变体（例如 db-pgvector、db-timescale）；否则适用去重规则。

Python 虚拟环境

每个项目根目录一个 .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 助手在定义好的时刻运行——提交前、发布前、部署后。它们不是 linter 规则。每个门禁都有一个条件、一个证据要求，以及一个是否必须人工审查的标志。

门禁按发布阶段组织，这样你就不会在绿地项目的第一天就运行发布前的混沌测试：

标记为 requires_human_review: true 的门禁不能自动通过——有些检查需要人类。

完整的门禁库、贡献指南和模式位于质量门禁仓库 →

ADR，自动排序

每个不显而易见的架构决策都会被记录。ForgeCraft 以 MADR 格式自动排序 docs/adrs/NNNN-slug.md——上下文、决策、备选方案、后果。你的 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 助手设置 vs 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 个 token）。它读取三个工件——forgecraft.yaml、CLAUDE.md、.claude/hooks——推导出正确的下一个 CLI 命令，并返回它。仅此而已。这是方法论的核心原则在工具设计上的体现：一个无状态读取器、一个有限的工件集、一个推导出的动作。初始设置后移除它以回收 token 预算。

你会得到什么

运行 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 个 token，而完整工具套件约 1,500 个）。它检查 forgecraft.yaml、你的 AI 指令文件和钩子是否存在，然后针对项目当前状态返回对应的 CLI 命令。

这是有意为之的设计。 ForgeCraft 的完整命令面——21 个操作——位于 CLI 中，而非 MCP 服务器。MCP 服务器只暴露一个工具，读取三个工件并返回一条建议。这正是 Generative Specification 原则在该工具自身架构中的体现：一个无状态读取器、一组有界的工件、一个推导出的动作。该工具践行了它写入你指令文件中的理念。

一个副作用：每个声明的 MCP 工具都会在每一轮被模型读取，无论是否被调用。一个工具消耗 200 个 token，二十一个工具消耗 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 将此视为设计约束，而非缺陷。可推导性（Derivability）——一个全新的 AI 实例仅凭工件就能正确确定的内容——是规范必须满足的标准。如果无状态读取器无法从工件中推导出正确的输出，那么是规范不完整，而不是 AI 的问题。

哨兵系统

架构宪法（CLAUDE.md、.cursor/rules/、.github/copilot-instructions.md、.windsurfrules）是每次 AI 会话的入口。它必须共同包含五个强制类别：

工具排序是最常缺失的类别，也是后果最严重的缺口。 一份只列出工具而不说明何时优先使用哪个工具的规范，会让每次会话都进行不可靠的推断。

哨兵是一棵导航树：根节点始终加载；每个子节点声明自己的范围和路由条件；AI 只深入与当前任务相关的分支。将所有叶子节点连接起来就得到完整的规范——它是无损的。这种设计防止了上下文膨胀以及加载无关内容带来的精度下降。

桥梁——作为导航策略的结构性纪律

SOLID、六边形架构和 TDD 不仅是工程纪律——在 GS 项目中，它们成为主动的导航策略：

• 先读接口，再读实现。 当端口/适配器边界清晰时，接口就是契约。除非契约信息不足，否则跳过实现。

• 信任通过的测试。 当 TDD 被强制执行时，通过的测试套件就是行为正确的证据。无需阅读实现来验证。

• ADR 记录原因。 当每个非显而易见的决策都被记录时，AI 读取记录而非从代码中推断意图。

这座桥梁将先前纪律的被动结构性收益转化为可衡量的 token 消耗和上下文占用的减少。

Token 净化

上下文窗口大小和位置排布都会降低 AI 的准确性（Liu 等，2023）。GS 通过设计最小化不必要的 token 消耗：

• 哨兵树是惰性的。 每个任务只加载相关分支——绝不会一次性加载完整规范。

• 契约优先于实现。 先读接口、schema 定义和测试断言。仅当契约不足以推导出答案时才读取实现文件。

• 宪法引领每次会话。 最重要的内容占据上下文的领先位置——那里位置准确性最高。

• MCP 工具面是有界的。 每个声明的 MCP 工具都会在每一轮被模型读取，无论是否被调用。ForgeCraft 哨兵只暴露一个工具（约 200 token），而非完整的命令面（约 1,500 token）。该工具践行它写入你项目的方法论。

文档分类——完整 GS 项目包含什么

一个脚手架项目包含以下工件类型。如果缺少任何一项，则脚手架不完整：

初始化级联：规格按顺序生成——每一项都是前一项的输出，也是后一项的生产规则。功能规格 → 架构 → 宪法 → ADR → 用例。当无状态代理获得全部五组工件后，无需进一步人工指示即可推导出任何有效的实现状态时，级联即告完成。

7 项属性——要验证什么

一个正确搭建的 GS 项目满足全部七项。这些是 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

生成式规范的一部分

生成式规范（GS） 背后的免费工具——一种用 AI 构建不漂移软件的方法：你编写足够精确的规范，使无状态 AI 从中推导出正确的代码，并由脚手架针对真实系统进行验证。

• 📄 白皮书（开放获取）：https://doi.org/10.5281/zenodo.21726017

• 🧭 从这里开始——方法、工具、用户评价：https://pragmaworks.dev

• 🔨 The Forge——为你的团队提供为期 2 天的 GS 实操工作坊：https://forgeworkshop.dev