AI编程新手如何用文档化工作流管理项目：从混乱到有序

1. 项目天条：为AI编程新手定制的“开发宪法”

如果你和我一样，是个对代码一知半解，但又想借助Cursor、Claude这些强大的AI编程工具来搞点事情的人，那你肯定遇到过这样的困境：今天让AI写个脚本，明天让它修个bug，后天再让它加个新功能。每次对话都像是开盲盒，AI要么理解错了你的意思，写出一堆跑不起来的代码；要么就是一次性给你生成几百行，看得你眼花缭乱，根本不知道从哪开始调试。项目做着做着就成了一团乱麻，文档没有，进度不清，最后只能推倒重来。

“MomoStone678/project-tenets-init”这个项目，就是我为了解决这个痛点，折腾了一个多月后总结出来的“笨办法”。它不是什么高深的框架，而是一套极其简单、强制的文档化工作流。你可以把它理解为给你的AI编程项目立下的“天条”或“宪法”。它的核心目标只有一个：让代码小白也能像专业开发者一样，有条不紊地、可持续地推进一个AI编程项目。

这套方法的核心，是强制性地在项目根目录创建几个关键的Markdown文档，并规定你每次给AI下指令时，都必须以一句固定的“咒语”开头。正是这句“咒语”和背后的文档体系，像交通规则一样，约束着AI的行为，让它从“天马行空的创意伙伴”变成“严谨可靠的执行工程师”。我自己用它搭配Cursor和相关的Agent技能，成功地把几个从零开始的小项目从想法变成了可用的工具，开发过程中的混乱感减少了至少八成。

2. 核心理念与设计思路拆解

2.1 为什么代码小白需要“天条”？

很多AI编程教程会教你各种华丽的Prompt技巧，但对于新手来说，最大的障碍往往不是“怎么让AI写出代码”，而是“怎么管理AI写出来的那一大堆东西”。缺乏编程经验意味着你缺乏对项目结构的直觉，也缺乏拆解复杂任务的能力。你给AI的指令往往是模糊的、一次性的，这直接导致了几个问题：

1. 上下文断裂：AI没有长期记忆，新开一个对话窗口，它就对之前的工作一无所知。你需要反复复述项目背景，效率极低。
2. 指令模糊导致偏差：你说“加个登录功能”，AI可能会生成一个完整但过于复杂的方案，或者一个过于简陋无法使用的方案，你需要来回纠正。
3. 缺乏测试与验证：AI生成的代码，你不敢直接运行，也不知道怎么测试。出了问题，排查起来如同大海捞针。
4. 项目资产混乱：代码、文档、测试脚本混在一起，过两天自己都忘了哪个文件是干什么的。

“项目天条”的思路，就是用最朴素的文档管理，来弥补经验和流程的缺失。它不教你写代码，而是教你如何“管理”写代码这个过程。

2.2 四级文档体系：构建项目的记忆骨架

这个项目的精髓，在于它创建的四层文档结构。这不像传统的软件工程文档那么复杂，每一层都有非常具体、单一的职责，且与你的操作强相关。

第一层：行动准则（项目天条.md）这是整个项目的“根本大法”。它定义了AI在面对不同类型任务时必须遵守的执行流程。比如，当AI判断你的指令是“开发一个新功能”时，它必须按照项目天条.md里规定的“功能开发流程”来工作：先分析需求、输出多个方案并评分、选择最优方案整合、分步骤实现、每一步进行验证。这份文档是你和AI之间的“契约”，确保了行为的一致性。它的查看频率是“每次任务”，这正是通过那句触发咒语来实现的。

第二层：状态快照（项目当前状态.md+常见问题排查.md）这相当于项目的短期记忆和“错题本”。

• 项目当前状态.md：记录当前项目的代码结构、已实现的功能、待办事项、已知的配置项等。它的目的是让AI在新对话中能快速“热启动”，理解项目进展到哪里了。但这里有个重要的实操心得：原作者也提到，不能完全依赖AI自动更新这个文件。我的经验是，在结束一个比较重要的开发阶段后，主动让AI帮你总结并更新这个文档，比如：“请根据我们刚才完成的工作，更新一下项目当前状态.md。”这样更可靠。
• 常见问题排查.md：记录开发过程中遇到的具体错误、警告及其解决方案。比如“运行main.py时出现ModuleNotFoundError: No module named ‘requests‘，解决方法：pip install requests”。这不仅能帮你积累经验，下次遇到同样问题AI也能直接从这里找到答案。它的查看频率也是“每次任务”，AI在遇到错误时会优先查阅这里。

第三层：战略蓝图（需求文档-V1.md）这是项目的长期目标。它不关心具体代码怎么写，而是清晰地定义这个项目要“做什么”。包括项目背景、核心功能列表、用户角色、非功能性要求（如性能、界面）等。在开始任何具体开发前，你应该和AI反复讨论、打磨这份文档，直到双方理解一致。它的查看频率是“主要开发阶段前”，用于对齐方向，防止跑偏。

第四层：战术手册（分步开发手册/目录下的文件）这是应对复杂任务的“分而治之”策略。当某个功能预估代码量会很大（比如超过300行）时，就不应该让AI一次性生成。而是创建一份分步开发手册，例如分步开发手册/用户登录模块.md，在里面将大功能拆解成一个个可独立验证的小步骤（Step 1: 创建用户模型；Step 2: 实现注册接口；Step 3: 实现登录逻辑…）。AI按照手册一步步开发，每完成一步就进行验证。这完美避开了AI的上下文长度限制，也让开发过程变得清晰可控。

2.3 意图分类与流程化：让AI成为标准工人

这套体系最巧妙的一点，是将你可能发出的所有指令，归纳为五种明确的“意图类型”。项目天条.md中会为每一种类型定义标准操作程序（SOP）。

通过这种分类和流程化，无论你发出什么指令，AI都被引导到一个结构化的处理路径上，大大减少了其自由发挥导致混乱的可能性。

3. 核心细节解析与实操要点

3.1 那句关键的“咒语”及其工作原理

整个体系运转的扳机，就是那句你必须养成的习惯：“根据项目天条.md 开展工作：”。

这不仅仅是一句提示词，这是一个强制的“上下文注入”指令。当你对Cursor或Claude说出这句话时，会发生以下几件事：

1. 指令重定向：AI会首先去读取项目天条.md文件的内容。这份文件的开头，很可能就写着“当用户以‘根据项目天条.md开展工作：’开头时，请遵循以下流程…”。
2. 意图识别：AI会根据你“：”后面的具体描述，对照天条里定义的五类意图，判断当前任务属于哪一类。
3. 流程激活：一旦意图匹配，AI就会激活对应的标准流程（SOP），并开始按步骤执行，比如先要求澄清需求，或者先去检查项目当前状态.md。

注意：这个习惯需要刻意培养。初期你可能会忘记说，结果就是AI又回到了那种“自由散漫”的响应模式。我的经验是，把这句话写在便签上贴在屏幕旁边，直到它变成肌肉记忆。

3.2 文件夹结构设计的巧思

生成的三个文件夹看似简单，实则各有深意：

• 文档/：所有Markdown文档的“家”。集中存放的好处是，当你需要快速查找或向AI引用某个文档时，路径非常清晰（./文档/项目天条.md）。这也物理上区分了“文档”和“代码”，避免了混乱。
• 分步开发手册/：这个文件夹是动态创建的，只在需要时（预估代码>300行）才由AI创建。这体现了“按需创建”的原则，避免项目一开始就有一堆空文件夹。里面的每个.md文件都是一个具体功能的“作战地图”。
• 手动运行/：这是专门为“测试”准备的沙盒。AI生成的临时测试脚本、需要你手动运行验证的代码片段，都应该放在这里。例如，AI可能会说：“我已经在手动运行/test_login.py中写了一个测试脚本，请您运行它并告诉我结果。” 这样做的好处是，测试代码不会污染主项目代码库，验证完毕后可以轻松删除，保持项目根目录的整洁。

3.3 如何与AI协作维护文档

文档不是生成了就一劳永逸的，它需要持续更新。你应该把AI当作你的文档协作者。

• 更新状态：在完成一个里程碑后，主动指令AI：“请根据我们刚刚完成的用户注册功能，更新项目当前状态.md，重点描述新增的/api/register接口和User模型。”
• 记录问题：每当AI帮你解决一个bug，立即让它归档：“请将刚才遇到的数据库连接超时问题及其解决方案，记录到常见问题排查.md中。”
• 修正需求：当需求变更时，不要直接开始改代码，而是先更新蓝图：“首先，请将需求文档-V1.md中的‘文件上传’部分修改为‘支持图片上传并生成缩略图预览’。”

通过给AI分派这些文档任务，你不仅减轻了自己的负担，也让整个项目的历史和逻辑变得可追溯、可理解。

4. 完整实操流程与核心环节实现

下面，我将以一个具体的场景为例，展示如何从零开始使用这套“项目天条”体系。

场景：我想开发一个简单的“个人书签管理器”，用于保存和分类我收藏的网页链接。

4.1 第一步：项目初始化

1. 安装与触发：在Cursor中，确保已安装“Project Tenets Init”相关的Agent Skill（具体安装方法取决于该技能的发布方式，通常在Cursor的Settings -> Agent Skills中管理）。然后，在你的项目空目录中，打开Cursor Chat，输入：“初始化项目”。
2. AI执行：AI技能被触发，它会：
   • 检查当前目录是否已有项目天条.md（避免覆盖）。
   • 创建文档/、分步开发手册/、手动运行/三个文件夹。
   • 从模板复制，生成四个核心Markdown文档到文档/文件夹下。
3. 生成结果：你的项目目录会立刻变得规整，拥有了基础骨架。此时，文档/项目天条.md等文件内容还是模板化的，需要你填入具体内容。

4.2 第二步：定义需求（填充Level 3文档）

接下来，不要急着写代码。先和AI一起明确“做什么”。

1. 打开文档/需求文档-V1.md，你会看到一个模板，里面有待填写的章节，如项目概述、用户故事、功能列表等。
2. 对AI说：“根据项目天条.md 开展工作：我们来一起完善‘个人书签管理器’的需求文档。”
3. AI的响应：AI会引导你进行对话，逐步填充这个文档。例如：
   • AI：“好的，我们先从项目概述开始。您能简单描述一下这个书签管理器要解决什么问题吗？”
   • 你：“我经常收藏很多文章链接，但浏览器书签太乱了，想按主题分类，并且能添加备注。”
   • AI：“明白。那么核心用户（您自己）的主要目标是什么？我们可以列出用户故事。”
   • …（经过几轮对话）
4. 最终产出：一份详实的需求文档-V1.md，内容可能包括：
   • 核心功能：添加书签（URL、标题、分类、备注）、按分类查看、搜索书签、导出书签。
   • 技术选型：使用Python的Flask框架（简单）、SQLite数据库（轻量）、纯HTML/CSS前端（暂时）。
   • 非功能需求：数据本地存储、界面简洁。

4.3 第三步：开发第一个功能（应用Level 1和Level 4）

假设我们从“添加书签”这个核心功能开始。由于这是一个包含前后端的完整功能，代码量可能不小。

1. 启动开发：你对AI说：“根据项目天条.md 开展工作：现在开始开发‘添加书签’功能。”
2. AI的标准化响应：
   • AI：“收到。识别为【开发功能】意图。首先，我将分析‘添加书签’功能的需求。根据需求文档-V1.md，这需要前后端协作。预估代码量将超过300行，因此我将先创建分步开发手册。”
   • AI：“已在分步开发手册/目录下创建添加书签功能.md。我将按照以下步骤进行：
     • Step 1: 设计数据库模型（Bookmark表）。
     • Step 2: 创建Flask后端应用结构。
     • Step 3: 实现后端添加书签的API接口 (POST /api/bookmarks)。
     • Step 4: 创建前端简单的表单页面。
     • Step 5: 使用JavaScript将表单数据提交到后端API。
     • 每一步完成后，我会提供验证方法。现在我们开始Step 1...”
3. 分步执行与验证：AI会严格按照手册推进。例如，完成Step 1后，它可能会说：“Step 1已完成，已创建models.py文件定义了Bookmark模型。请在手动运行/文件夹中运行我生成的test_db.py脚本，以确认数据库表能成功创建。” 你运行脚本，看到成功提示后，再告诉AI：“数据库测试通过，请继续Step 2。”
4. 状态同步：在开发间隙或完成功能后，指令AI：“请更新项目当前状态.md，记录‘添加书签’功能已实现，包括新增的models.py、app.py中的/api/bookmarksPOST接口，以及templates/add_bookmark.html前端页面。”

4.4 第四步：遇到问题与修复（应用Level 2文档）

在开发Step 3（后端接口）时，你运行测试，遇到了一个错误：sqlalchemy.exc.OperationalError: (sqlite3.OperationalError) no such table: bookmark。

1. 求助AI：“根据项目天条.md 开展工作：运行测试时出现错误：sqlalchemy.exc.OperationalError: (sqlite3.OperationalError) no such table: bookmark。”
2. AI的标准化排查：
   • AI：“识别为【修 bug】意图。首先检查常见问题排查.md...未找到相同错误。”
   • AI：“分析错误：提示‘bookmark’表不存在。原因可能是数据库未初始化或模型定义后未创建表。请检查是否在创建Flask app后，运行了db.create_all()来创建所有表？”
   • AI：“建议解决方案：在app.py的初始化部分，确保在导入模型后，在应用上下文中调用db.create_all()。我已修改代码，请重新运行测试。”
   • AI：“同时，我将此错误‘SQLite表不存在’及解决方案记录到常见问题排查.md中，以备后续查阅。”
3. 问题解决与知识沉淀：你按照AI的建议修改并重新运行，问题解决。同时，常见问题排查.md里多了一条记录，下次任何对话中的AI再遇到类似问题，都能直接引用这个解决方案。

通过以上四个步骤的循环，无论项目多复杂，你都能在一个清晰、可控的框架内推进。AI的行为变得可预测，项目的进度和知识变得可积累。

5. 常见问题与排查技巧实录

在实际使用这套方法一个多月后，我踩过一些坑，也总结出一些让体验更顺畅的技巧。

5.1 关于“项目当前状态.md”的信任问题

这是原作者也提到的一个关键点。你不能100%相信AI会自动、准确地更新状态文档。我的策略是：

• 关键节点手动触发：在完成一个相对独立、重要的模块后，主动命令AI进行总结和更新。例如：“请总结一下我们刚刚完成的用户认证模块，并更新到项目当前状态.md，包括新增的文件、路由、以及重要的配置项。”
• 内容结构化：在项目天条.md的模板里，就可以规定项目当前状态.md必须包含的章节，如“项目结构”、“已实现功能”、“待办事项”、“环境配置”、“运行说明”等。这样AI在更新时就有据可依，不容易遗漏。
• 定期回顾：每天或每段开发开始前，快速浏览一下项目当前状态.md，确认其描述与实际情况相符。如有偏差，立即让AI修正。

5.2 AI不遵守流程怎么办？

有时AI可能会“偷懒”或“自作聪明”，跳过某些步骤（比如不输出多个方案就直接开发）。这时需要你进行“强约束”：

• 明确引用：在指令中直接点明需要遵守的具体流程。例如：“根据项目天条.md 开展工作，请严格按照‘开发功能’意图的流程，先为我提供三个不同的技术方案并评分，我们再决定。”
• 检查与纠正：如果AI直接开始写代码，打断它：“停。你还没有按照天条要求进行方案设计和评分。请先执行这一步。”
• 强化训练：对于你常用的AI（如Cursor的特定模式），在它正确执行几次后，它会更好地学习这个模式。坚持使用固定的触发词和流程，本身就是对AI的一种训练。

5.3 如何管理“分步开发手册”的复杂度？

当一个项目有多个大功能时，分步开发手册/目录下可能会有很多文件。

• 命名规范：让AI使用清晰的功能名命名手册文件，如分步开发手册/用户认证模块.md、分步开发手册/数据导出功能.md。
• 主目录索引：可以在分步开发手册/目录下创建一个README.md或_index.md文件，作为所有手册的索引，记录每个手册对应的功能、当前进度（如“Step 3/5进行中”）。
• 归档与清理：当一个功能完全开发并测试通过后，可以将对应的手册文件移到一个分步开发手册/已完成/子目录中，或者直接在文件开头标记[状态：已完成]。保持活动手册的清晰。

5.4 这套方法适用于所有AI编程工具吗？

核心思想是通用的，但具体实现依赖于AI工具的能力。

• Cursor：是最佳搭档，因为它对本地文件系统的读写能力很强，能完美支持这种基于文档的交互。其Agent Skills机制也能很好地封装“初始化”这个动作。
• Claude Desktop / ChatGPT (带代码解释器或文件上传)：也可以使用，但体验会稍打折扣。你需要手动创建文档结构和模板，然后在每次对话时手动上传或提示AI关注这些文档。流程的自动化程度不如Cursor。
• 关键依赖：无论用什么工具，AI都需要具备长期对话上下文和理解/生成Markdown的能力。如果AI的上下文很短，或者无法很好地处理多文档协作，这套方法的效果会减弱。

5.5 对代码小白真正的价值在哪里？

我认为最大的价值是建立了信心和控制感。以前面对AI生成的一大坨代码是恐惧的，现在你知道，再大的项目也可以被拆解到分步开发手册里的一行行步骤；以前出了问题无从下手，现在可以去常见问题排查.md里找找，或者让AI按“修bug”流程处理；以前换了个对话AI就失忆了，现在有项目当前状态.md作为交接单。你从一个被动的指令发出者，变成了一个项目管理的“导演”，AI则是你严格遵循剧本的“演员”。这种角色的转变，能让你真正享受到AI编程的乐趣，而不是挫败感。

最后，我想说，这套“项目天条”体系不是一个僵化的教条。它提供的是一种结构和纪律。你可以根据自己的项目特点和习惯，去调整那些文档的模板，增加或合并某些流程。但核心——用文档驱动流程，用流程约束AI——这个原则，对于任何想用AI严肃地完成一个项目的代码小白来说，都是一盏值得信赖的指路灯。