1. 一个月从零到四项目我的AI编程真实路径复盘先说结论一个月四个项目从完全零基础到能跑通完整开发流程靠的不是天赋而是一套被逼出来的“纪律系统”。这套系统后来被我做成了一个agent项目纪律工具专门用来解决AI编程过程中反复出现的混乱、遗忘和低效问题。我最初的状态是能看懂一点Python但没写过完整项目前端只会改改HTML后端概念停留在“听说过”。用AI编程工具写代码一开始确实爽——你说需求它给代码复制粘贴就能跑。但很快问题就来了项目一多上下文丢失、代码风格混乱、依赖冲突、重复造轮子、忘记之前踩过的坑。一个月做了四个项目之后我发现自己80%的时间不是在写新功能而是在重复解决已经解决过的问题。这就是“项目纪律系统”的由来。它不是某个具体的技术框架而是一套约束AI编程行为、管理项目上下文、沉淀经验教训的规则集合。我把它做成了一个agent让它在每次编程会话开始时自动加载项目纪律在开发过程中实时提醒在会话结束时自动归档经验。这篇文章适合谁看如果你是零基础想用AI编程做项目的人或者已经用AI写了一些代码但感觉越来越乱的人再或者你对agent开发、AI编程提示词、项目纪律系统这些概念感兴趣那接下来的内容应该能帮你省下不少试错时间。我会从整体设计思路讲起然后拆解核心细节和实操要点接着完整还原四个项目的实操过程最后把踩过的坑和排查技巧整理成速查表。全程不藏私能直接抄的配置和提示词我都会给出来。2. 项目纪律系统的整体设计与思路拆解2.1 为什么零基础用AI编程更需要“纪律”零基础的人用AI编程最大的误区是以为“AI什么都能搞定”。实际上AI编程工具的能力边界非常清晰它擅长根据明确指令生成代码片段擅长解释报错擅长在给定上下文中做局部修改。但它不擅长记住你三天前说过的项目规范不擅长主动发现你的代码风格已经漂移更不擅长在你忘记某个依赖版本时自动帮你回溯。我第一个项目是一个简单的命令行待办事项工具用Python写的。当时觉得很简单AI给的代码直接跑通了。第二个项目是一个天气查询小工具开始引入第三方API。第三个项目是一个本地文件整理脚本。第四个项目是一个带简单前端的个人书签管理器。四个项目都不大但每一个都让我踩了不同的坑。第一个坑上下文丢失。每次新开一个AI编程会话我都要重新解释项目结构、依赖、命名规范。第二个坑代码风格漂移。同一个项目里AI有时用驼峰命名有时用下划线有时用类有时用函数。第三个坑依赖冲突。第三个项目用了某个库的2.0版本第四个项目想复用代码时发现那个库已经升到3.0API全变了。第四个坑经验遗忘。我在第二个项目里已经解决过API请求超时的问题到第四个项目又花了一个小时重新查。这些坑单独看都不致命但叠加起来一个月下来浪费的时间至少占30%。所以我开始想能不能把“项目纪律”这个概念具象化做成一个agent让它来替我记住这些事2.2 项目纪律系统的核心设计原则我给自己定了三条原则后来也成了这个agent的设计基础。第一条纪律必须可执行不能只是文档。写一个Markdown文件放在那里叫“项目规范”没人会看AI也不会主动读。纪律必须变成agent每次会话都会加载的上下文变成具体的检查项和提醒。第二条纪律必须轻量不能拖慢开发速度。如果每次写代码前都要填一堆表单、走一堆流程那还不如不用。我的做法是把纪律压缩成几个关键字段项目名称、技术栈、依赖版本、命名规范、已知问题、上次会话进度。这些字段用YAML格式存储agent启动时自动读取。第三条纪律必须能沉淀不能每次从零开始。每完成一个功能或解决一个问题agent要自动把经验追加到项目的“经验库”里。下次遇到类似问题agent先查经验库再决定是否需要重新推理。基于这三条原则我把项目纪律系统设计成了一个三层结构最底层是项目元数据YAML文件中间层是纪律检查规则提示词模板最上层是agent执行逻辑会话启动、过程提醒、结束归档。2.3 技术选型为什么选轻量方案而不是重型框架市面上agent框架很多有LangChain、AutoGPT、CrewAI等等。我试过其中几个最后放弃了。原因很简单对于个人开发者、零基础、小项目来说重型框架的抽象层太厚调试成本太高。你花在理解框架上的时间可能比写业务代码还多。我最终选的是一个极简方案用Python写一个命令行脚本调用大模型的API配合本地文件存储。核心逻辑不超过300行代码。这样做的好处是完全可控出问题能直接定位到具体行不依赖任何框架的版本更新可以随时根据需求修改。具体来说我用了以下组件大模型API用于生成代码、解释报错、检查纪律。我试过几个不同的API最后选了一个响应速度快、代码生成质量稳定的。这里不具体点名因为不同时期可用的API不同你可以根据自己的情况选择。本地文件存储用YAML存项目元数据用Markdown存经验库用JSON存会话记录。不引入数据库因为小项目不需要。命令行交互用Python的argparse模块做参数解析用rich库做终端输出美化。rich是可选的不用也能跑。Git集成用git worktree来管理不同项目的分支避免切换项目时污染工作区。这个后面会详细讲。这个选型逻辑的核心是每一层都要能单独替换每一层都要能单独调试。如果你用了一个大框架某一层出问题你可能要翻遍框架文档才能找到原因。而用自己的脚本出问题直接看代码就行。2.4 四个项目的整体规划与纪律系统迭代四个项目不是随便选的它们构成了一个难度递进的序列项目一纯本地、无依赖、单文件。目的是熟悉AI编程的基本流程建立最初的纪律字段。项目二引入外部API、需要处理网络请求和错误。目的是测试纪律系统在依赖管理上的表现。项目三涉及文件系统操作、需要处理路径和权限。目的是测试纪律系统在环境差异上的表现。项目四带前端、需要前后端联调。目的是测试纪律系统在跨技术栈协作上的表现。每做完一个项目我都会回顾纪律系统哪里不够用然后迭代。项目一之后我加了“依赖版本锁定”字段。项目二之后我加了“错误处理模板”字段。项目三之后我加了“环境检查清单”。项目四之后我加了“跨栈接口约定”字段。到第四个项目结束时这个纪律系统已经从一个简单的YAML文件变成了一个包含启动检查、过程提醒、结束归档三个阶段的完整agent。它不能帮你写代码但它能让你写代码的过程少很多混乱。3. 核心细节解析与实操要点3.1 项目元数据文件的设计与字段说明项目元数据是整个纪律系统的基石。它用YAML格式存储放在每个项目的根目录下文件名固定为.project-discipline.yaml。agent每次启动时第一件事就是读取这个文件。我最终定下来的字段如下project_name: bookmark-manager tech_stack: - python: 3.11 - flask: 2.3.2 - sqlite: 3 dependencies: - requests2.31.0 - beautifulsoup44.12.2 naming_convention: variables: snake_case classes: PascalCase files: kebab-case known_issues: - Flask debug mode 下 SQLite 连接偶尔报锁 - 前端 fetch 请求需要手动处理 CORS last_session: date: 2024-01-15 progress: 完成了书签列表页的渲染详情页还没做 next_step: 实现书签详情页的 API 和前端 experience_refs: - api-timeout-handling - sqlite-lock-avoidance每个字段都有明确的用途。tech_stack和dependencies用于在AI生成代码时提供准确的版本上下文避免它给出过时的API用法。naming_convention用于在代码生成后做自动检查如果AI用了不一致的命名agent会提醒。known_issues是最有价值的字段它记录了当前项目已知但未解决的问题避免AI重复踩坑。last_session用于恢复上下文让你不用每次重新解释进度。experience_refs指向经验库中的具体条目方便快速查阅。注意known_issues字段不要写得太长。我的经验是每个项目不超过5条只记录真正影响开发的问题。写太多会变成噪音AI反而抓不住重点。3.2 纪律检查提示词模板的编写技巧提示词是agent和AI模型之间的接口。我试过很多种写法最后发现最有效的是“角色上下文检查项输出格式”的四段式结构。以代码生成后的纪律检查为例我的提示词模板是这样的你是一个项目纪律检查员。当前项目的纪律要求如下 技术栈{tech_stack} 依赖版本{dependencies} 命名规范{naming_convention} 已知问题{known_issues} 请检查以下代码是否符合纪律要求 {code} 检查项 1. 是否使用了未在依赖列表中声明的库 2. 变量、类、文件的命名是否符合规范 3. 是否触发了已知问题中的任何一条 4. 是否有明显的错误处理缺失 输出格式 - 如果全部通过输出 PASS - 如果有问题逐条列出问题类型、具体位置、修改建议这个模板的关键在于检查项要具体输出格式要固定。如果你只说“检查代码质量”AI会给你一堆泛泛而谈的建议。但如果你说“检查是否使用了未声明的库”AI就会去对比import语句和依赖列表。另一个技巧是把known_issues作为检查项的一部分。比如已知问题是“SQLite在debug模式下会锁”那AI在检查代码时就会特别注意数据库连接的部分。这比事后手动排查高效得多。3.3 经验库的自动归档机制经验库是纪律系统的记忆。每次会话结束agent会自动把本次会话中解决的问题、发现的技巧、遇到的坑整理成一条经验记录追加到经验库文件中。经验记录的格式我设计得很简单## api-timeout-handling - 日期2024-01-10 - 项目weather-query - 问题调用外部API时偶尔超时导致程序卡死 - 解决设置timeout10并捕获requests.exceptions.Timeout超时后重试一次 - 代码片段 python try: resp requests.get(url, timeout10) except requests.exceptions.Timeout: resp requests.get(url, timeout10)备注重试一次就够了不要无限重试否则会拖慢整体响应这个格式的好处是问题、解决、代码片段、备注四要素齐全下次遇到类似问题直接搜关键词就能找到。而且代码片段可以直接复制不用重新推理。 自动归档的实现方式是在会话结束时agent把本次会话的对话记录发给AI模型让模型提取出“问题-解决”对然后按照上面的格式生成记录。我试过让模型自动判断哪些内容值得归档效果还不错但偶尔会漏掉一些细节。所以我的做法是自动归档后我会快速扫一眼手动补充遗漏的部分。 提示经验库文件不要太大。我的经验是每个项目一个经验库文件超过50条记录就考虑拆分或归档。太大的文件会让AI在检索时变慢而且容易抓错重点。 ### 3.4 Git worktree在AI编程中的实际用法 git worktree是我在第三个项目时才开始用的用了之后再也回不去了。它的作用是允许你在同一个仓库的不同分支上同时拥有多个工作目录。对于AI编程来说这意味着你可以为每个项目或每个功能开一个独立的worktree互不干扰。 具体操作很简单 bash # 在主仓库目录下创建一个新的worktree git worktree add ../project-b-feature-a feature-a # 进入新的worktree目录 cd ../project-b-feature-a # 在这里用AI编程不会影响主仓库的工作区为什么这对AI编程特别有用因为AI编程经常需要试错。你让AI生成一段代码跑一下发现不行回滚再试。如果你在主工作区做这些操作很容易把其他文件的修改也带进去。而用worktree每个实验都在独立目录里回滚就是删掉整个目录干净利落。另一个好处是你可以同时开多个AI会话每个会话对应一个worktree互不干扰。比如一个会话在改前端一个会话在改后端两个worktree同时跑效率翻倍。注意worktree目录不要放在主仓库内部否则git会把它当成未跟踪文件。我一般放在主仓库的同级目录下用../前缀。3.5 多agent协作的边界与纪律约定到第四个项目时我开始尝试多agent协作。具体来说就是同时开两个AI会话一个负责前端一个负责后端。两个agent通过一个共享的接口约定文件来协作。接口约定文件我命名为.api-contract.yaml放在项目根目录。内容大致如下endpoints: - path: /api/bookmarks method: GET response: - id: integer - title: string - url: string - path: /api/bookmarks method: POST request: - title: string - url: string response: - id: integer前端agent和后端agent都读取这个文件按照约定生成代码。前端agent知道GET请求会返回什么结构后端agent知道POST请求需要接收什么字段。这样即使两个agent不直接通信也能保证接口对齐。但多agent协作也有纪律要求。我的经验是接口约定文件一旦确定就不能单方面修改。如果前端agent觉得需要加一个字段它必须先修改约定文件然后通知后端agent重新读取。这个“通知”目前是我手动做的因为自动通知需要额外的消息队列对于小项目来说太重了。另一个纪律是每个agent只能修改自己负责的目录。前端agent只能改frontend/目录后端agent只能改backend/目录。共享的约定文件只能由我手动修改。这样可以避免两个agent同时改同一个文件导致冲突。4. 四个项目的实操过程与核心环节实现4.1 项目一命令行待办工具——建立最初的纪律字段项目一的目标很简单做一个命令行待办工具支持添加、删除、列出待办事项。数据存在本地JSON文件里。我用的AI编程工具是一个支持对话式编程的编辑器。第一次会话我直接说“帮我写一个Python命令行待办工具支持add、remove、list三个命令数据存JSON。”AI很快给出了代码大概50行能跑。但我发现几个问题变量命名一会儿用todo_list一会儿用todos错误处理几乎没有如果JSON文件不存在就直接报错没有帮助信息用户不知道有哪些命令。这些问题都不大但让我意识到如果每次都要手动检查这些效率太低。于是我开始写第一个纪律文件。当时还很简单就是一个Markdown文件里面写了三条变量命名统一用snake_case所有文件操作必须捕获异常每个命令必须有help文本然后我把这个文件的内容复制到每次AI会话的开头作为上下文。效果立竿见影AI生成的代码开始遵守这些规则我不用再手动改了。项目一结束后我把这个Markdown文件升级成了YAML格式加了tech_stack和dependencies字段。这就是纪律系统的雏形。实操心得项目一不要追求功能完整重点是跑通“AI生成-检查-修正”的循环。我当时的待办工具只用了半天就做完了但花了一天时间在调整纪律文件上。这个时间投入是值得的后面三个项目都受益了。4.2 项目二天气查询工具——依赖管理与错误处理项目二的目标是做一个天气查询工具调用外部API获取天气数据支持按城市查询。这个项目让我踩了第一个大坑依赖版本冲突。AI生成的代码用了requests库但没有指定版本。我本地装的是2.28AI生成的代码里用了一个2.31才有的参数跑起来直接报错。我花了半小时才定位到是版本问题。于是我在纪律文件里加了dependencies字段明确锁定版本dependencies: - requests2.31.0然后每次AI生成代码后agent会自动检查import语句如果发现导入了未声明的库就提醒我。第二个坑是错误处理。天气API偶尔会超时AI生成的代码没有处理超时程序直接卡死。我在纪律文件里加了“错误处理模板”try: # 网络请求代码 except requests.exceptions.Timeout: # 超时处理 except requests.exceptions.RequestException as e: # 其他请求错误这个模板成了后续所有涉及网络请求的项目的标配。项目二结束后我把经验库的自动归档机制加上了。每次会话结束agent会把本次解决的问题整理成经验记录。比如“API超时处理”这条经验后来在项目四里直接复用省了一个小时。注意依赖版本锁定不要锁太死。我一开始用锁定精确版本后来发现有些库的安全更新无法自动获取。现在的做法是主要依赖用锁定次要依赖用加手动检查。4.3 项目三本地文件整理脚本——环境差异与路径处理项目三的目标是写一个脚本自动整理下载目录里的文件按类型分到不同子目录。这个项目让我遇到了环境差异问题。我在自己的电脑上跑得好好的换到另一台电脑上就报错。原因是路径分隔符不同Windows用反斜杠Linux用正斜杠。AI生成的代码用了硬编码的路径分隔符。解决方法是在纪律文件里加“环境检查清单”要求所有路径操作必须用os.path.join或pathlib。同时agent在代码生成后会检查是否有硬编码的路径分隔符。另一个问题是文件权限。整理脚本需要移动文件如果目标目录没有写权限就会报错。AI生成的代码没有处理这个。我在纪律文件里加了“权限检查”要求所有文件操作前先检查目标目录是否可写。项目三还让我开始用git worktree。因为文件整理脚本需要反复测试每次测试都会移动文件如果直接在项目目录里跑很容易把项目文件也移走。用worktree后我在独立的测试目录里跑脚本不影响主工作区。实操心得环境差异问题在AI编程里特别常见因为AI模型训练时看到的代码来自不同平台它不知道你的运行环境。解决办法是在纪律文件里明确写清楚目标环境比如“本项目的所有代码必须在Windows 10和Ubuntu 22.04上都能运行”。4.4 项目四个人书签管理器——前后端联调与多agent协作项目四是最复杂的一个一个带前端的个人书签管理器后端用Flask前端用原生HTMLJavaScript数据存SQLite。这个项目让我第一次尝试多agent协作。我开了两个AI会话一个负责后端API一个负责前端页面。两个agent通过.api-contract.yaml文件来约定接口。后端agent的任务是实现/api/bookmarks的GET和POST接口返回JSON格式的书签列表。前端agent的任务是实现书签列表的渲染和添加书签的表单。协作的关键是接口约定文件。我先把接口定义好然后两个agent分别读取。后端agent生成的代码返回的JSON结构和前端agent期望的结构完全一致。联调时一次通过没有出现字段名不匹配的问题。但多agent协作也有坑。前端agent在生成代码时自作主张加了一个“删除书签”的按钮但后端agent没有实现对应的DELETE接口。结果点击删除按钮时前端报404错误。我后来在纪律文件里加了“接口变更必须同步”的规则任何agent如果觉得需要新增接口必须先修改约定文件然后由我手动通知另一个agent。另一个坑是SQLite的锁问题。Flask在debug模式下会启动两个进程同时访问SQLite会导致锁冲突。AI生成的代码没有处理这个。我在经验库里记录了这个问题并加了解决方案在debug模式下SQLite连接使用check_same_threadFalse并设置timeout10。项目四结束后纪律系统已经包含了启动检查、过程提醒、结束归档三个完整阶段。我把它打包成了一个Python脚本放在GitHub上后来还加了一个简单的命令行界面方便在其他项目里复用。提示多agent协作时接口约定文件要尽量详细。不要只写字段名还要写字段类型、是否必填、默认值。我一开始只写了字段名结果前端agent把数字类型的id当成了字符串处理导致排序出错。5. 常见问题与排查技巧实录5.1 AI编程中上下文丢失的排查与解决上下文丢失是AI编程最常见的问题。表现是AI生成的代码和你之前定义的规范不一致或者AI忘记了之前已经讨论过的项目结构。排查思路先检查纪律文件是否被正确加载。我遇到过几次agent启动时没有读取.project-discipline.yaml原因是文件路径写错了。解决方法是在agent启动时加一个检查如果纪律文件不存在或读取失败直接报错退出不要静默继续。另一个原因是会话太长。AI模型的上下文窗口有限如果一次会话聊了太多内容早期的纪律要求会被挤出窗口。解决方法是把长会话拆成多个短会话每个会话聚焦一个功能。会话开始时agent重新加载纪律文件确保上下文新鲜。实操心得我一般把每个会话控制在20轮对话以内。超过20轮就开新会话把当前进度写入last_session字段新会话从进度继续。5.2 依赖冲突的快速定位与修复依赖冲突的表现是代码在本地跑得好好的换台机器或换个时间就跑不起来。常见原因是某个库的版本变了API不兼容。快速定位方法用pip freeze导出当前环境的完整依赖列表和纪律文件里的dependencies字段对比。如果发现版本不一致就是冲突源头。修复方法在纪律文件里锁定版本然后用pip install -r requirements.txt重新安装。如果冲突涉及多个库可以用pipdeptree查看依赖树找到冲突的根源。我踩过的一个坑是AI生成的代码里用了pandas的某个新API但我本地装的是旧版本。AI不知道我的版本它只是根据训练数据里的最新版本生成代码。解决办法是在纪律文件里明确写清楚版本号并在提示词里强调“请使用指定版本的API”。5.3 代码风格漂移的自动检查方案代码风格漂移的表现是同一个项目里变量命名一会儿snake_case一会儿camelCase函数一会儿用类封装一会儿用纯函数。自动检查方案在agent里加一个后处理步骤用正则表达式检查生成的代码是否符合命名规范。比如检查变量名是否匹配^[a-z_][a-z0-9_]*$如果不匹配就提醒。更彻底的方法是用flake8或pylint做静态检查把纪律文件里的命名规范转换成配置文件。比如在.flake8里设置variable-naming-stylesnake_case然后让agent在代码生成后自动跑一遍flake8。我目前用的是正则检查加手动抽查。正则检查能抓住大部分问题但有些复杂情况需要人工判断。比如AI生成的一个函数名是getBookmarkList正则检查会报错但人工判断可能觉得这个命名在特定上下文里是合理的。5.4 多agent协作中的接口不一致问题接口不一致的表现是前端agent生成的请求格式和后端agent期望的格式不匹配导致联调失败。排查方法先检查.api-contract.yaml文件是否被两个agent都正确读取。然后检查两个agent生成的代码是否严格遵循了约定。我遇到过一次前端agent把POST请求的body写成了form-data但后端agent期望的是JSON。原因是约定文件里没有明确写content-type。解决方法在约定文件里加content_type字段明确每个接口的请求和响应格式。同时在agent的提示词里强调“必须严格按照约定文件生成代码不得自行更改格式”。另一个技巧是在联调前先用curl或Postman手动测试接口确认后端返回的数据结构和约定文件一致。这样可以提前发现问题不用等到前端跑起来才发现。5.5 常见问题速查表问题类型典型表现排查方法解决方案上下文丢失AI忘记项目规范检查纪律文件是否加载拆分会话重新加载纪律文件依赖冲突换环境后报错对比pip freeze和纪律文件锁定版本用requirements.txt风格漂移命名不一致正则检查或flake8在纪律文件里明确规范接口不一致前后端联调失败检查约定文件和content-type完善约定文件手动测试接口环境差异换平台后报错检查路径分隔符和权限用os.path.join加权限检查经验遗忘重复解决同一问题搜索经验库自动归档会话前检索提示这张表建议打印出来贴在显示器旁边。我前三个项目基本把表里的问题都踩了一遍第四个项目才顺畅很多。6. 纪律系统的后续扩展与个人体会这个纪律系统目前还是一个命令行脚本功能比较基础。我后续想加的几个方向一是自动检测代码中的安全问题比如硬编码的密钥、不安全的反序列化二是支持更多语言目前只针对Python做了优化三是加一个简单的Web界面方便在浏览器里查看经验库和纪律文件。但这些都是锦上添花。核心的纪律逻辑已经跑通了启动时加载元数据过程中检查规范结束时归档经验。这套逻辑不依赖任何特定工具你完全可以用任何AI编程工具配合任何文本编辑器来实现。我个人在实际操作中的体会是AI编程的效率提升不在于AI能写多少代码而在于你能不能让AI少犯重复的错误。纪律系统的价值就在这里。它不能让你从零基础变成专家但它能让你在从零到一的过程中少走很多弯路。最后分享一个小技巧每次开新项目时先把纪律文件写好哪怕项目还没开始写代码。这个文件会成为你和AI之间的“合同”后续所有代码生成和检查都围绕它展开。我试过先写代码再补纪律文件结果发现纪律文件总是滞后于实际需求效果差很多。先写纪律再写代码顺序不能反。