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的指令往往是模糊的、一次性的这直接导致了几个问题上下文断裂AI没有长期记忆新开一个对话窗口它就对之前的工作一无所知。你需要反复复述项目背景效率极低。指令模糊导致偏差你说“加个登录功能”AI可能会生成一个完整但过于复杂的方案或者一个过于简陋无法使用的方案你需要来回纠正。缺乏测试与验证AI生成的代码你不敢直接运行也不知道怎么测试。出了问题排查起来如同大海捞针。项目资产混乱代码、文档、测试脚本混在一起过两天自己都忘了哪个文件是干什么的。“项目天条”的思路就是用最朴素的文档管理来弥补经验和流程的缺失。它不教你写代码而是教你如何“管理”写代码这个过程。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的标准流程示例制定计划“为项目制定一个开发计划”1. 分析需求文档-V1.md。2. 将需求拆解为功能模块。3. 评估复杂度并排序。4. 输出甘特图或任务列表。连续开发“继续开发用户管理模块”1. 阅读项目当前状态.md和分步开发手册/用户管理模块.md。2. 定位到上次中断的步骤。3. 继续执行后续步骤。4. 更新状态文档。修 Bug“运行时报错了错误是…”1. 首先检查常见问题排查.md是否有现成方案。2. 分析错误日志定位问题代码。3. 解释错误原因并提供修复方案。4. 将新问题及解决方案归档到排查文档。开发功能“添加一个文件上传功能”1. 分析需求并输出至少3个技术方案从复杂度、可维护性、性能等方面评分。2. 与你讨论并确定最终方案。3. 如代码量大创建分步开发手册。4. 按步骤实现并测试。需求处理“我们改一下需求上传后要能预览图片”1. 更新需求文档-V1.md。2. 评估对现有代码和计划的影响。3. 制定需求变更实施计划。通过这种分类和流程化无论你发出什么指令AI都被引导到一个结构化的处理路径上大大减少了其自由发挥导致混乱的可能性。3. 核心细节解析与实操要点3.1 那句关键的“咒语”及其工作原理整个体系运转的扳机就是那句你必须养成的习惯“根据项目天条.md 开展工作”。这不仅仅是一句提示词这是一个强制的“上下文注入”指令。当你对Cursor或Claude说出这句话时会发生以下几件事指令重定向AI会首先去读取项目天条.md文件的内容。这份文件的开头很可能就写着“当用户以‘根据项目天条.md开展工作’开头时请遵循以下流程…”。意图识别AI会根据你“”后面的具体描述对照天条里定义的五类意图判断当前任务属于哪一类。流程激活一旦意图匹配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 第一步项目初始化安装与触发在Cursor中确保已安装“Project Tenets Init”相关的Agent Skill具体安装方法取决于该技能的发布方式通常在Cursor的Settings - Agent Skills中管理。然后在你的项目空目录中打开Cursor Chat输入“初始化项目”。AI执行AI技能被触发它会检查当前目录是否已有项目天条.md避免覆盖。创建文档/、分步开发手册/、手动运行/三个文件夹。从模板复制生成四个核心Markdown文档到文档/文件夹下。生成结果你的项目目录会立刻变得规整拥有了基础骨架。此时文档/项目天条.md等文件内容还是模板化的需要你填入具体内容。4.2 第二步定义需求填充Level 3文档接下来不要急着写代码。先和AI一起明确“做什么”。打开文档/需求文档-V1.md你会看到一个模板里面有待填写的章节如项目概述、用户故事、功能列表等。对AI说“根据项目天条.md 开展工作我们来一起完善‘个人书签管理器’的需求文档。”AI的响应AI会引导你进行对话逐步填充这个文档。例如AI“好的我们先从项目概述开始。您能简单描述一下这个书签管理器要解决什么问题吗”你“我经常收藏很多文章链接但浏览器书签太乱了想按主题分类并且能添加备注。”AI“明白。那么核心用户您自己的主要目标是什么我们可以列出用户故事。”…经过几轮对话最终产出一份详实的需求文档-V1.md内容可能包括核心功能添加书签URL、标题、分类、备注、按分类查看、搜索书签、导出书签。技术选型使用Python的Flask框架简单、SQLite数据库轻量、纯HTML/CSS前端暂时。非功能需求数据本地存储、界面简洁。4.3 第三步开发第一个功能应用Level 1和Level 4假设我们从“添加书签”这个核心功能开始。由于这是一个包含前后端的完整功能代码量可能不小。启动开发你对AI说“根据项目天条.md 开展工作现在开始开发‘添加书签’功能。”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...”分步执行与验证AI会严格按照手册推进。例如完成Step 1后它可能会说“Step 1已完成已创建models.py文件定义了Bookmark模型。请在手动运行/文件夹中运行我生成的test_db.py脚本以确认数据库表能成功创建。” 你运行脚本看到成功提示后再告诉AI“数据库测试通过请继续Step 2。”状态同步在开发间隙或完成功能后指令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。求助AI“根据项目天条.md 开展工作运行测试时出现错误sqlalchemy.exc.OperationalError: (sqlite3.OperationalError) no such table: bookmark。”AI的标准化排查AI“识别为【修 bug】意图。首先检查常见问题排查.md...未找到相同错误。”AI“分析错误提示‘bookmark’表不存在。原因可能是数据库未初始化或模型定义后未创建表。请检查是否在创建Flask app后运行了db.create_all()来创建所有表”AI“建议解决方案在app.py的初始化部分确保在导入模型后在应用上下文中调用db.create_all()。我已修改代码请重新运行测试。”AI“同时我将此错误‘SQLite表不存在’及解决方案记录到常见问题排查.md中以备后续查阅。”问题解决与知识沉淀你按照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严肃地完成一个项目的代码小白来说都是一盏值得信赖的指路灯。