sunwenzhe-git / atlas

# Atlas — 践行 Project Harness 的全流程 AI 编程工作流
> 📖 **官方文档与官网**：https://sunwenzhe-git.github.io/atlas/
> **Coding Agent 有 Agent Harness，而项目全生命周期更需要 Project Harness。** 
> 
> **Project Harness（项目级工程线束）是由 Atlas 原创提出的核心概念。** 
> 在现代 AI 编程中，外部 Agent Harness 关注的是工人（模型）在单次任务中如何调用工具与调用经验；但复杂的真实软件工程，更需要在代码库内部建立一套守护全生命周期的工程线束 —— 即 **Project Harness**。 
> Atlas 为你的项目提供这套线束：应然资产先行、机器严格对账、人机协同终验。
---
## 目录
- 一、为什么需要 Project Harness？（破局 Vibe Coding）
 - 1. 行业现实：写得越快，烂尾越彻底（NBER 弱环节假说）
 - 2. 经典体系结构 🆚 AI 时代体系结构映射
 - 3. 为什么说 Project Harness 是 AI 时代的 Spring Boot？
 - 4. 工人手记 🆚 监理蓝图：为什么有了 Agent 记忆仍需 Project Harness？
- 二、核心架构：两层正交治理体系与三环闭环
 - 1. 两层正交模型（项目级平面 🆚 需求级平面）
 - 2. 核心武器库：三环资产体系（Rings）
 - 3. 唯一单向编排件（atlas-apply 会话技能）
- 三、快速开始（Quick Start）
 - 1. 依赖准备
 - 2. 全局安装 CLI 与项目初始化
 - 3. 核对技术栈画像 (`product/stack-profile.yaml`)
 - 4. 怎么快速使用？（大白话为主，确定性入口兜底）
- 四、创新设计：E2E 用例评审控制台（人机协同终验）
- 五、技术纵深：代码图谱（Code Graph）优化逆向抽取
- 六、变异证明（Mutation Proving）
- 七、断言规范：抗伪造、累加链与 testid 薄桩
- 八、门禁系统（Gates）
- 九、自带技能生态（Built-in Skills & Agents）
- 十、贡献与流水线协同（RFC 机制）
- 十一、社区交流（钉钉群）
- 十二、开源协议（License）
---
## 一、为什么需要 Project Harness？（破局 Vibe Coding）
在纯粹依赖 Agent 自由发挥的 AI 辅助编程（Vibe Coding）中，开发者普遍会遇到难以逾越的工程瓶颈：
1. **上下文截断导致历史失忆**：长周期会话一旦被总结压缩，模型会遗忘上一轮方案为什么这么选，甚至反复推翻既有架构；
2. **“伪完成”幻觉（False Pass）**：模型宣称“功能已全部实现”，实际上只写了前端表单，未落持久化存储；或者仅凭 Toast 弹窗自证成功；
3. **单源事实坍塌**：接口契约、代码实现、测试用例散落在不同角落，修好 A 坏了 B，代码越写越腐败；
4. **形式主义审查**：让生成代码的同一个 Agent 自己审查代码，审查结果永远是”毫无问题”。
### 1. 行业现实：写得越快，烂尾越彻底（NBER 弱环节假说）
**这不是个别人的体感，而是有数据佐证的行业规律。** 
NBER（美国国家经济研究局）2026 年工作论文 35275 追踪了超过 50 万名 GitHub 开发者：自主编码 Agent 把代码提交量推高了约 240%，项目数只涨约 80%，真正发布出去的软件只涨约 30%。
论文把这种现象命名为**「弱环节假说」**——上游代码写得再快，只要卡在评审、集成、发布这些下游环节，多写的代码就变不成交付。模型只加速了「写」，加速不了「判断」——边界怎么定、改动波及谁、验收怎么算对，这些下游判断环节正是 Atlas 用应然资产与机器门禁接管的部分。
### 2. 经典体系结构 🆚 AI 时代体系结构映射
如果从计算机经典体系结构的演进视角来审视当前的 AI 编程生态，各层分工其实一目了然：
| 经典体系结构 | AI 编码时代映射 | 代表角色 / 组件 | 核心职责与分工 |
| :--- | :--- | :--- | :--- |
| **CPU / 算力核心** | **LLM（大语言模型）** | Claude 3.7 / GPT-5 / GLM-5 | 负责纯粹的逻辑推理与自回归计算（纯算力输入与输出） |
| **操作系统 / Runtime (OS)** | **Agent Harness** | Claude Code / Cursor / Pi Agent / OpenCode | **提供系统调用（Syscall）与运行环境** • 文件读写、Bash 执行（工具调用） • 内存与缓存管理（KV Cache 保温、上下文窗口截断） • 多进程调度（Subagent 派生） |
| **工程框架 / 工业级脚手架** | **Project Harness** | **Atlas** / Trellis / OpenSpec | **定义项目物理秩序与全生命周期防线** • 规范与应然资产基线（PRD / AC 账本） • 依赖图谱影响面基准（可选增强，advisory） • 机器物理阻断门禁（防止 AI 敷衍实现与伪造测试） |
### 3. 为什么说 Project Harness 是 AI 时代的 Spring Boot？
“脚手架”常被理解为 `npm create` 或 `vue-cli` 这种生成一次空目录就退场的工具。但 **Project Harness 不是一次性模板，它是像 Spring Boot 一样的全生命周期工程框架（Framework）**：
1. **从“散装手搓”走向“约定优于配置 (Convention over Configuration)”**： 
 在 Spring Boot 诞生前，Java 开发者各凭喜好手搓 XML、配置 Web 容器，团队项目极其混乱脆弱；现在的 AI 编程亦然，大家都在各自的 `.cursorrules` 和 Prompt 里给 AI 打零散补丁。**Atlas 则如同 Spring Boot，为 AI 编程立下了第一套工业级工程规范**：目录组织标准、单源事实资产、两层正交状态机，开箱即用。
2. **从“人肉盯防”走向“框架级拦截防呆 (Poka-Yoke)”**： 
 Spring Boot 依靠分层架构与拦截器（AOP）规范初级程序员的代码；而面对“极具创造力但极其热衷抄近道（写假测试、改宽断言、自报通过）”的 AI，**Atlas 的硬门禁（Iron Gates）、变异证明与 AST 静态审查充当了物理拦截器**。不满足规范的代码，在退出码层面直接阻断（FAIL=1），从机制上堵死漏洞。
3. **自带开箱即用的工程度量 (Actuator)**： 
 如同