Forge

规范驱动的 AI 辅助开发工作流（Claude Code / Codex Skills）

先充分讨论，再写文档明确需求，再基于文档设计和实现。 无 Feature Spec 不写代码。无验收计划不跑测试。发现问题必须举一反三。

这是什么 · 快速开始 · Skill 清单 · 关键机制 · 安装 · 设计哲学 · 文档导航

这是什么

Forge 是一套覆盖从头脑风暴到发布复盘完整开发链路的 Claude Code / Codex Skills：14 个专职 Skill + 1 个总入口 /forge。既可全链路串联（/forge-dev --full 从需求一路编排到发布），也可单独调用任意一环（比如只用 /forge-eng 写代码）。

核心理念是规范驱动开发（Spec-Driven Development）：每个功能在写代码前必须有 Feature Spec——Given/When/Then 行为场景 + 验收检查表——经用户确认后才进入开发；QA 基于同一份 Spec 逐项断言。文档是 Skill 之间传递上下文的唯一通道，不依赖会话历史。

解决的核心问题

系统全景

用户有想法
       │
       ▼
  ┌─────────────────┐
  │ forge-brainstorm │  头脑风暴 → 思考文档
  └──────┬──────────┘  4 模式：产品 · 内容 · 构建 · 探索
         │
         ▼
  ┌──────────┐
  │ forge-prd│  产品诊断 → PRD 当前事实 + .features Feature Spec + CHANGELOG
  └────┬─────┘  ⚠️ Feature Spec 用户确认后才进入开发
       │
       ▼
  ┌──────────┐
  │ forge-dev│  调度器 → Discussion → Research → 子技能调度
  └────┬─────┘  --full 尾段可一路编排到发布
       │ 独立上下文执行
  ┌────┼──────────────────────┐
  ▼    ▼                      ▼
┌──────────┐ ┌──────────────┐ ┌──────────┐ ┌──────────┐
│  forge-  │ │forge-design- │ │  forge-  │ │  forge-  │
│  design  │ │    impl      │ │   eng    │ │    qa    │
└──────────┘ └──────────────┘ └──────────┘ └──────────┘
 设计规划      设计→代码        工程实现      QA 验收
 自闭环                       TDD+Worktree  验收计划→测试
                                            →举一反三
       │
       ▼
  ┌──────────┐   ┌──────────┐   ┌──────────┐
  │  forge-  │ → │  forge-  │ → │  forge-  │
  │  review  │   │   ship   │   │  fupan   │
  └──────────┘   └──────────┘   └──────────┘
   代码审查       发布流程       复盘沉淀

随时：/forge → 检查项目状态，推荐下一步

快速开始

场景 A：新想法

/forge-brainstorm  → 讨论想法，产出思考文档
/forge-prd         → PRD 当前事实 + .features Feature Spec（用户确认后才开发）
/forge-dev         → 调度设计 + 工程 + QA

场景 B：已有 PRD

/forge-dev         → 检查 Feature Spec → 调度

场景 C：不知道下一步

/forge             → 检查状态，告诉你该做什么

场景 D：单独调用

/forge-eng         → 只写代码（Worktree + TDD）
/forge-qa          → 只跑验收测试
/forge-bugfix      → 系统性修 Bug

场景 E：全自动交付

/forge-dev --full   → 从需求一路编排到发布（review → ship → doc-release）
/forge-dev --resume → 从检查点恢复

forge-deliver 已于 2026-07-04 退役并入 forge-dev（归档在 _archive/2026-07-04-forge-deliver-retired/）。

场景 F：新项目一键接入

~/.claude/skills/forge-doc-policy/scripts/init-project.sh
                    → 幂等铺好 docs/、.features/、.forge/ 状态文件

效果示例

Feature Spec 确认门禁

用户    ❯ 帮我加一个频道管理功能

forge   ❯ ⚠️ 该功能没有 Feature Spec。建议先运行 /forge-prd 生成。

用户    ❯ /forge-prd

forge   ❯ Feature Spec 已生成，请审阅：
          一、用户流程：设置页 → 频道列表 → 添加/删除/排序 → 保存
          二、页面结构：3 个区块，5 个组件
          三、行为场景：3 个功能点，共 9 个 Given/When/Then 场景
          四、验收检查表：18 项（功能 9 + 视觉 6 + 流程 3）
          
          A) 确认，进入开发
          B) 整体方向需要调整
          C) 细节需要修改

举一反三

用户    ❯ 频道卡片的间距不对，应该是 16px 不是 12px

forge   ❯ 已修复。搜索代码库发现 3 处类似风险：
          1. src/components/SourceCard.tsx:42 — 同样使用 gap-3（12px）
          2. src/components/ActionCard.tsx:28 — padding 也是 12px
          3. Feature Spec 中 StarredView 组件要求 gap: 16px，当前为 12px
          
          要一并修复吗？
          A) 全部修复
          B) 选择性修复

Skill 清单

核心链路（9 个）

辅助技能（5 个）

总入口

/forge  →  检查项目状态（.features/、git branch、文档），推荐下一步

共享层

skills/_shared/ 存放被多个 Skill 引用的公共规范，随 install.sh 一起 symlink，各 Skill 只写一行引用、不复制内容（单源防漂移）：

关键机制

Feature Spec（规范驱动）

每个功能在开发前必须有 Feature Spec。完整 Spec 写入 .features/{feature-id}/feature-spec.md；docs/PRD.md 保持为产品当前真相源，只吸收已确认且仍有效的产品事实。

规范驱动规则（R1-R7）

写入项目 CLAUDE.md，每次会话自动加载：

上下文工程

解决 AI 长会话质量劣化（Context Rot）问题：

forge-dev（调度器，~30% 上下文）     forge-eng（执行器，100% 全新上下文）
┌─────────────────────┐           ┌──────────────────────────┐
│ PRD 摘要             │  Agent    │ ENGINEERING.md 全文       │
│ RESEARCH.md 摘要     │ ───────→ │ .features Feature Spec 行为场景 │
│ 执行计划             │  传递路径  │ 源代码（按需读取）         │
└─────────────────────┘           └──────────────────────────┘

同一思路贯穿全体系：每个 SKILL.md 只保留骨架和铁律，阶段细则拆进 references/ 按需加载（如 forge-bugfix 63KB → 12.6KB 骨架 + 4 份阶段手册）。2026-07-17 对标 Anthropic skill-creator 与 yao-meta-skill 完成两轮整改后，15 个 SKILL.md 总量累计下降 22%（4429→3449 行），最大文件 332 行，全部远离官方 500 行红线；触发路由用 evals/trigger-cases.md 回归。

复盘闭环（能力复利）

forge-fupan 产出账本条目（learnings.jsonl，含置信度）
       │
       ▼
下次开工：forge-bugfix P1 / forge-eng 理解现状 自动回放相关条目
       │
       ▼
再复盘：检测同类问题复发 → 复发 ≥3 次强制固化为 skill 规则

安装

# 克隆到本地
git clone https://github.com/yike-gunshi/forge-skills.git

# 运行安装脚本（默认同时安装到 Claude Code 和 Codex 可发现目录）
cd forge-skills
./install.sh

# 新开 Claude Code / Codex 会话即可使用

常用选项：

./install.sh --uninstall      # 卸载（移除 symlink）
./install.sh --target claude  # 仅 ~/.claude/skills
./install.sh --target codex   # 仅 ~/.agents/skills
./install.sh --status         # 检查当前 symlink 是否完整（含坏链检测）
./install.sh --dry-run        # 只打印动作，不改文件

安装方式是 symlink 而非复制：skills/ 目录是唯一真源，git pull 后所有会话立即用上新版本，不会产生漂移的副本。skill 清单自动发现（skills/ 下含 SKILL.md 的目录），新增 skill 无需改安装脚本。

设计哲学

1. 讨论是最便宜的修复 — 充分讨论 → 充分设计 → 才写代码
2. 文档是源代码的上游 — PRD 变更驱动代码变更，不是反过来
3. 规范驱动开发 — Feature Spec（Given/When/Then）是行为契约，无 Spec 不写代码
4. 上下文是最稀缺的资源 — 调度器精简（30%），子任务独立上下文（100%），骨架 + references 按需加载
5. 证据先于断言 — TDD + Verification Gate，声称完成须提供证据
6. 用户保持控制权 — Feature Spec、验收计划、举一反三——关键决策交用户
7. 举一反三 — 发现问题后搜索相似模式，不仅修单点
8. 原子化一切 — 每个任务独立 commit，可追溯、可回滚
9. 复盘闭环 — 教训进账本 → 开工回放 → 复发检测 → 反哺 Skill，下次更好

文档导航

仓库结构

forge-skills/
├── README.md                       ← 你在这里
├── SKILL.md                        ← /forge 总入口
├── CHANGELOG.md                    ← 版本变更账本
├── LICENSE                         ← MIT
├── install.sh                      ← 一键安装/卸载（symlink，自动发现 skill）
├── skills/                         ← 14 个专职 Skill + 共享层
│   ├── _shared/                    ←   跨 skill 公共规范（文档加载协议、视觉决策层）
│   ├── forge-brainstorm/           ←   头脑风暴
│   ├── forge-prd/                  ←   PRD 当前事实 + .features Feature Spec
│   ├── forge-dev/                  ←   开发调度器（--full 端到端）
│   ├── forge-design/               ←   设计规划（含 UX 规则/配色/字体数据库）
│   ├── forge-design-impl/          ←   设计实现
│   ├── forge-eng/                  ←   工程实现（Worktree + TDD）
│   ├── forge-qa/                   ←   QA 验收（只测不修）
│   ├── forge-bugfix/               ←   Bug 修复流水线（P0-P8）
│   ├── forge-review/               ←   PR 审查
│   ├── forge-ship/                 ←   发布
│   ├── forge-doc-release/          ←   发布后文档更新
│   ├── forge-doc-policy/           ←   文档治理规范 + init 脚手架
│   ├── forge-status/               ←   并行会话巡检
│   └── forge-fupan/                ←   复盘（Workbench 门禁 + 账本副产出）
│       └── */references/           ←   各 skill 的阶段手册（按需加载）
├── tools/
│   └── fupan-workbench/            ← 复盘工作台应用（复盘流程门禁 + 历史回看，不随 skill 加载）
├── evals/
│   └── trigger-cases.md            ← 触发路由回归用例（改 description 后过一遍）
├── _archive/                       ← 退役 skill（含 forge-deliver）
├── docs/                           ← 文档
└── assets/                         ← 架构图（SVG）

融合来源

Forge 融合了以下框架的精华：

MIT License © yike-gunshi