夜雨聆风从 IDEA 到 App 的 AI Native 项目流程
目标
在之前发布的的博客中，我已经介绍了我的脚手架（Java） + Docs 文档体系，今天这篇长文，我会详细介绍我用 Coding Agent ，通过使用我的 AI Native Project Template，管理需求、统一语言、文档、计划、测试，把 IDEA 落地成一个应用，本文不包含商业验证和变现相关内容。
前置条件
• 已经有一个相对明确的产品 idea，不需要非常完整，但是至少能说清楚核心功能 • 已经安装或准备使用 AI Native Project Template： • GitHub 地址： https://github.com/ryan-alexander-zhang/ai-native-project-template• CLI 地址： https://github.com/ryan-alexander-zhang/ainpt• 本文使用 english-copilot作为 demo：一个英语学习助手 Web 应用。
AI Native Project Template 是我搞得一个模板项目，不是一个完整应用脚手架。没有预设前端框架、后端框架、部署平台，是一套 docs-first 的项目工作模板，安装ainpt 并创建项目ainpt create english-copilot 。
整体链路
这套流程的核心是：
idea -> prd -> spec（link user story） -> design -> decision(optional) -> plan -> coding -> verify• idea：还没有完全产品化的想法，记录问题、初始能力、边界和早期判断。• prd：产品需求，说明为什么做、给谁用、做什么、不做什么。• spec：系统视角的规格，说明系统到底应该做什么。• us：User Story，核心，挂在 spec 下面，承载用户价值视角的需求描述，含EARS 需求和 GWT 验收。• design：跨功能或者结构性的技术设计，比如领域模型、数据模型、状态机等• decision：有取舍的产品、技术、架构决策（ADR）• plan：具体如何实现，拆任务、列文件、列验收
项目模板要求每个主要文档都有 front matter，通过 front matter 管理类型、状态和 Link，唯一 ID 可全局检索，
---id: <type>-<five-digit-number>-<slug>type: idea|prd|spec|us|design|decision|plan|issue|...role: mainstatus: draftparent: <upstream-id>---parent 很关键，用来串联上下游文档
idea-00001-english-learning-copilot -> prd-00001-english-learning-copilot -> spec-00001-auth-accounts -> us-00001-register-email-password -> plan-00001-auth-accounts这样做的好处是，后面 review、补需求、修 bug 的时候，Agent 能顺着文档链找到“当初为什么这么做”，而不是只看当前代码猜。
步骤一：先得有个 IDEA
先得有一个 IDEA，本文会以一个英语学习的 Web 应用举例
我有一个idea，做一个英语学习的助手1. 预设系统级别单词本，比如预设CET4、CET6，单词本可以设置 include 和 exclude，与后文有关2. 用户可以创建用户级别单词本，然后可以添加单词，添加单词时可以输入一个或多个例句，每个例句可以对应一个 URL。每个用户初始化都有一个默认的单词本，相关操作如果没有选择单词本都会添加到这个默认单词本中。3. 用户可以在设置页面配置多个外部词典的 template url，比如有道词典的https://www.youdao.com/result?word={argument name="word"}&lang=en，这样每一个单词可以跳转到外部的词典中4. 可以通过浏览器插件 Clip 网页为 Markdown 成为一份系统内部的学习材料，这份材料中的单词，如果命中了include，则高亮显示，如果命中了 exclude 则不高亮显示，同一个单词如果同时在include 又在exclude，exclude 优先级更高5. 在查看学习材料详情页，用户可在文章中选中句子添加注解，注解可以设置描述和颜色，注解可以单独查看，注解也可以编辑和删除6. 在查看学习材料详情页，用户可以在文章中选择单词，添加到单词本中，单词本可选择，没有选择则添加到默认用户级别单词本7. 用户可以分享学习材料，包括添加的标注，分享后会有一个只读链接，可以Public 访问8. 登录认证，可以注册、登录，也可以用 Google 登录认证步骤二：创建项目
使用 AI Native Project Template 创建项目：
ainpt new english-copilot
文件大概说明：
• ARCHITECTURE.md：当前系统形态、技术栈、模块结构、边界。• AGENTS.md：Agent 在这个 repo 里工作的规则。• CONTEXT.md：从CONTEXT_TEMPLATE.md创建出来的项目统一语言。• DEVELOPMENT.md：开发阶段、命令、Definition of Done，微调• TESTING.md/UNIT_TESTING.md/INTEGRATION_TESTING.md/API_TESTING.md/E2E_TESTING.md：测试分层和命令，其中API_TESTING我固定为 Bruno，其他都需要进行调整。• DOCUMENT.md：文档管理规则。• THIRDPARTY.md：外部依赖、参考资料、第三方代码来源。• docs/README.md：docs/目录分类和 front matter 规则。
步骤三：先统一语言
为什么要做这件事？举个例子，比如单词本语义，在语言表述中，我们可能会用单词本、WordBook、WordsBook、Vocabulary、单词数据库等等各种各样的词汇都可能会使用，如果不约束 AI，有可能就会出现各种各样的表达。等 Agent 用grep|rg 去检索词的时候，如果模型没有把这些词汇罗列，就漏掉了。CONTEXT.md 作为 Agent 后续写idea、prd、spec、代码、测试时的词汇事实源，新词需要注册，语言一统一，就能减少后续因为关键词检索导致的上下文丢失的问题。
项目初期保留的CONTEXT.md 内容：
# English Learning Copilot ContextThe shared glossary for the app that turns clipped web pages into personalizedEnglish study material. One canonical term per concept; use these exactly.## Language### Vocabulary**Wordbook**:A named collection of word entries. A **system wordbook** is preset and shared(e.g. CET4, CET6) and is read-only to learners; a **user wordbook** is createdand owned by a learner. Each learner has exactly one **default wordbook** thatreceives word-adds when none is chosen._Avoid_: word list, vocabulary book, deck, set.**Word entry**:One word inside a wordbook, optionally carrying example sentences._Avoid_: word item, vocab, term, lemma (a lemma is the matching result, not the entry).**Example sentence**:A sentence attached to a word entry, with an optional source URL._Avoid_: usage, sample, quote.**Highlight mode**:A per-learner setting on a wordbook that drives highlighting: **HIGHLIGHT**(highlight its words), **EXCLUDE** (never highlight them; wins over HIGHLIGHT),or **NORMAL** (no effect, e.g. the default wordbook). Set per learner, so ashared system wordbook can be HIGHLIGHT for one learner and NORMAL for another._Avoid_: include/exclude sets, whitelist/blacklist, allow/deny list.### Reading**Learning material**:A web page clipped into Markdown and stored in the app. It is a one-timesnapshot, never re-clipped from the source._Avoid_: material, article, document, doc, page, clip (the noun).**Clip**:The act of capturing a web page as a learning material via the browserextension. Verb only._Avoid_: import, scrape, save, capture.**Highlight**:The visual marking of a word in a learning material because its lemma is in aHIGHLIGHT-mode wordbook and not in any EXCLUDE-mode one. Matching is lemma-basedand case-insensitive (`Running` matches `run`)._Avoid_: mark, flag, emphasize.**Annotation**:A learner's note on a selected sentence in a learning material, with adescription and a color. Editable and deletable; not auto-re-anchored when thematerial text changes._Avoid_: note, comment, highlight (highlight is vocabulary marking, not a note),markup.### Sharing & Config**Share link**:A read-only, public, no-login URL to a learning material and its annotations. Alive view that reflects later edits._Avoid_: public link, share URL, permalink, snapshot link.**External dictionary template**:A learner-configured dictionary URL with a `{word}` placeholder, used to open aword in a third-party dictionary._Avoid_: dictionary URL, lookup template, dict link.## Flagged ambiguities- **Highlight** vs **Annotation**: both are visual on a material. "Highlight" is only the automatic vocabulary marking driven by wordbook highlight modes. A learner's colored note on a sentence is always an "annotation", never a "highlight".- **Clip** (verb, the action) vs **Learning material** (noun, the result). Never call the stored material a "clip".步骤四：把 IDEA 落盘到docs/idea/
把 idea 让 AI 落盘到docs/idea/ 下：
这里的README.md 中有对idea 类型简单说明和模板，所以 Agent 会格式化文档，这就是整个业务的开始。
步骤五：从 IDEA 到写 PRD
让 AI 根据：
docs/idea/idea-00001-english-learning-copilot.md写 PRD 并：
docs/prd/prd-00001-english-learning-copilot.mdPRD 的 front matter 里，parent 指向上游 idea：
---id: prd-00001-english-learning-copilottype: prdrole: mainstatus: activeparent: idea-00001-english-learning-copilot---步骤六：确定技术栈和项目形态
有了 Idea 和 PRD 后，就需要考虑技术栈了。这部分需要一定的技术沉淀、调研能力和判断力。
针对本文中这种工具向应用，能有可用的框架复用的就复用。用框架的好处就是有参考、可组合，劣势就是认知负担会重一些，需要学习框架。但是在 AI 时代，获取知识和学习比以前要容易很多。所以第一时间不考虑任何造轮子的事情，重要的是把东西做出来、用起来，后续迭代过程中，再考虑 enhance、replace 等，并且可以在已用框架的基础上借鉴一些实现方案，后续可以瘦身。我的经验是，先做加法再做减法。
本次选用的技术栈：
lucide-react icons, GSAP for landing-page and complex animations | |
Auth.js v5@auth/prisma-adapter; Google provider + Credentials provider;bcryptjs for password hashing | |
@hookform/resolvers) | |
THIRDPARTY.md | |
react-markdownremark-gfm +rehype-sanitize | |
wink-lemmatizer | |
@testing-library/react (unit/component), Playwright (E2E), Testcontainers PostgreSQL (integration) | |
步骤七：项目根目录工作流和规格文件适配当前项目
AI Native Project Template 的README.md 里有根据模板创建项目后需要自定义的说明，这些需要自定义的还是要改一下，需要根据实际项目、语言、框架等做出调整。最后封装成Makefile make 调用，目的是可以在本地随时让 Agent 启停中间件、运行测试、运行项目等。比如make dev 启动，make test 跑测试，make e2e 跑端到端测试等。
english-copilot 里，Makefile 的入口：
步骤八：写 Spec 和 User Story
按照 AI Native Project Template 定义的 Doc 模型：
spec:us = 1:nSpec 文件说明 Do What 和 Design，内联或者挂载docs/design 文件。模板中，使用EARS 描述系统视角需求项，使用GWT 编写验收细则，最后让 Agent 生成plan，后续根据这个plan 开始 coding。
english-copilot 里的 Demo
可以看到，需求和验收都结构化且具有唯一 ID，这样可以在任何地方进行 Link。
步骤九：Design Doc
小 spec 可以 inline design，但如果涉及跨多个功能或者比较大，就应该单独写一个 Design，另外，Design 甚至可以单独编写，后续再挂载，比如一些系统切面功能（限流、熔断、高并发、优化方案等）的预 Design。
比如 parent 指向 PRD/SPEC 等需要 Design 的地方
---id: design-00001-data-modeltype: designrole: mainstatus: activeparent: prd-00001-english-learning-copilot---步骤十：让 Agent 生成 Plan，再开始 Coding
编写代码之前根据 spec 生成 plan，如果 plan 太大可以拆分成单独的 task 文件，实践过程中觉得过度涉及了，没有拆过。
在这个 demo 里：
docs/plan/plan-00001-auth-accounts.mddocs/plan/plan-00002-wordbooks.mddocs/plan/plan-00003-materials.mdplan-00002-wordbooks.md 为例，内容如下：
步骤十一：实现、测试、验收、记录
有了 plan 之后，可以根据 plan 进行 coding ，通过测试门禁后更新结果。在 demo 里，plan-00002-wordbooks.md 最后的结果记录 是：
All tasks done. Domain lib (T1–T6) + server actions (T7) + UI (T8: `/wordbooks`,`/wordbooks/[id]`, `/settings`) + E2E (T9). Verified: `make build` + `make lint`clean; 34 unit/integration tests at 100% `src/lib` coverage; 4 E2E specs pass(auth + wordbooks: create → set mode → add word, and the `{word}` rejection).另外，关于验收，除了必须的人工验收，可以使用 Sub Agent 从文档出发去验证代码，去读 spec 的 EARS 和 GWT 去做验证，是否真的完成了，是否有对应的测试且测试通过了。
步骤十二：Issue Fix
如果出现 Issue，先落盘 Issue 文件，使用第一性原理 Debug 落盘现象、复现流程以及 Fix 方案后进行 Fix，这样可以做到 Issue 可观测、可跟踪、可审计。
比如一个简单的 Issue Demo：
demo 的文档结构
贴一个过程中的文档结构：
总结
• CONTEXT.md里有项目统一语言，并且 spec / design / code 使用的是同一套词。• docs/idea/里有最初产品想法，状态不是随便留在draft。• docs/prd/里有 PRD，并且parent指向 idea。• docs/spec/里有可实现的功能规格，并且parent指向 PRD。• docs/us/里有挂到 spec 下的 User Story，EARS 和 GWT 能互相对应。• 有跨功能设计时，放到 docs/design/，不要散在多个 spec 里。• 有真实取舍时，写 docs/decision/，不要只把选择写成结论。• docs/plan/里有实现计划，能看到任务、文件、需求映射和验收路径。• Makefile能启动、测试、构建、迁移数据库。• plan 结束后记录实际做完了什么、跑了什么验证。
另外这个 Demo 是在一个 Session 中完成的，让 AI 总结了一下 Session 中的人机分工如下图：
常见坑
•先写代码，后补文档：这样 Agent 一开始没有稳定上下文，后面补的文档也容易变成事后说明。 •不写 CONTEXT.md：短期看省时间，长期会让概念发散，尤其是中英文混用时，检索会漏。•PRD 和 spec 混在一起：PRD 说产品要什么，spec 说系统做什么，plan 说怎么做。混在一起后，Agent 很难判断自己该执行哪一层，所以 PRD 给人看，用来产出 spec，下游尽量不依赖 PRD。 •有取舍但不写 decision：可能就不记得当时为什么要这么做了，只剩个 pr 或者 commit。比如过几天就忘了为什么选 Auth.js、不选 Clerk；为什么先做 web app、不先做 extension。 •Makefile 没有稳定入口：每次都重新告诉 Agent 怎么启动、怎么测，会浪费上下文，也容易跑错命令。 •Plan 没有验收路径：Agent 写完了，但不知道要跑哪些测试，也不知道失败后该回到哪个需求。 •Outcome 不记录：实现完成后没有证据沉淀，后续 review 和 debug 都要重新考古。
后续
• 继续完善文档模板和工作流 • 后续打算多探索下关于验证的方法，目前通过覆盖率、变异测试可以提高单元测试的质量，但是在符合业务语义的测试用例生成中依然是不如意，还是需要大量的人力去写测试用例，另外涉及浏览器的 E2E测试的成本、环境等都是需要考虑的角度。总而言之，在 AI 时代，写代码去实现需求这件事变得成本不高了，工程上更多聚焦于怎么验收、怎么 Review、怎么提高效能和质量上了。• 这个英语学习助手 Demo 的 UI Design，按照经验，Claude Design 还是香，也可以使用 Open Design 但要用 Claude 模型，Codex 可以使用 image2生成图后转 UI 或者直接落地代码，但可修改性上不太够。
