loom

loom — Weave Specs into Execution

AI 工程化框架。把需求、规范、上下文、执行过程"织"成一套稳定工程流程。

loom 是什么

• 一套 skills + commands + hooks 的集合，注入到 AI 编程工具中
• 一条 按任务类型自适应的开发流水线：根据 feature / bugfix / hotfix / refactor / quickfix / chore / qa / pm-prototype 自动选择对应步骤
• 一个 CLI 工具（loom），负责安装、更新、诊断、卸载，以及流水线执行（run/status/tasks/index）、证据导出（evidence）、结构化记忆（memory）和 MCP server（mcp-serve）
• 一个 项目初始化器（/loom-init-project 或 loom init-project），自动扫描项目生成宪章、结构化记忆和 agent 入口

从需求描述出发，经过头脑风暴、计划拆解、隔离开发、代码审查，最终交付。

支持工具矩阵

工具	支持等级	入口文件	Skills	Hooks	Plugin	MCP 配置
Claude Code	full	CLAUDE.md	✅	✅	✅	✅
Codex	full	AGENTS.md	✅	✗	✗	✅
Cursor	full	.cursor/rules/*.mdc	✅	✗	✗	✅
GitHub Copilot	full	.github/copilot-instructions.md	✅	✗	✗	✗
OpenCode	full	AGENTS.md	✅	✅	✅	✅

• full：完整支持，适配器已实现
• Hooks：Claude Code 通过插件接入完整 hook 运行时；OpenCode 适配器已注册插件和 MCP，原生事件 hook 的运行时扩展仍以 config/tools.schema.json 的适配器契约为准。
• 适配器契约：工具能力、安装范围、配置面、loom-managed 产物和版本探测方式以 config/tools.schema.json 的 contract 为单一源，并生成到 src/generated/tooling.js 的 ADAPTER_CONTRACTS；loom doctor 会基于契约输出一致性和版本诊断

安装

前置条件

• Node.js >= 22
• （可选）codegraph — 装了则 loom index 自动委派给它做 AST 级图索引，并注册其 MCP server；未装则跳过图查询能力

方式一：一键安装脚本

git clone https://github.com/xiqin/loom.git
cd loom
bash install.sh --tool claude-code

远程一键安装：

# Unix
curl -fsSL https://raw.githubusercontent.com/xiqin/loom/main/install.sh | bash -s -- --tool claude-code

# Windows PowerShell
irm https://raw.githubusercontent.com/xiqin/loom/main/install.ps1 -OutFile install.ps1; .\install.ps1 -Tool claude-code

方式二：npm 安装

npm i -g loom-engineering
loom install --tool claude-code

安装选项

Flag	作用
--tool <targets>	目标工具（必填，逗号分隔或 "all"）
--dry-run	预览，不实际写入
--from-release	从 GitHub release tag 下载（可重现安装）
--version <ver>	指定下载版本（配合 --from-release）

安装后验证

loom doctor    # 诊断安装状态
loom list      # 列出可用 skills 和 commands

MCP 性能开关

loom 的 MCP server 支持通过环境变量控制工具暴露和运行统计。需要把变量配置到客户端启动 loom mcp-serve 的 MCP server 配置里，而不是只在普通 shell 会话里临时设置。

变量	建议值	作用
LOOM_LAZY_TOOLS	1	启用 MCP 工具懒加载，默认只暴露基础工具，按需加载 pipeline/context/memory/session 工具组，减少工具定义带来的上下文开销。
LOOM_TELEMETRY	1	开启 loom MCP 工具调用统计，记录调用次数、耗时、响应字节数和估算响应 token；可通过 loom_telemetry 工具查看，MCP server 退出时也会向 stderr 输出摘要。

配置示例：

Claude Code (~/.claude.json):

{
  "mcpServers": {
    "loom": {
      "command": "loom",
      "args": ["mcp-serve"],
      "env": {
        "LOOM_LAZY_TOOLS": "1",
        "LOOM_TELEMETRY": "1",
      },
    },
  },
}

// OpenCode: mcp.loom.environment
{
  "mcp": {
    "loom": {
      "type": "local",
      "command": ["loom", "mcp-serve"],
      "enabled": true,
      "environment": {
        "LOOM_LAZY_TOOLS": "1",
        "LOOM_TELEMETRY": "1",
      },
    },
  },
}

修改 MCP 配置后需要重启对应客户端，运行中的 MCP server 不会自动继承新环境变量。

初始化项目上下文

在 Codex/Claude/OpenCode 中直接触发 loom-init-project skill 即可；脚本由 skill 自动运行，不需要用户手动调用。

也可以使用 CLI：

loom init-project

卸载

卸载

# 脚本卸载
bash uninstall.sh --tool claude-code
.\uninstall.ps1 -Tool claude-code

# CLI 卸载
loom uninstall --tool claude-code

卸载只清理用户级安装的文件（用户目录下的 skills、commands、plugin 注册），不碰项目目录中的任何文件。

恢复

如果误卸载，重新安装即可：

loom install --tool claude-code

版本与发布策略

• 遵循 Semantic Versioning
• 版本号在 package.json 中定义，通过 scripts/sync-version.mjs 同步到所有元数据文件
• 每个生成的文件包含 loom:version=x.y.z 标记，用于检测已安装版本
• loom update 自动比较版本号，仅在版本不同时更新
• loom doctor 显示当前安装状态和版本

版本检查

loom doctor
# 输出示例：
#   Tool: claude-code
#   Version: 2.0.1
#   Status: installed

流水线

流水线由 .loom/workflow.yaml 集中定义。支持两种模式：

• 类型模式：loom run --type <feature|bugfix|hotfix|refactor|chore|quickfix> — 按预设类型选择固定流水线
• 智能模式：loom run --auto --request "<需求描述>" — AI 自主分析需求，从 step_catalog 中选择最优步骤组合

智能模式经过三段决策：规则短路（0 token）→ AI fallback（可选）→ 规则兜底。首次选择只返回结果，不初始化；执行前会向用户说明选择来源、风险等级和步骤顺序，并等待用户明确确认。确认后把 dynamic_steps 写入 pipeline.state.json，并在自动生成的 progress.md 中记录当前阶段和动态步骤，便于 AI 在没有对话上下文时继续执行。

如需先审查或手动调整步骤，也可以独立使用 loom select 子命令生成 pipeline-plan.md：

loom select --spec-dir specs/feat --request "重构状态管理，跨模块改动"

阶段完成时使用 handoff 记录压缩后的交接摘要，便于后续阶段或无上下文续跑读取；progress.md 会自动刷新 Handoffs 摘要，不要手动编辑：

loom handoff write --spec-dir specs/feat --stage planning --status done --summary "计划已确认" --artifacts plan.md,tasks/
loom handoff write --spec-dir specs/feat --task T1 --summary "导出认证服务接口" --artifacts src/auth/service.ts
loom status --spec-dir specs/feat

MCP 客户端可调用 loom_write_handoff 写入相同结构的 stage 或 task handoff。stage 与 task_id 二选一，常用字段包括 status、summary、artifacts 和自定义 data；status 允许值为 done、partial、blocked、failed。

合规历史可以通过 loom evidence 规范化为 loom.evidence.v1 视图，用于本地检查、CI 导出或 PR 报告输入：

loom evidence --json --hash-artifacts
loom evidence --jsonl --out .loom/evidence/evidence.jsonl
loom evidence --format markdown --out .loom/evidence/report.md
loom evidence --format html --out .loom/evidence/report.html
loom evidence --trends --out .loom/evidence/trends.json

流水线类型

类型	适用场景	包含步骤
feature	新功能开发	brainstorming → planning → approved → git-worktree → executing → verification → code-review → synced
bugfix	已定位的 bug 修复	planning → approved → executing → verification → code-review → synced
hotfix	生产紧急问题	approved → executing → verification
refactor	代码重构	brainstorming → planning → approved → executing → verification → code-review → synced
quickfix	单文件小改动、已知 bug 小修复	executing → verification
chore	依赖升级、配置调整、文档更新等	executing → verification
qa	QA 验收测试	qa-analysis → qa-design → qa-approved → qa-execution → qa-signoff → qa-report
pm-prototype	PM 原型探索	brainstorming → spec-approved → prototype

AI 收到任务后会先判断类型并告知用户，必须等用户明确确认后再初始化或读取对应流水线执行。未指定类型时默认使用 feature。code-review 为对抗审查段（code-review-request → review-gate → code-review-response），低风险流水线（hotfix/quickfix/chore）跳过。

feature 流水线步骤

Step	阶段	说明	输出
1	brainstorming	需求头脑风暴，探索 2-3 种实现方案	spec.md + requirements.json
2	writing-plans	按分层拆解 task	plan.md + tasks/ + traceability.json
3	git-worktree	创建隔离分支	feature 分支
4	subagent-driven-development	Subagent 隔离派发 + 双审查	源码 + test-report.md + 更新后的 traceability.json
5	verification	完成前验证，Spec覆盖/类型一致性/编译测试	verify-report.md
6	code-review-request	双轴预审查（Standards + Spec）+ Spec 遗漏自审，生成审查请求	review-request.md
7	review-gate	人工 gate，等待审查者反馈	—
8	code-review-response	处理审查反馈，修复 BLOCKER，push back 不合理建议	review-response.md
9	index-update	codegraph 同步与结构化记忆更新（无 codegraph 时跳过索引）	codegraph 图索引 / .loom/memory/store.json

结构化账本可用独立脚本主动生成或检查：

npm run requirements:generate -- --spec-dir specs/feat
npm run requirements:check -- --spec-dir specs/feat --required
npm run traceability:generate -- --spec-dir specs/feat
npm run traceability:check -- --spec-dir specs/feat --required

requirements.json 记录每个 REQ-xxx 的 types、required_categories 和 behavior；traceability.json 记录 REQ -> behavior -> task/test/evidence 闭环。

代码审查

6 维审查

维度	关键检查项
架构合规	是否遵循项目架构分层（从 constitution.md 读取）、是否存在跨层调用
代码质量	是否使用了项目禁止的调试函数、SQL 是否参数化（防注入）
安全风险	SQL 注入检查、认证/授权是否正确
性能隐患	N+1 查询检查、分页查询是否使用框架分页组件
规范一致性	命名是否符合项目规范、响应格式是否统一
变更影响范围	本次变更的函数、接口、类型是否被其他模块引用（codegraph 可用时查 codegraph_impact/codegraph_callers，否则用源码搜索补充判断）、公开接口的参数签名是否变化（新增必填参数、删除字段、类型变更）

Skills（22 个）

10 流水线 + 4 辅助 + 7 通用 + 1 测试 Skill，共 22 个

核心流水线 Skills：

Skill	输出	说明
loom-brainstorming	specs/<date+feature>/spec.md	需求头脑风暴, +可视化伴侣、设计自检、用户审查 Gate
loom-detail-expansion	specs/<date+feature>/requirements.json	按 15 维度展开 Behavior Obligation，补齐 test_plan 与 applicability
loom-writing-plans	specs/<date+feature>/plan.md	分层拆解 task, +模型选择、类型一致性检查
loom-analyze-artifacts	specs/<date+feature>/artifact-analysis.json	planning 后审批前跨产物一致性只读分析
loom-using-git-worktrees	feature 分支	创建隔离分支, +测试基线验证
loom-subagent-driven-development	源码 + 测试报告	Subagent 派发 + 双重审查,独立模板文件、4种状态处理
loom-converge	specs/<date+feature>/convergence-report.json	executing 后 verification 前对照意图清单，missing/partial 回流 executing
loom-omission-hunter	specs/<date+feature>/findings/omission-hunter.json	只读对抗式审查，负空间检查（应存在但不存在）
loom-verification-before-completion	验证报告	完成前验证, +Spec覆盖、类型一致性、编译测试
loom-index-update	codegraph 同步 + 结构化记忆	codegraph 同步

辅助 Skills：

Skill	说明
loom-init-project	项目初始化（扫描 + 生成宪章/记忆/入口）
loom-router	轻量入口路由（分流到 skill 或 pipeline selector，不写流水线状态）
loom-pipeline-selector	开发流水线步骤选择（确认后写入 dynamic_steps）
loom-using-loom	loom 框架使用指南（本 skill）

通用 Skills：

Skill	说明
loom-test-after-implementation	实现后测试，先实现再重构再写行为验证测试，+流程图、好/坏示例、常见误区表
loom-systematic-debugging	系统化调试, +4阶段流程图、条件等待、纵深防御
loom-requesting-code-review	请求代码审查, +预审查清单、Spec遗漏自审、审查模板
loom-receiving-code-review	接受代码审查, +响应模板、流程图
loom-dispatching-parallel-agents	并行 agent 派发, +模型选择、并发工作流图
loom-writing-skills	编写自定义 skills, +方法论深度、流程图
loom-finishing-a-development-branch	分支完成流程 , +选项展示（Merge/PR/Keep/Discard）

测试 Skills：

Skill	输出	说明
loom-qa	qa/<date+target>/qa-report.md	QA 验收流水线，测试人员使用：新功能验证 + 回归 + 集成测试 + 持久化用例库

完整定义详见 skills/loom-using-loom/SKILL.md 或 .loom/skills/ 目录

文档索引

除本 README 外，docs/ 目录提供以下文档：

文档	说明
docs/pipeline-reliability-improvement-plan.md	流水线可靠性改进方案（P0/P1/P2 完整设计与落地清单）
docs/pipeline-validators.md	流水线声明式 validator 注册表、审批门禁、handoff 指纹、防漂移测试
docs/traceability-ledger.md	结构化账本 requirements.json / traceability.json 字段、维度白名单、校验阶段、CLI
docs/skills-reference.md	Skills 快速参考（触发、输出、下一步）
docs/architecture.md	目录结构、核心模块、数据流、Hook 系统、Schema 驱动、测试架构
docs/system-design.md	系统设计、流程图、阶段语义
docs/project-overview.md	项目总览与分层阅读路线
docs/installation.md	安装、初始化、子命令用法
docs/customization.md	项目级 / skill 级 / 流水线级自定义
docs/generated-files.md	自动生成文件清单与生命周期
docs/install-security.md	安装位置与写入规则
docs/uninstall.md	卸载流程
docs/naming.md	命名约定与内部术语

License

MIT