Harness 企业级落地(二) - 让 AI 读懂项目

上一篇，我们描述了 Harness 的框架和整体设计：一套稳健的软件工程设计，约束 AI 在工程里稳定的工作。开源地址：cow-harness

AI Harness 企业级落地实践（一）

这一篇我们继续深究，一个团队如何能成长为：AI 全栈开发，可以同时维护 APP、后台、网页等多端代码。

AI 时代下，我们认为程序员不应该局限于某一门技术，应该以顶层思维看待整个项目,了解整个系统的设计和数据流向。

这样不仅能够提高个人的知识广度，更能够独立且高效地完成具体的某个模块，从而加快产品的迭代速度，实现快速的想法验证。

一、顶层设计思维

要完成 AI 全栈，得先做到：

把我们的全栈项目汇总管理起来
让 AI 读懂每个子项目的代码风格、框架分层、设计理念，并沉淀下来

进而达到：

无论什么模型，都能快速地知道你的需求，需要动到具体哪一个端
编码符合这个端的风格，代码也不会出现低级失误
编写完毕之后，能够自动启动各个端，然后自己做跨端的e2e 全流程测试

二、基于 git submodule 的项目结构

针对全栈协作的场景，APP、后端和网页端等各个端，会有各自有独立的代码仓库，同时迭代节奏和分支管理也有所不同。

所以我们先维护一个组合根仓库，把业务子项目通过 Git submodule 的方式去汇合起来，常见的结构大致是这样：

bash 复制代码

fullstack-workspace/
├── cow-harness/                    # 全栈入口与通用 Harness
├── .ai-harness/
│   └── workspace-map.md            # 业务模块地图
├── apps/mobile/                    # APP 端代码（git submodule）
├── services/backend/               # 后端代码（git submodule）
└── apps/web/                       # 网页端代码（git submodule）
│ 
└── .gitmodules

.gitmodules

记录仓库来源和落盘路径，根仓库记录每个子仓库此刻应使用的分支。这样子团队任何人拉下根仓库，都能拿到同一组前后端代码版本；
submodule 本身不会影响子项目的分支策略，分支规范、提交习惯和代码目录仍由各子仓库自己维护。

workspace-map.md

盘点子项目分别属于什么领域、是否已经初始化等；
一张地图，解决"这个任务先去哪里"。

三、让 AI 深度读懂整个项目

"读懂" 不是让 AI 把整个仓库扫一遍，然后给你写一份看上去很专业的总结；而是要非常精准的知道每个项目的设计、风格、规范约束、安全性能指标等。

为此，我们特意为这个环节编写了一个 SKILL：domain-init。

这个 SKILL 拥有非常完整的项目识别能力，不仅接入到 cow-harness，也独立进行了开源，需要自取：github.com/MinLeeV5/do...

1. 前置介绍

domain-init 会先做领域识别：从构建文件、依赖、入口、测试工具和目录结构里找信号，判断当前项目是哪个端（如：更接近 React 前端、Go 后端、移动端、CLI...）。

确定领域后，会采样真实代码，识别项目已经在使用的架构设计、组件规范、接口分层、测试夹具和验证命令等等，再把这些事实变成可 review 的规则草案。

核心重点：代码是事实源，规则只是对事实的结构化表达。

2. 四大原则

原则	它解决的问题
信号优先	先根据项目里的依赖、入口和构建文件判断领域，避免一份前端规范误用到后端或客户端。
证据先行	每条约定都要能回到项目代码中找到出处，避免模型凭记忆造出"理论正确、项目错误"的规则。
按领域过滤	前端重点看设计系统、状态和可访问性；后端重点看接口、数据和可观测性。相关的才进入上下文。
人不缺席	领域判断、扫描范围、规则草案和最终写入都有确认点。AI 负责归纳，人负责判断哪些是约定、哪些只是历史包袱。

3.最佳实践

如果只是从已有项目里抽取，会有另一个风险：可能原本项目就设计得不是很好，然后 AI 就会依照这个规范越写越烂。

于是 domain-init 还提供了一些最佳实践 references。

参考文件	设计作用	避免
`detection-signals.md`	定义领域识别的优先级、降级路径和人工确认机制。	把项目类型猜错。
`domain-matrix.md` 与 `dimension-pool.md`	用领域矩阵过滤规则、Skill 和 Agent 的适用维度。	把所有治理维度一次性塞给每个项目。
`project-index.md`	为不同问题指定开源质量标杆和应参考的关键文件。	只会套空泛的"最佳实践"。
`output-formats.md`	规定 rule、skill、agent 的结构、代码示例和证据要求。	生成只有口号、没有执行性的产物。

project-index.md ：关键的质量索引，引用了大量的优秀实践，不同的问题，我们去找不同的标杆。比如：

编码约定可以参考 everything-claude-code 的分语言规则
前端性能和组件架构可以参考 Vercel 的 agent skills
测试策略和验证门控可以看 get-shit-done
安全审查则有 gstack 和 Trail of Bits 的工作流

同时，使用这些优秀实践时，不是把别人仓库的内容拷过来。核心是让 AI 学习它如何组织规则、如何表达硬约束、如何把验证写进流程；然后再回到当前项目的代码事实，生成适合自己的内容。

验证链路：领域判断有信号，规则结论有代码，产物质量有标杆，落盘前有人 review。

四、初始化产物

初始化完成后，每个子项目里都会有一组**能被后续任务反复读取的资产。**这些资产不会放在组合根仓库，而是放在各自的业务子项目里。

bash 复制代码

services/backend/
├── AGENTS.md                       # AI 进入项目的入口
├── cow-harness/
│   └── skills/domain-init/          # 嵌套的领域初始化 skill
├── .ai-harness/
│   ├── project.profile.md           # 项目画像
│   ├── context-map.md               # 模块、入口与边界
│   ├── verification.md              # 验证方式与命令
│   └── domain-init-report.md        # 检测依据、确认范围和结果
├── .agents/                         # 当前项目选择的平台规则、skills、agents
└── .ai-runtime-artifacts/           # 需求、计划、验证与决策记录

project.profile.md ：回答"这是什么项目、关键约束是什么"；

context-map.md ：回答"代码应该改在哪里、边界在哪里"；

verification.md 回答"改完怎么证明它没问题"。

另外还会生产一些模型层的入口

domain-init-report.md ：把领域判断的依据、用户确认过的范围和生成结果保留下来，避免这些结论变成无从追问的黑盒；

.agents/ ：这个项目真正会被 AI 加载的规则、skills 和 agents；

.ai-runtime-artifacts/ ：保存需求分析、计划、验证记录和架构决策。

五、初始化后，如何执行任务

当一个任务从全栈组合根目录进入时

AI 先读 workspace-map.md
任务里出现明确的项目路径、模块名、接口名或界面名，就用这些证据定位业务子项目
结合相关的多个项目，开始判定任务体量，决定是否进行 spec 拆解
项目一旦选定，读取顺序也固定下来：先通过 AGENTS.md 进入项目，再加载 cow-harness/core/ 的通用流程，以及当前项目的 project.profile.md、context-map.md 和 verification.md
然后 AI 会遵循 harness 的规范，去使用 superpower 和 omx 开始干活

六、快速接入

维护好全栈组合仓库，先把所有子模块拉到组合根仓库锁定的版本：

css 复制代码

git submodule update --init --recursive
git submodule status --recursive

cow-harness也作为 submodule 加入到你的项目中

sql 复制代码

git submodule add git@github.com:WxqKb/cow-harness.git cow-harness
git submodule update --init --recursive

接下来让cow-harness 开始为你初始化子项目：

swift 复制代码

请先读取 cow-harness/README.md、cow-harness/init/fullstack-bootstrap.prompt.md
和 cow-harness/skills/domain-init/SKILL.md。

这是一个由多个业务子项目组成的全栈项目。请先运行
git submodule status --recursive，区分业务子项目、Harness 和第三方依赖；
展示候选业务子项目并等待我选择。只初始化我确认的子项目，
不要在组合根目录生成混合的领域规则，也不要自动改写未选择的子项目。

七、写在最后

实际上，各大基模的在 coding 的发力下，AI 对程序员行业的冲击是致命的，在大公司体感是十分明显的。

比方说：接收到的一句话需求，能让 AI 全面了解拆分，快速搭建出 A/B 方案，并发布给天使用户测试。这个流程验证以往可能要投入一周的时间，但是 AI +harness 2 天就能搞定。而这种提效方式，对个人和业务都会产生不容小视的价值，而且早已不是天方夜谭。

Harness 全栈说白了，也会卷掉一波人。

但笔者想说的是，在这个大环境下我们尽量去成长。当编码技术不再是壁垒的时候，我们应该更快速的去利用好 AI，让 AI 全面扩宽我们的知识面和业务边界。 沉淀成为我们的核心竞争力，那我相信当环境好起来后，你依然是那个香饽饽～

下一篇，我们会继续深入讲解 harness 中，是如何使用 openspec 和 omx 工作流，进行高质量的工作的。

cow-harness 开源仓库，欢迎使用！