副标题: 从零到一的完整开发流程与沟通技巧
版本: v1.0 日期: 2025-11-21 作者: 基于autowzry-agent项目开发经验总结
本文档是我在使用Claude Code开发autowzry-agent项目过程中总结的经验和方法。主要目的是帮助我自己在未来的新项目中快速建立高效的AI协作开发模式，同时也希望能帮助其他初学者学习如何与AI Agent有效协作。
与AI Agent协作开发的三个核心理念：
控制节奏：不让Agent立即执行，而是先讨论、确认、再实施。通过”不要立刻写”、”先讨论”这样的提示词控制开发节奏，避免Agent按错误的理解开始工作。
明确沟通：使用清晰的提示词和结构化的对话方式。需求要逐步澄清，设计要总结确认，每个阶段都要明确批准。避免模糊的表达导致理解偏差。
文档驱动：建立完整的文档体系，让Agent通过阅读文档快速了解项目。文档包括架构设计、开发日志、使用指南等，随着项目进展同步更新。
本文档按照开发时间线组织，从项目启动到日常开发的各个阶段都有详细说明：
docs/guides/AGENT_COLLABORATION_RULES.md - Agent应该遵循的通用规则，跨项目适用docs/guides/README_FOR_AGENT.md - 让新Agent在10分钟内了解项目docs/design/ARCHITECTURE.md - 完整的项目架构和函数签名新项目启动时：按顺序阅读第一章和第二章，了解如何建立协作框架和实现第一个模块。
日常开发时：根据当前任务查阅对应章节，比如要实现新功能就看第四章，遇到Bug就看第五章。
遇到问题时：参考第五章的调试方法和第六章的最佳实践，找到解决方案。
新项目开始时，首先要向Agent介绍项目的基本信息。用一段完整的话描述项目是什么、要解决什么问题、目标用户是谁、使用什么技术栈。
对话模板：
我要开发一个XXX项目，主要功能是YYY。目标用户或使用场景是ZZZ。技术栈包括AAA、BBB、CCC。这个项目的特点是DDD，预期能达到的效果是EEE。
autowzry-agent项目示例：
我要开发一个强化学习Agent项目，叫autowzry-agent，主要功能是训练AI玩王者荣耀游戏。通过观看视频或在线对战收集数据，使用DQN算法训练模型，让AI学会控制游戏角色进行战斗。技术栈包括Python、PyTorch、OpenCV、还有autowzry库用于控制安卓设备。这个项目的特点是离线学习，可以从录制的游戏视频中学习，不需要一直连接设备。预期能达到的效果是AI能够自主进行基本的移动和攻击，逐步提升对战能力。
在开始具体开发前，让Agent阅读协作规则文档。这个文档定义了Agent应该遵循的通用规则，比如不要立即执行、要先讨论、使用TodoWrite跟踪任务等。
对话方式：
请先阅读 docs/guides/AGENT_COLLABORATION_RULES.md。这是我们协作开发的规则，所有开发工作都要遵循这些规则。阅读完后确认你理解了，然后我们开始项目规划。
Agent应该回复：
我已经阅读了AGENT_COLLABORATION_RULES.md，理解了8条核心法则：沟通原则、任务管理、代码质量、文档同步、错误处理、信息获取、表达方式、学习与适应。我会在整个开发过程中遵循这些规则。现在可以开始项目规划了。
这个步骤很重要，因为它建立了协作的基本规则。后续如果Agent违反了某条规则，可以提醒他”记住Agent法则第X条”。
开发规范包括两部分：架构设计原则和代码风格规范。这些规范要在项目开始时明确，后续所有开发都要遵循。
(a) 架构设计原则
对话模板：
我们约定一下架构设计原则。这个项目的核心理念是XXX。首先是YYY的角色，它负责ZZZ。其他模块要保持通用性，比如AAA模块负责BBB，CCC模块负责DDD。我们采用EEE模式，初始化时FFF。数据流是GGG。记住这些原则，所有设计决策都要遵循。如果你不确定某个设计是否符合原则，不要猜测，先问我。
autowzry-agent项目示例：
我们约定一下架构设计原则。这个项目的核心理念是模块化和通用性。
首先是兼容层的角色。compatibility.py这个文件是整个项目中唯一跟具体游戏和设备相关的模块，所有游戏特定的逻辑、设备操作、图像识别算法都封装在这里面。未来如果要换一个游戏，或者换一个控制库，只需要重写这个兼容层就可以了，其他模块完全不用动。
其他模块都要保持通用性。比如action模块负责定义动作空间，reward模块负责奖励计算，data模块负责数据管理，buffer模块负责训练数据加载，trainer模块负责训练。这些模块不应该包含任何游戏特定的代码，它们通过兼容层提供的接口来工作。
我们采用依赖注入的模式。兼容层在初始化时会创建并连接所有其他模块。比如兼容层先初始化action模块，把自己传进去；然后用action模块初始化data模块；再把data模块传给buffer。这样形成了一个完整的依赖链，但是每个模块本身都是独立的。
数据流是这样的：视频文件或者设备画面首先进入兼容层，兼容层截图后交给DataManager处理，DataManager把数据保存到HDF5文件，然后TrainingBuffer从HDF5加载数据提供给Trainer训练，训练出的模型最后又通过兼容层控制设备进行对战。整个流程是单向的，很清晰。
记住这些原则，所有的设计决策都要遵循。如果你不确定某个设计是否符合原则，不要猜测，先问我。特别是当你发现需要在通用模块里写游戏特定代码时，一定要停下来重新考虑设计。
(b) 代码风格规范
对话模板：
再约定一下代码规范。这些规范在所有代码中都要保持一致。日志输出使用XXX格式。所有脚本都用YYY处理命令行参数。异常处理统一用ZZZ方式。函数返回值遵循AAA规则。变量命名用BBB，类名用CCC，常量用DDD。输出分隔线统一用EEE。请在所有代码中保持这些风格，特别是当你参考现有代码时，注意学习它们的风格并保持一致。
autowzry-agent项目示例：
再约定一下代码规范。这些规范在所有代码中都要保持一致。
日志输出使用固定格式，用方括号加标签开头，然后是具体内容。比如加载数据时输出'[Load] Loading: filepath'，出错时输出'[ERROR] 错误信息'，警告用'[WARNING]'，保存用'[Save]'。这样日志很清晰，容易筛选。
所有脚本都用argparse处理命令行参数。定义一个parser，添加需要的参数，然后用args来访问。参数名用连字符分隔，比如--config-file，--max-frames。
异常处理统一用try-except包裹主要逻辑，在except块里先打印错误信息，然后用traceback.print_exc()输出完整的堆栈跟踪。这样出错时能快速定位问题。
函数返回值遵循Unix风格：成功返回0，失败返回1。主函数最后用sys.exit(main())来返回状态码。
变量命名用snake_case，就是全小写字母，单词之间用下划线连接，比如data_manager，buffer_capacity。类名用PascalCase，每个单词首字母大写，比如DataManager，TrainingBuffer。常量用全大写加下划线，比如MAX_FRAMES，DEFAULT_CONFIG。
输出分隔线统一用等号重复60次，就是'='乘以60。这样不同部分的输出很容易区分。
请在所有代码中保持这些风格，特别是当你参考现有代码时，注意学习它们的风格并保持一致。
文档规范定义了文档的目录结构、更新规则、更新流程。这个规范确保文档体系完整、清晰、易于维护。
对话方式（autowzry-agent项目示例）：
我们来规划一下文档结构。所有文档放在docs目录下，按功能分成四个文件夹。
第一个是guides文件夹，存放各类指南文档。里面有三个文件：README_FOR_AGENT.md是给未来Agent的快速上手指南，这是必读文件，目的是让Agent在10分钟内了解项目；quickstart.md是给用户的使用手册，教用户如何使用项目；还有COLLABORATE_WITH_AGENT.md就是我们现在写的这个协作开发指南。
第二个是design文件夹，存放设计相关文档。主要是ARCHITECTURE.md，这个文件记录完整的项目架构，包括每个模块的功能、类的定义、函数签名、依赖关系等。这个文档很重要，能帮Agent快速了解项目结构，节省大量token，不用去读具体代码文件。
第三个是logs文件夹，存放开发日志。development_log.md是日志索引文件，列出所有开发记录的链接和简短摘要。每次开发会话的详细记录单独保存，文件名格式是日期加主题，比如2025-11-20_buffer_check_tool.md。每个详细日志包括开发背景、实现内容、技术细节、测试结果和文件变更记录。
第四个是old文件夹，存放已经废弃或过时的文档。当文档不再适用时，不要删除，移动到这里作为历史参考。
关于文档更新的规则：每次开发会话结束时必须更新development_log.md，添加索引条目并更新项目状态；架构调整时要更新ARCHITECTURE.md；流程变更时要更新quickstart.md。
更新文档的流程是：不要直接修改，先告诉我你要改哪些文件、为什么要改、准备添加什么内容，我确认后你再执行。
请确认你理解了这个文档规范。
README_FOR_AGENT.md是项目的入口文档，目的是让未来接手的Agent在10分钟内了解项目。这个文档要包含必读文件列表、项目状态、核心原则、任务指引等。
对话方式：
请生成 README_FOR_AGENT.md，目的是让未来的Agent在10分钟内了解项目。
内容结构包括：第一部分是必读文件列表，列出3到5个最重要的文档，按优先级排序，说明每个文档的作用和大概阅读时间，总时间控制在10分钟以内。第二部分是项目当前状态，分为已完成和待开发两部分，用对勾标记已完成的，用沙漏标记待开发的。第三部分是核心架构原则，简短描述3到5条最重要的设计原则。第四部分是根据任务阅读文件的指引，比如用户要求收集数据应该读哪些文件、用户要求训练模型应该读哪些文件。第五部分是重要提醒，分为不要做的和应该做的，各列3到5条。第六部分是标准工作流程，描述开发的基本步骤，大概6步左右。
语气要友好但专业，就像在和未来的同事对话一样。开头可以说"致未来的Agent：你好！欢迎加入XXX项目开发"。
在新的开发会话开始时，或者Agent对项目不熟悉时，用这个方法引导Agent快速了解项目。
基本方式：
先读 docs/guides/README_FOR_AGENT.md
这一句话就够了。README_FOR_AGENT.md会告诉Agent应该按什么顺序阅读哪些文档。
进阶用法：
当需要Agent深入了解某个方面时，可以这样说：
根据 README_FOR_AGENT.md，你需要先读三个文档。第一个是quickstart.md，了解整个训练流程，大概3分钟。第二个是ARCHITECTURE.md，了解每个模块的功能和接口，大概5分钟。第三个是development_log.md，了解最近的开发进度和当前状态，大概2分钟。读完后，我们讨论XXX功能的实现。
关键点：
README_FOR_AGENT.md是项目的索引和导航。它不包含详细的技术信息，而是告诉Agent去哪里找详细信息。这样Agent能快速建立项目的整体认知，然后根据需要深入了解具体部分。
不要让Agent盲目地grep搜索代码或glob查找文件。大部分情况下，文档已经告诉了Agent所需的信息。如果Agent开始搜索，说明文档不够完善，应该补充文档而不是依赖搜索。
实现任何新功能前，都要先进行充分的需求讨论。这个阶段的目标是确保Agent完全理解要实现什么、为什么要实现、怎么实现。
用户开场：
我们来实现XXX模块，功能是YYY。先讨论一下接口设计和实现思路，不要立刻写代码。
“不要立刻写代码”这句话很关键，它明确告诉Agent现在是讨论阶段，不是实现阶段。
Agent应该做的：
Agent应该提出澄清问题，用自然的问句形式询问。问题要具体，涵盖输入输出、依赖关系、边界条件、配置项等方面。
比如：
好的，我理解了基本思路，但是有几个细节需要明确一下。第一个问题，XXX是指什么？是AAA还是BBB？第二个问题，YYY需要考虑ZZZ的情况吗？第三个问题，这个模块依赖哪些其他模块？第四个问题，是否需要配置项？第五个问题，模块应该放在哪个目录下？
用户回答：
逐一回答Agent的问题，给出明确的决策。
Agent总结确认：
Agent收集完信息后，用一段完整的话总结最终设计。总结要包括所有关键要点，用自然的段落形式，不要用列表。
比如：
明白了，让我总结一下最终设计。XXX模块放在YYY目录下，初始化时接收ZZZ参数。主要功能是AAA，通过调用BBB接口实现。输入是CCC格式，输出是DDD格式。需要处理EEE这种边界情况。依赖FFF模块，初始化顺序是GGG。这个设计是否正确？
用户批准：
正确，开始实现。
或者
还有一个问题：HHH应该怎么处理？
请查看完整文档的”第四章案例”部分，这里有一个完整的Reward模块实现对话示例。
[继续第二部分…]
当需要在已有模块基础上添加新功能时：
当前XXX模块已实现，现在要扩展YYY功能。先读取XXX的实现，理解现有逻辑，然后讨论YYY如何集成，不要破坏现有架构。
Agent会先读取代码，理解现状，然后提出集成方案。
写代码之前，先阅读scripts文件夹里的train.py和label_data.py这两个文件，学习一下它们的代码风格。特别注意日志是怎么输出的，命令行参数是怎么解析的，异常处理是怎么写的。你的实现要和这两个文件保持一致的风格。
现在开始实现XXX功能，使用TodoWrite跟踪进度。任务列表：1. AAA，2. BBB，3. CCC
Agent会创建TodoList，逐步实现，每完成一个立即标记completed。
现在测试刚实现的功能。使用数据：data/episodes/episode_xxx.hdf5。如果出错，不要立刻修改，先分析原因。
根据本次开发，按照文档规范更新相关文档。你先陈述一下：1. 要动哪些文件，2. 为什么要动，3. 准备添加什么内容
Agent列出计划后，用户确认，然后Agent执行。
对话模式：
先读 docs/guides/README_FOR_AGENT.md, 必须阅读和遵守docs/guides/AGENT_COLLABORATION_RULES.md。不经过我的允许禁止擅自修改代码。
我发现当前XXX设计有问题：[具体描述]。原因是YYY。我希望调整为ZZZ方案。你先分析一下：1. 这个调整会影响哪些文件，2. 需要改动哪些地方，3. 可能的风险是什么。不要立刻修改。
Agent分析影响范围，建议分步实施方案，等待确认后逐步执行。
当前已实现XXX（如move训练），现在要扩展YYY（如attack训练）。先读取XXX的实现代码，理解其设计模式，然后讨论YYY如何集成，确保：1. 不破坏现有XXX功能，2. 保持向后兼容，3. 遵循相同的设计模式
这是一个完整的功能开发案例，展示了从需求讨论到文档更新的全过程。
用户：
我希望增加一个预训练脚本。就是不需要跑训练，但是把数据buffer打开，然后从buffer中抽取数据，保存到hdf5中，以方便我检查buffer的代码是否正确。对于reward小于负1或者大于负1的重点标记或者print到屏幕上，方便我检查。明确需求后再写代码，不要立刻写。
Agent提出5个问题：抽取策略？reward判断条件？输出格式？保存路径？抽取数量？
用户逐一回答，最终明确：抽取所有buffer，绝对值小于0.1算正常，全英文输出详细信息，保存所有字段。
Agent总结确认，用户批准：”正确。另外写代码之前，阅读scripts中的train.py和label_data.py，保持代码风格一致。”
Agent使用TodoWrite创建任务列表：
每完成一个任务立即标记completed。
Agent运行测试，报告结果：95个样本，1个异常（1.05%），测试通过。
用户：
本次开发已基本完成，现需对项目文档进行系统性评审。将按规范逐一梳理待修改的文件清单，明确每项修改的理由及必要性，并制定详细的修改方案与实施计划。所有修订工作均需逐项确认，严禁擅自更改。
Agent列出4个文件：development_log.md、详细日志、ARCHITECTURE.md、quickstart.md，说明理由和内容。
用户确认：”OK，开始”
关键成功因素：需求明确（5轮Q&A）、代码风格统一（先读再写）、文档同步（先规划再更新）
❌ 错误方式：
代码报错了，帮我修一下
✅ 正确方式：
运行XXX.py时报错：[完整错误信息]。我怀疑是YYY的问题，因为ZZZ。你先分析一下可能的原因，不要立刻修改代码。
当Agent违背设计原则时：
你彻底错了，违背了开发原则。错误点：你不应该XXX，因为YYY。正确做法：应该ZZZ。我们重新讨论一下AAA的设计。
关键点：明确指出错误、说明违背的原则、解释正确做法、要求重新讨论。
本次开发基本结束，再次阅读 docs/guides/README_FOR_AGENT.md和遵守docs/guides/AGENT_COLLABORATION_RULES.md。 总结内容，看哪些文档需要修改，修改什么，给出理由和计划。我们逐个进行修改。不要擅自修改。你应该先阅读相关的文档后再做出回答。
新项目启动：
每次功能开发：
控制Agent执行节奏：
让Agent快速了解项目：
避免无意义调试：
从todo.txt和本次对话总结：
docs/guides/AGENT_COLLABORATION_RULES.md - Agent应遵循的通用规则docs/guides/README_FOR_AGENT.md - 10分钟了解项目docs/design/ARCHITECTURE.md - 完整架构和函数签名docs/logs/development_log.md - 开发历史记录文档版本: v1.0 最后更新: 2025-11-21 更新内容: 新增”持续经验积累”沟通技巧 基于项目: autowzry-agent 作者: 项目开发者