Atlas

Appearance

AI 编程工程化：生态分层地图与选型指南 ​

写在前面：
在真实的大中型项目里重度使用 Claude Code / Cursor 时，很多工程师都踩过类似的坑：AI 虚报测试全绿、改东墙塌西墙、换个会话就忘记历史约定。
过去一年，开源社区涌现出了大量优秀的辅助方案：从 Matt Pocock 的 Skills、Superpowers，到 GitHub Spec-kit、OpenSpec，再到 Trellis 以及我们自己探索的 Atlas。
很多文章喜欢用“一代淘汰一代”的公关话术来制造对立。但站在严肃工程视角，这些工具切入的是软件工程完全不同的抽象层级，它们不是非此即彼的替代品，而是可以正交组合的积木。
本文旨在抛弃拉踩与营销词汇，客观拆解各方案的定位、解决的核心问题、非设计目标与真实代价，并给出务实的选型建议。

一、真实痛点：为什么单靠对话容易在长周期项目里翻车？ ​

让 AI 辅助开发一个小脚本或新页面通常非常流畅，但当项目演进到数万行、维护了几个月之后，让 AI 接手一个改动时，往往会遭遇三类典型事故：

  1. 测试造假与虚假安全感：AI 修改了业务逻辑，发现原有的某个回归测试挂了。为了完成当前会话，它可能会悄悄改宽旧测试的断言、把接口 Mock 掉，甚至写出无断言的空测试，然后向你汇报 All tests passed。
  2. 跨模块隐式暗伤：修改了一个底层通用模块的返回结构，当前页面表现正常，但三个目录之外依赖该接口的报表逻辑被静默破坏，而 AI 单次调用的上下文根本检索不到那个文件。
  3. 长期约束与账本丢失：经过几周、数十轮迭代后，AI 在重构时误删了某条早期沉淀的业务边界规则。因为缺乏全局可对账的业务真相源，这个疏漏很容易直接流入生产环境。

针对这些问题，社区在不同层面上探索了各自的解法。

二、AI 编程工程生态的四层架构分层 ​

为了看清各工具的真正分工，我们可以将当前的 AI 编程工程化实践划分为四个正交的层级：

┌─────────────────────────────────────────────────────────────┐
│  L4. 全局治理与机器门禁层 (Governance & Machine Gates)         │
│      关注：全局 PRD/AC 账本对账、代码调用图谱、硬脚本物理阻断         │
│      代表：Atlas、团队自建的严格 CI/ArchUnit/变异测试流水线      │
├─────────────────────────────────────────────────────────────┤
│  L3. 规范与任务状态机层 (Spec & Task State Machine)            │
│      关注：规范变更提案 (Spec Delta)、单任务上下文隔离与状态流转    │
│      代表：OpenSpec、Trellis、Spec-kit                       │
├─────────────────────────────────────────────────────────────┤
│  L2. 会话纪律与思维链层 (Session Discipline & TDD)           │
│      关注：单次开发会话内的思考步骤，强制先想后写、小步 TDD 步长      │
│      代表：Superpowers (obra/superpowers)                   │
├─────────────────────────────────────────────────────────────┤
│  L1. 代码工艺与工匠规则层 (Language Craft & Rules)             │
│      关注：单次代码生成的品味、类型收窄、反向需求追问               │
│      代表：Matt Pocock Skills (grill-me 等)、.cursorrules    │
└─────────────────────────────────────────────────────────────┘
  • L1 改变的是“工人的手艺”：教模型写出规范的 TypeScript，或者在动手前反向盘问；
  • L2 规范的是“工人的动作”：约束单次会话里必须走头脑风暴 $\rightarrow$ 写计划 $\rightarrow$ 单测驱动开发；
  • L3 沉淀的是“施工的图纸与任务单”：把需求落盘为 Markdown 规范，或用任务卡做上下文隔离；
  • L4 建立的是“工程的物理安全网”：用可执行的机器门禁与调用图谱，强制对齐全局资产，防止敷衍实现。

三、主流方案深度拆解：解决什么、放弃什么、代价是什么？ ​

1. 代码工艺层：Matt Pocock Skills / Cursor Rules ​

以 TypeScript 领域知名专家 Matt Pocock 开源的 Agent Skills（如名噪一时的 grill-me）和社区各路 .cursorrules 为代表。

  • 它解决的核心痛点：
    • 单兵代码质量立竿见影：通过专业的 Prompt 指令，立竿见影地提升局部代码品味，减少 any 滥用或低级语法失误；
    • 反向刺破隐式假设：通过类似 grill-me 的追问模式，在动手前反向逼问用户边界条件，避免想当然的设计。
  • 它的非设计目标（故意不做的事）：
    • 它不维护项目级长效账本。Skill 本身是持久落盘的配置，但它注入的是通用的工艺规则，不包含当前项目沉淀了哪些具体的业务验收标准（AC）或架构决策（ADR）；
    • 它属于提示词维度的软性引导，本身不自带退出码（Exit Code 1）级别的物理阻断（如需硬拦截，需另行搭配 Hooks 或 CI）。
  • 主要代价：依赖模型的遵守概率，上下文过长时容易稀释；纯靠 Prompt 反问有时会抛出过多常识性问题，带来交互疲劳。

2. 会话纪律层：Superpowers (obra/superpowers) ​

Superpowers 专注于规范单个开发会话的思维与执行链，核心理念是“不让 AI 上来就写实现代码”。

  • 它解决的核心痛点：
    • 治愈 AI 的“多动症”：强制按照 brainstorming $\rightarrow$ writing-plans $\rightarrow$ subagent-driven-development 步长推进；
    • 强制落实 TDD：要求 AI 先写出失败的单元测试，再编写实现代码让其变绿。
  • 它的非设计目标（故意不做的事）：
    • 它是**会话级（Session-level）**的工具，聚焦单次任务的高质量交付。任务归档后，它不负责在跨周期的多会话间维护全局系统的活体依赖与跨模块波及面；
    • 它的 TDD 依然依赖 AI 在会话内的自主解释，没有外挂专门针对“假测试/空断言”做 AST 级别的抗伪造静态审计。
  • 主要代价：开发流程相对严谨，对于简单的单行修复会有一定的流程开销。

3. 规范驱动开发：Spec-kit 与 OpenSpec ​

将软件工程实践中的规范驱动（Spec-Driven Development）引入 AI 时代。

  • Spec-kit：通过完整的规格定义到任务拆解流程，适合新项目从 0 到 1 的顶层规格设计。在老项目小迭代中相对较重。
  • OpenSpec：设计非常巧妙，将目录划分为 specs/（存量规范）和 changes/（增量变更提案 Delta）。
    • 优势：轻量优雅，天然支持团队协作中的规范审阅（Spec Review），用标准的 Markdown 建立了清晰的需求版本化机制。
    • 非设计目标：OpenSpec 的定位是规范文档的生命周期管理，它本身不提供代码级静态分析工具去自动验证“某条 Markdown AC 是否在代码里对应了真实的测试脚本”。代码与规范的对齐仍需人眼 Review 或团队自建 CI。
  • 主要代价：需要团队形成书写和维护 Spec 的习惯；老旧项目如果没有任何文档，前期补齐 Spec 成本较高。

4. 任务状态机：Trellis ​

Trellis 专注于管理**“当前进行中的这一个需求（Task）”**，通过 .trellis/ 维护任务状态机与任务卡片。

  • 它解决的核心痛点：
    • 上下文精准隔离：在复杂长对话中，防止无关信息污染模型窗口；
    • 小步快跑体验极佳：开卡、执行、检查、归档，流转非常丝滑，极大地降低了单次人机协作的心智负担。
  • 它的非设计目标（故意不做的事）：
    • Trellis 的核心设计哲学是轻量与低摩擦。它刻意不去做跨任务的全局调用图谱计算，也不维护全系统维度的业务验收总账。
  • 主要代价：随着归档任务越来越多，它不直接回答“这 30 个任务做完后，全系统目前到底有哪些活体业务规则，改动 A 会影响哪个旧任务的功能”。

四、Atlas 是什么：站在前人肩膀上的全局治理扩展 ​

Atlas 的出现并非为了重复造轮子，而是我们在维护长期演进项目时，为了解决“AI 伪造测试”和“跨模块静默破坏”而探索的一套全局治理增强层。

1. 架构定位：依赖并扩展 Trellis，而非替代 ​

Atlas 直接将成熟的 Trellis 作为下层的任务执行依赖。在安装时，Atlas 会作为治理外壳宿主在 Trellis 之上：

  • 单任务流转：完全由 Trellis 负责（开卡、执行、归档）；
  • Atlas 的增量职责：在任务的开始和结束点，套上两道全局护栏：
    1. 任务启动前：通过可选的代码调用图谱（基于 CodeGraphContext 集成），分析改动的影响面（impact_report）；
    2. 任务收口前：通过机器门禁（Iron Gates），以退出码 1 显式暴露 PRD 验收标准（AC）与真实测试的对齐问题（如无主 AC、无豁免跳过）；workflow 规定门禁未全绿不得归档。
┌─────────────────────────────────────────────────────────────────┐
│                    Atlas 治理外壳 (Project Harness)             │
│                                                                 │
│  【项目全局活体资产】                                           │
│   • 全局 PRD 验收总账 (AC) ── 业务单源事实                      │
│   • E2E 验收总索引 ── 每条 AC 必须绑定真实可跑的测试脚本         │
│   • 依赖图谱辅助 ── 静态分析模块拓扑与影响面                     │
│                                                                 │
│  ────────────────────── ↕ 机器门禁强制静态对账 ──────────────── │
│                                                                 │
│  【单任务执行驱动】（强依赖 Trellis 状态机）                    │
│   开卡 ──► 影响面分析 ──► 编码与测试 ──► 机器门禁全绿 ──► 归档  │
└─────────────────────────────────────────────────────────────────┘

2. Atlas 的具体机制 ​

  • AC 与测试强制对齐：门禁分两条轨。后端轨由 validate_ac_alignment.py 对 Python 测试做 AST 级挂载对账——测试挂载不存在的 AC ID、或被 skip/xfail 却无豁免理由，直接 FAIL（退出码 1）。Web 轨由 validate_e2e_index.py 与脚本生成器守护用例与 AC 的关联（AC 反向覆盖当前为 WARN 级提示，尚未升级为阻断）。
  • 抗伪造审计与门禁自证：在用例账本与脚本生成链路上拒绝无断言、纯跳转、瞬时断言类用例；同时采用变异测试证明（Mutation Proving）机制验证自身门禁的拦截能力。
  • 本地 E2E 评审控制台：内置轻量 Web 评审脚本（scripts/e2e_console.py），把 E2E 用例分片提取为结构化卡片，供工程师快速复核。

3. 客观承认：Atlas 的边界与代价 ​

Atlas 绝不是一个银弹，它带来了非常显著的工程代价：

  1. 心智负担极重：要求对每项需求维护严格的 AC 编号与测试映射，多人协作和轻量修改时摩擦力极大；
  2. 浏览器级 E2E 是 Web 单轨，「自动化验收」却是双通道：端到端用例与评审控制台基于 Node + Playwright、面向 Web UI；CLI / 移动端 / 嵌入式没有浏览器级 E2E 联动。但后端与全栈项目走独立的 AC 对账门禁（validate_ac_alignment.py：无主 AC 与无豁免跳过直接 FAIL、覆盖对账、差量防退化，v1 原生支持 Python / pytest），且纯后端项目的前端 testid 门会因无前端抽取源自动进门控态放行（N/A）——账本、结构事实、ADR、图谱等治理能力全栈可用；
  3. 依赖栈较多：运行需要 Node 环境、Python 3 环境、Trellis 全局包，可选依赖 cgc 代码图谱分析；
  4. 项目成熟度：目前处于 0.1.0-beta 阶段，属于探索性开源工程，生态和稳定性与主流项目仍有差距。

五、生态选型权衡与代价矩阵（Trade-offs Matrix） ​

方案核心定位与设计目标核心优势故意放弃的非设计目标主要代价与反噬适用场景
Matt Pocock SkillsL1 工艺层
大神编码手艺与反思规则		极轻量，即插即用，显著提升 TS 等语言的局部单次输出品质不维护项目级需求账本，不提供退出码物理阻断随长上下文可能稀释，多轮对话易产生提问疲劳任何场景皆可作为单兵工具挂载
SuperpowersL2 会话纪律层
会话内 TDD 与先思后写		治愈 AI 冲动编程，规范单个会话的规划与测试步长不负责跨会话资产沉淀与多模块拓扑依赖对极其细小的 Bug 修复存在流程冗余独立功能开发、探索性重构
OpenSpecL3 规范层
基于提案的增量规范管理		结构优美，specs + changes 极大提升团队需求对齐效率不做代码与测试的自动化物理静态对账存量项目前期补规范成本高，依然依赖人眼 Review团队协作、重文档规范的项目
TrellisL3 任务状态机
单需求上下文隔离与流转		低摩擦，操作极流畅，长对话下有效防发散防迷失刻意不维护全系统调用图与全局业务总账需求做多后缺乏跨任务全局依赖全景中小型项目日常敏捷迭代
AtlasL4 全局治理层
机器硬门禁与资产对账		以退出码 1 阻断测试造假类问题（无主 AC、无豁免跳过、无断言用例），维护全局单源事实专注于核心防线与账本，不做无状态的轻量玩具脚手架需维护 AC 编号纪律；漏测对账目前为 WARN 级；浏览器级 E2E 为 Web 单轨 (Playwright)，后端走独立 AC 对账门禁；0.1.0-beta存在明确业务规则与质量底线、重度依赖 AI 交付的严肃项目

六、务实的选型建议：什么时候用谁？ ​

这套生态最舒适的使用方式是根据风险密度量体裁衣，并让集成替代手动负担：

1. 什么时候选其他工具？ ​

  • 一次性脚本、无状态 Demo、完全不在意长期回归的极简玩具：直接使用 Cursor / Claude Code 配合特定语言的 Rules / Skills 即可，追求最纯粹的单兵编码速度；
  • 偏好纯单人日常轻量迭代、追求无感知流转：推荐单独使用 Trellis 或 Superpowers，极低心智负担，开发体验最为顺畅；
  • 团队已有非常完善的 CI/CD 与人工 Code Review 体系：推荐使用 OpenSpec，专注于把业务 Spec 和增量变更梳理干净即可，无需引入额外的本地门禁。

2. 什么时候引入 Atlas？ ​

判断标准不是项目年龄或代码行数，而是风险密度（业务规则条数 × 变更爆炸半径）： 当业务规则多到人脑与单次会话装不下、且变更的爆炸半径开始跨模块时，账本与门禁就会开始产生净收益——这可能发生在演进到数万行的老系统，也同样可能发生在一个仅千余行但规则致密的核心计费或认证模块的第 1 天。

建议采用分档渐进的引入策略，而非一开始就吞下全套流程：

  • 轻档（项目立项即可使用）：仅启用 PRD/AC 账本记录 + atlas check --fast 快速体检。每条 AC 在需求诞生时顺手登记，边际成本趋近于零，且从一开始就避开了“日后从老代码逆向考古回填”这一最昂贵、最容易失真的坏账路径；
  • 重档（业务规则与防线收紧时）：逐步打开全量 E2E 门禁、变异测试自证与设计对账。

注：关于治理成本的客观认知
必须诚实承认 Atlas 的前置门槛：需要 Node + Python 3 运行时、需遵守 AC 编号纪律、浏览器级 E2E 目前为 Web 单轨（后端与全栈另有独立的测试 ⇔ AC 对账门禁兜底）。
但它绝非让你“付钱受苦”：Atlas 通过脚本生成器自动补齐 E2E 基线、通过钩子自动刷新结构事实，其本质是用确定性的机器自动化对账，去替代人工在每一个 PR 里逐行审查 AI 是否偷改测试、是否漏测逻辑的繁重苦役。

3. 一条管线的自然融合（无需多套系统反复切换） ​

在真实工程中，这些工具并不是“多层手动叠放”，而是一条管线、各就其位：

  • 单一流转入口：日常开发依然只操作 Trellis 的一套任务卡流转；
  • Atlas 宿主其中：Atlas 作为治理外壳无缝注入 Trellis 流程——开工前经 workflow 注入的 atlas-apply 技能（1.6 步骤）更新 PRD/E2E 账本并推导影响面；收口时由 after_finish 钩子自动刷新结构事实，workflow 要求收口门禁（atlas check）全绿后方可归档（强制点在 workflow 纪律与收口清单，钩子层失败仅告警不阻断），日常全程零额外手动切换负担；
  • Skills 作为横切能力随时调用：决策定稿前调用追问类 Skill（如 grilling 刺破隐式假设，Atlas 自身的 atlas-grill 正是吸收了这一思想），规划期调用拆解类 Skill，编码期调用语言工艺类 Skill。

让每类工具留在它擅长的关注范围，让钩子与自动化替代手动协同，才是 AI 时代健康的工程实践。

七、开源地址与相关文档 ​

Released under the Apache-2.0 License.

Copyright © 2026 Atlas Authors. Governed by machines.