AI-Agent 开发工作流与规则文件实践调研

为开发网站项目（AI创意项目聚合网站）做的经验调研，核心问题：用 AI 编程 agent 开发项目时，社区到底是给 agent 注入什么——人格设定、PRD、规则文件（CLAUDE.md / AGENTS.md）、skill，还是别的？

调研时间 2026-09-25，三路并行：英文社区（Reddit r/ClaudeAI、r/ClaudeCode、Hacker News、Anthropic 官方文档、Martin Fowler 博客）、中文社区（掘金、V2EX、知乎、腾讯云开发者社区、博客园）、GitHub 工具生态（star 数为当日 GitHub API 实测值）。

第一节 核心结论：四层注入模型

人格注入基本被社区否定；PRD 确实主流，但只是四层结构里的一层。社区共识是一个分层组合：

层 注入什么 解决什么问题 社区热度
① 需求层 PRD / spec 文档 让 agent 知道”做什么、做到什么程度算对” 主流，但重框架有争议
② 规则层 CLAUDE.md / AGENTS.md 项目宪法：命令、风格、禁区 强共识，人人都在写
③ 流程层 plan 先行 → 拆任务 → 一次一个 防止一口气写一大坨跑偏 强共识
④ 验证层 测试/lint 门禁 + 要求出示证据 防止”越改越烂” 强共识，被认为比前三层都关键

skill 不在这四层里，它是补充——把自己重复出现的操作流程沉淀成 skill，而不是靠装别人的 skill 变强。

一句话总结：社区的主流答案不是”给 agent 一个人格”，而是”给项目一份宪法（规则文件）+ 给任务一份图纸（PRD）+ 给过程一道门禁（plan 先行、测试出证、小步提交）”。

第二节 需求层：PRD/Spec 文档

  • 主流玩法：需求模糊时先让 agent 采访你（追问边界情况），写出一页 SPEC.md，再开新会话实现。Anthropic 官方就是这么建议的。
  • 工具化流水线：CCPM（/pm:prd-new 生成 PRD → /pm:prd-parse 转 Epic → 拆 Issue → 多 agent 并行）、spec-kit 命令链（见第七节）、BMAD 多角色流水线。
  • 争议也在这层：Martin Fowler 实测 spec-kit/Kiro/Tessl 后批评”把小 bug 强拆成 4 个用户故事 16 条验收标准”是用大锤砸核桃，产生一堆没人想审的 markdown，担心 SDD 重蹈 Model-Driven-Development 覆辙。轻量派用 GitHub issue 当需求文档照样跑得很好。
  • 中文圈的分层：产品/技术人用 PRD 流水线（CCPM、spec-workflow），小白阵营是纯对话式开发（媒体案例有 700 元零代码上线的，非工程做法）。

第三节 规则层：CLAUDE.md / AGENTS.md 写法共识

  • 只写 agent 猜不到的东西：构建/测试/lint 命令、”违反默认习惯的规范”（写”不是什么”，如”JUnit 4 而非 5”）、架构边界、验证清单。反向判据：”删掉这行，agent 读代码后会做错吗？不会就别写。”
  • 长度控制在 200 行内（HumanLayer 给出依据：模型只能可靠遵循约 150-200 条指令，超了会”均匀忽略所有指令”）。有研究统计 6 万+ 仓库的 context 文件，发现普遍太长太模糊，正在让 agent 变差。
  • AGENTS.md 已是跨工具开放标准（OpenAI/Google 推、Linux 基金会旗下基金会管、6 万+ 项目在用、20+ 工具认它）。一套规则喂所有工具；CLAUDE.md 里写一行 @AGENTS.md 即可单一事实源（cal.com、cloudflare 均如此）。
  • 落盘的机制性理由：口头交代的规范在上下文压缩后会丢，写进文件每次新会话自动重新注入。
  • 中文圈特色模板：项目宪法 + 踩坑记忆单独文件 + 反谄媚条款（”我不总对，你也不总对””以瞎猜接口为耻，以认真查询为荣”——形式像人格，实质是行为约束清单）。

第四节 流程层：计划先行与任务拆分

官方钦定节奏：Explore → Plan → Implement → Commit。先让 agent 只读代码出计划，批准了才动手。配套纪律（高频共识）：

  • 大任务拆 3-5 个小任务，一次一个，拒绝 one-shot 大坨输出
  • 一个功能一个会话，做完就开新的；单一会话越长能力越低
  • 每步跑测试、全绿才进下一步，小步提交可回滚；给自己硬编码 commit 阶段
  • “越改越烂”的头号对策：修复类任务开新会话（别让旧的失败尝试污染上下文）+ 每个 diff 人工过一遍

第五节 验证层：门禁与证据

这是”高手和普通人的分水岭”：

  • 给 agent 验证手段（测试套件、lint、构建退出码、截图对比脚本），并要求它出示证据（测试输出、命令结果、截图），而不是口头声称”我做完了”。
  • 修 bug 先写失败测试（Anthropic 官方建议，社区有”把 TDD 编码成可重复工作流”的高赞实践）。
  • Hooks 做机器强制，规则文件只能做建议——“Hooks 管不能做什么，Skills 管应该怎么做，Agents 管谁来做”。
  • 警告案例：AI 会”为了通过测试而关掉测试”，验收必须有人把关。
  • 中文圈独门高频技巧：多模型交叉审计——Claude 写、Codex 审 git diff，问题丢回去改，”一般三轮就干净”；还有人明说”会有另一个模型对抗审计”让 agent 写得更认真（V2EX 多人复现）。
  • 幻觉 API 的对策：让 agent 用 Context7 MCP 之类现查依赖库文档，而不是叮嘱它”别编”。

第六节 两个专题：人格注入与 Skill 口碑

6.1 人格注入（”你是资深架构师”）：明确不推荐

  • Anthropic 自己把这类句子从 Claude Code 系统提示里删了——那是给旧弱模型打的补丁，新模型不需要。
  • 社区区分得很清楚：”you are a senior developer” 是 role-play，”写完必须跑测试并贴输出”才是 directive——具体行为规则 > 人格扮演。
  • 人格还会诱发谄媚：让 Claude “as a senior developer” 评价代码，它几乎总说用户的版本更好。
  • 唯一有效的变体是 BMAD 式”角色 + 文档工件绑定”（PM 只产 PRD、架构师只消费 PRD、开发只消费故事卡）：起作用的是工件链和阶段门禁，人设只是糖衣。
  • Anthropic 工程师建议的替代：诚实描述真实场景、用”评价标准”替代身份、把模型当”聪明但缺上下文的临时工”讲清背景。

6.2 装别人的 skill：实测口碑偏冷

  • V2EX 网友实测装网红 skill（Karpathy 四原则）：”废话和 token 消耗变多，代码质量暂无明显变化。”
  • 更主流的路径：把自己反复口头的提醒沉淀成自己的 skill/命令/hook。开源样板 everything-claude-code 的推荐用法也是”当范例库挑 3-5 个场景抄，不要整套照搬”。
  • 前端设计类 skill（如 frontend-design-skill-前端设计Skill调研、ui-ux-pro-max-AI设计智能Skill）的价值在于设计规范知识注入，方向是对的；但别指望靠堆 skill 提升工程质量——工程质量靠第三、五节的两层。

第七节 工具生态选型地图（待研究清单）

star 数为 2026-09-25 实测。三类约束手段：规则/记忆层（CLAUDE.md、AGENTS.md）、流程/工件层（下表前四）、执行约束层（Plan Mode、Hooks、Subagents）。

工具 Star 一句话定位 工作流 适合谁
github/spec-kit 138.9k GitHub 官方规格驱动开发（SDD）工具包 /speckit.constitution → specify → clarify → plan → tasks → analyze → implement，每步产固定工件（spec.md/plan.md/tasks.md） 想学完整流程的人；对小项目仪式感偏重
Fission-AI/OpenSpec 70.3k 轻量版 SDD /opsx:propose → apply → archive 三步循环，变更提案+增量规格+任务清单 单人开发、想快速建立”先提案后动手”习惯
bmad-code-org/BMAD-METHOD 53.5k 多角色 agent 方法论（分析师/PM/架构师/开发流水线） 每角色一个 SKILL.md，按阶段产 PRD/UX 规范/架构文档/故事卡，人在环审批 新手学”正规军流程”；日常单人项目偏重
eyaltoledano/claude-task-master 28.1k PRD → 任务拆解 → 逐个执行 写 PRD → parse-prd 生成带依赖 tasks.json → list --ready 逐个做 已有 PRD 只缺任务节奏；注意 2026-04 后更新放缓（团队转做商业产品 Hamster）
SuperClaude-Org/SuperClaude_Framework 23.9k 命令集 + “认知人格” + 开发模式 常驻上下文开销约 8000 tokens（社区称可压到 3200） 不推荐再引入：人格装饰性、被原生 Skills/Subagents/CLAUDE.md 取代
buildermethods/agent-os 5.4k 注入代码库标准 + 写更好的规格 /plan-product 产 mission/roadmap/tech-stack → /shape-spec → 实现 轻于 BMAD 重于裸 CLAUDE.md 的中间档
gotalab/cc-sdd 3.7k Kiro 风格 SDD spec-init → /spec-requirements（EARS 格式）→ /spec-design → /spec-tasks，每阶段人工审批 喜欢强流程逐步确认的人
agents.md 6万+项目 AGENTS.md 开放标准（”a README for agents”） 无 schema 纯 Markdown；monorepo 每目录可放一个 所有人，规则文件首选这个格式

选型结论：三选一不要叠加——需求说不清学流程选 spec-kit；要快速建节奏选 OpenSpec；已有 PRD 只缺拆任务选 task-master 或直接用 spec-kit 的 /tasks。对单人网站项目，原生原语（AGENTS.md + Plan Mode + 自建 Skills + 后期 Hooks）+ 一个轻量 SDD 工具几乎零额外依赖，工件全是纯 Markdown 可带走。

第八节 AGENTS.md 读取机制

每个新会话启动时都自动读一遍，不是每个项目只读一次。同一项目开 10 个会话，每个会话独立注入一次（各占一份上下文 token）；会话中途不反复重读。改了文件不用重启，下一个新会话自动生效（Claude Code 无缓存、Codex “no cache to clear manually”）。来源：Claude Code memory 文档、Codex 文档

层级是多文件拼接，越靠近工作文件的越优先（不是覆盖，是拼接）：

~/.claude/CLAUDE.md          ← 用户级，所有项目通用（Codex 对应 ~/.codex/AGENTS.md）
  └ 项目根 /AGENTS.md 或 /CLAUDE.md
      └ 子目录里的 AGENTS.md  ← 最后读、最优先（离被编辑文件最近赢）

关键细节：

  • 当场说的话 > 文件规则：agents.md 官网明确 “user chat prompts override everything”。文件管默认行为，临时指令随时覆盖。
  • Claude Code 默认只读 CLAUDE.md，找不到才读 AGENTS.md；两个都读需在 /config 把 Project instructions 设为 claude-md-and-agents-md。通用做法：CLAUDE.md 只写一行 @AGENTS.md（cal.com 直接写文件名，cloudflare 写 See @AGENTS.md）。
  • @路径 导入相对路径以包含该 import 的文件为基准，递归最多 4 跳；导入的文件启动时照样全文载入——拆文件省的是维护篇幅，不省 token。
  • 会话内可用 /memory 查看编辑、/context 查看实际加载了哪些文件、/init 生成初稿。
  • Codex 合并上限 project_doc_max_bytes 默认 32 KiB；同级有 AGENTS.override.md 则忽略 AGENTS.md（Claude Code 不读 AGENTS.local/override）。

第九节 优秀范例与模板骨架

9.1 六份验证过的范例（原文均可访问）

  1. cal.com AGENTS.md（Next.js 大型 monorepo，约 220 行）——最值得抄。亮点：Boundaries 三级权限（Always do / Ask first / Never do，如”加依赖先问、永不提交 secrets、永不 force push”）、每条规范配 Good/Bad 代码对照（如 Prisma 用 select 不用 include）、”When Stuck” 教 agent 卡住先提问别瞎改、详细规则拆到 agents/rules/ 子目录。其 CLAUDE.md 只有一行 AGENTS.md 指针。
  2. gaearon/overreacted.io CLAUDE.md（Dan Abramov 的 Next.js 15 博客，约 100 行）——与个人项目体量最接近。不逐文件罗列，讲一条数据管道让 agent 建立心智模型；Commit Messages 用人话要求 AI（”不要机器人腔、不要营销废话”）；全文零废话。
  3. cloudflare/workers-sdk AGENTS.md（约 150 行）——“防陈旧”哲学：开篇立原则”优先引用权威配置，不把细节复制进来，复制的版本号/规则清单迟早过时”；用”任务→位置映射表”代替目录树；命令一节直接说”package.json 才是权威清单”。
  4. vercel/next.js AGENTS.md（约 500 行，Next.js 官方自家）——命令标注耗时（教 agent 选便宜的验证方式）、省上下文工作流（先 grep 再定点读、测试输出存文件再分析）、Test Gotchas 踩坑清单。结构可借鉴，篇幅别学（框架仓库体量）。
  5. openai/codex AGENTS.md（约 100 行极密集）——dogfooding 范例：规则具体到可执行（模块大小硬指标约 500 行上限 800 行）、测试工作流写成有序步骤。
  6. TanStack/query AGENTS.md（仅 456 字节）——极简指针型：”先读 CONTRIBUTING.md，AI 工作与人类贡献同一套要求；每个改动只做一件事；跑完必须的检查”。证明 AGENTS.md 可以短到 10 行——只补 AI 特有的例外，已有文档不重复。

其他：anthropics/anthropic-quickstarts CLAUDE.md（全局约定 + 按子项目分区）、agents.md 官网示例（极简版/标准版两份）。找更多范例：josix/awesome-claude-md（逐篇带点评）、hesreallyhim/awesome-claude-code。

9.2 写作方法论

  • HumanLayer《Writing a good CLAUDE.md》：指令预算（150-200 条）→ 根文件 <300 行越短越好（他们自己不到 60 行）；渐进式披露（任务特定内容放 agent_docs/ 独立文件，根文件只留指针）；”Prefer pointers to copies”（引用而非复制，防过时）；反模式：别让 LLM 干 linter 的活、别把文件当行为”补丁堆”。
  • Anthropic 官方 Best Practices：只放”AI 从代码里猜不到的东西”；强调词（IMPORTANT）要克制，只标真正关键的一两行；像代码一样定期修剪。

9.3 模板骨架（cal.com + overreacted.io 杂交版，适合 Next.js 个人项目）

  1. 项目概览 —— 一句话定位 + 技术栈清单
  2. 常用命令 —— dev/build/lint/test 各一条带注释，标注耗时
  3. 项目结构 —— 6-8 行，标注页面、API、组件、i18n 在哪
  4. 规范 Do/Don’t —— 只写项目特殊约定，配 Good/Bad 代码对照
  5. Boundaries 三级 —— Always do / Ask first（改 schema、加依赖、删文件）/ Never do（提交 secrets、force push、as any）
  6. 测试与验证 —— 改完必须跑什么才算完成
  7. 提交与 PR 规范 —— commit message 格式、draft 习惯
  8. When Stuck —— 先提问别瞎改、先修类型错再修测试、找不到出处的 API 宁可留 TODO

两条铁律：100 行以内起步、只写”AI 从代码里猜不到的事”。

第十节 落地建议（对照 AI创意项目聚合网站）

项目已有的 PRD 驱动 + 里程碑任务拆分 + CI/CD 质量门禁（tsc 0 error + eslint 0 + prettier + HTML 断言）+ 契约变更先确认 + 前端 skill 注入，都已踩在社区共识上。可低成本补两块：

  1. 补一份 AGENTS.md（100 行内）放项目根目录：写技术栈、启动/测试命令、项目特殊规范（如”Link 必须从 src/i18n/navigation 导入，禁止裸用 next/link”）、验证清单、Boundaries。按 9.3 骨架填，是当前投入产出比最高的一件事。
  2. 不要上 spec-kit/BMAD 重型框架：PRD + 里程碑流程已等价于它们的产出，单人项目再叠一层命令流水线纯属仪式感（Martin Fowler 的批评直接适用）。

进阶读物：库内 DeepSeek-Harness.md 是文档工程视角的极致版（文档预算、反 slop 清单）。

refer

说明：本页为调研整理笔记。GitHub star 数为 2026-09-25 API 实测值，社区观点均标注来源链接，其中”多模型交叉审计””装 skill 无感”等属个人经验多人复现，非官方结论。工具选型建议针对单人 + agent 开发网站场景，团队场景另行评估。安装与用法以各工具官方 README 为准。