Project OS Skills：把 Agent 开发变成产品工程系统

我以前的问题#

我以前让 Agent 写代码时，经常会这样开始：

1
帮我实现一个 xxx 功能。

然后 Agent 很快给出文件、组件、接口、脚本。短期看很高效，但后面经常会出现几个问题：

• 功能写出来了，但不知道它服务哪个用户场景。
• 架构选择是临时拍的，后面换人或者换 Agent 又要重新争论。
• 业务逻辑、接口处理、数据访问混在一起，改一个点会牵出一片。
• 隐藏 Prompt、规则、评分逻辑这类核心知识没有明确保护边界。
• 测试只在交付时跑一下，没有变成可复用资产。
• 排障修完就算，踩过的坑没有沉淀成知识库。

这些问题单独看都不致命，但叠在一起，项目就会慢慢变成一团“能跑但没人敢动”的代码。

这其实很像做衣服只看最后能不能穿，却不管版型、走线、面料和后续改衣空间。短期能交差，长期一定难看。

代码只是系统的一层#

这次最大的改变，是我开始把项目拆成几个层次看：

1
产品定位
2
 -> 护城河与知识系统
3
 -> ADR 架构决策
4
 -> 工程边界
5
 -> 黑盒与安全契约
6
 -> 运维交付
7
 -> QA 资产
8
 -> 复盘与知识库

以前我更关心“代码怎么写”。现在我会先问：

• 这个产品到底给谁用？
• 用户真正想完成的任务是什么？
• 这个项目的价值，是模型 API，还是背后的规则、流程和运营经验？
• 哪些东西必须留在服务端，不能暴露给普通用户？
• 哪些技术选择需要写成 ADR，避免以后反复争论？
• 部署失败怎么回滚？
• 测试能不能下次继续跑？
• 这次踩坑能不能变成下一次的诊断入口？

这些问题不会直接生成漂亮页面，但它们决定了项目后面能不能继续长。

Project OS Skills 做了什么#

project-os-skills 目前把这套思路拆成了几个独立 skills。

我希望 Agent 以后不是一收到需求就冲去改文件，而是在合适的节点慢下来。

比如做新项目时，先用 project-os-thinking 看产品和系统；做 AI 产品时，用 moat-first-ai-product 找出真正的护城河；做架构选型时，用 adr-driven-architecture 留下为什么现在这样选；上线或改服务器时，用 runbook-first-ops 先写清楚风险和回滚。

这不是为了让开发变慢。恰恰相反，它是为了让后面的每一次迭代不必从零开始猜。

最触动我的几个思想#

1
Internal record -> public projection
2
Internal record -> admin projection

怎么使用这个 skills 包#

如果只是想给一个项目加上 Project OS 的工作流，推荐让 Coding Agent 自己安装。打开目标项目，把下面这段话交给 Codex、Claude Code、Cursor、Windsurf、OpenCode、Gemini CLI、Hermes 或其他 Agent：

1
请按照下面这份安装指南，把 Project OS Skills 安装并配置到当前项目：
2
https://raw.githubusercontent.com/YangYuS8/project-os-skills/refs/heads/main/docs/guide/installation.md

Agent 会读取安装指南，根据当前项目选择安装模式，并帮助补全 PROJECT_RULES.md。

也可以直接在项目根目录执行：

1
curl -fsSL https://raw.githubusercontent.com/YangYuS8/project-os-skills/main/scripts/install.sh | bash -s -- --mode project --dest . --agents all

安装后，项目里会出现类似这些文件：

1
.project-os/
2
PROJECT_RULES.md
3
AGENTS.md
4
CLAUDE.md
5
GEMINI.md
6
CODEX.md
7
OPENCODE.md
8
.cursor/rules/project-os.mdc
9
.cursorrules
10
.windsurfrules

其中 .project-os/ 放通用方法和模板，PROJECT_RULES.md 记录当前项目自己的事实、约束、部署规则、测试要求和已知事故。

如果是 Hermes 这类支持原生 skills 目录的 Agent，也可以安装成原生 skills：

1
git clone https://github.com/YangYuS8/project-os-skills.git
2
cd project-os-skills
3
bash scripts/install.sh --mode skills --target hermes

我希望它改变什么#

我不希望这个包变成另一堆漂亮但没人读的文档。

它应该改变的是 Agent 参与项目的方式：

• 不要一上来就写代码，先确认产品目标和用户任务。
• 不要把公开模型能力当成护城河，要找出自己的规则、流程和知识系统。
• 不要让架构选择散落在聊天记录里，重要决策要写 ADR。
• 不要把业务逻辑塞进页面或路由里，边界要清楚。
• 不要把敏感字段返回给前端再假装安全，public/admin 契约要分开。
• 不要把部署当成最后一步，诊断、备份、验证、回滚都属于工程本身。
• 不要把测试当成一次性报告，能复用的检查才是资产。
• 不要让事故只留下“修好了”，复盘应该让系统变聪明。

这套方法不会让一个粗糙想法自动变成好产品。但它会逼着 Agent 和人一起面对那些更难、也更真实的问题。

总结#

这次经历给我的最大提醒是：开发不是把功能堆起来，而是让产品、工程、运维、测试和知识沉淀形成一个持续运转的系统。

project-os-skills 只是我目前提炼出的第一版。它肯定还会继续改，但方向已经很明确：让 AI Agent 从“代码生成器”往“产品工程协作者”靠近。

如果以后我再做 AI 产品或长期项目，我会优先把这套操作系统装进去。

不是为了显得专业，而是为了让项目在下一次需求、下一次部署、下一次事故之后，仍然能保持清醒。