【AI翻译】智能体编程原则与实践(Agentic Coding Principles & Practices)

URL 来源: http://agentic-coding.github.io/

概述

本仓库分享"智能体编程6原则28实践"，旨在帮助使用AI编程助手的开发者从"直觉编程迈向智能体编程"。目标是为开发者提供具体指导方针，以充分发挥生成式AI和编程助手的强大能力，在最大化开发效率的同时，有效管控潜在风险，确保开发者对代码质量、安全性和可维护性负责。

动机

AI编程助手让我们能够以令人惊叹的方式瞬间将创意转化为真实代码，几乎就像"言出法随"。（这一表述和核心理念深受Ethan Mollick的文章《言出法随，2025年3月12日》启发。）就如同念诵简单咒语即可施展"三环火球术"一般，我们能够轻松生成代码来快速实现功能。我本人曾尝试用这种方式创建一个钓鱼应用原型，尽管此前毫无移动开发经验。这是一次令人惊喜的体验，仅用一周时间，我不仅借助AI完成了代码实现，还涉足了整个软件开发生命周期(SDLC)——从项目规划、产品需求、设计、核心功能实现，乃至基础QA准备（如测试用例生成）——主要通过AI辅助便取得了不错的成果。

然而，这些"轻易召唤的存在"往往难以驾驭，生成的代码很可能杂乱无章。正如威力强大却粗糙的火球，虽然在简单实验或兴趣项目中看似威风凛凛，但直接应用到需要稳定性、质量和可维护性的生产环境中，可能力不从心甚至危险重重。这样的代码容易留下我们终将偿还的"技术债务"这一黑魔法。

在实际工作中，我们真正需要的不仅仅是简单的火球，而是如同"九环流星坠击"般强大、精妙且可靠的成果——能够解决复杂问题并创造可持续价值的结果。换言之，我们需要与AI有效协作，产出适合真实产品开发的高质量、稳定代码。

生成式AI和编程助手技术突飞猛进，但要安全准确地召唤"流星"，仍需施法者——我们开发者——具备深刻理解、谨慎态度和娴熟的"法术控制技巧"。仅仅拥有强大工具并不能自动保证卓越成果。

本仓库正是基于这些思考而建。它旨在分享"智能体编程原则与实践"，帮助开发者与AI编程助手协作，负责任地创造适合实际生产环境的"流星级"成果，超越仅仅生成"火球级"代码的层次。

我整理并分享这些原则和实践，希望看到更多同行法师（开发者）在真实工作中超越业余级别的火球发射，转而与AI携手召唤强大而精妙的"流星"。

原则

这些原则为实践高效且负责任的"智能体编程"提供基本指导，不论具体使用何种AI编程工具、技术栈、开发者角色或资历层级。

1. 开发者责任制

• 描述： 即使在AI助手协助下，开发者对其编写（或最终批准）并提交至系统的代码之质量、功能、性能、安全性和可维护性承担最终责任。
• 核心： AI只是工具；人类才是责任主体。"AI做的"不是有效借口。

2. 理解与验证

• 描述： 不应在未充分理解的情况下接受或使用AI生成或建议的代码。在将任何代码集成到系统之前，必须完全理解其功能和影响，并进行彻底验证（包括代码审查和测试）。
• 核心： 禁止盲目接受代码。这能防范隐藏的bug或意外副作用。

3. 安全性与机密性优先

• 描述： 不要直接向未经公司明确批准的外部AI助手输入或分享公司敏感信息（源代码、API密钥、内部数据、客户信息、知识产权等）。即使使用已批准的工具，也要对通过助手、中间服务器等可能发生的意外数据泄露保持警惕，严格遵守所有公司安全政策和指导原则。
• 核心： 防范数据泄露和安全事件。

4. 维护代码质量、标准与一致性

• 描述： 开发者有责任确保AI助手生成的任何代码都经过修改和管理，以满足团队和公司的编码约定、架构模式、设计体系、安全标准和相关合规要求。
• 核心： 维护代码库一致性和质量，有效管理技术债务。

5. 人类主导的设计与批判性思维

• 描述： 核心系统设计、架构决策和关键业务逻辑的实现必须由开发者主导。将AI助手用于支持角色（如创意激发、实现辅助），但始终批判性地评估其建议，避免盲目接受。
• 核心： 认识AI的局限性；基于人类洞察和经验做出关键决策。

6. 认识AI局限性并适应技术变化

• 描述： 了解并在AI能力和已知局限性范围内使用AI（如幻觉、偏见、过时知识、缺乏上下文理解等）。跟上快速发展的AI技术和工具。通过探索/试验新功能/技术、在团队内分享成功/失败经验、参与相关社区等方式，持续更新对有效使用模式和风险的认知，提升技能。
• 核心： 不要过度依赖AI；清晰了解其边界。持续适应变化的技术，不断构建团队能力。

实践

这些实践提供了如何在现实工作环境中应用AI协作开发原则的具体方法和指导，为将理论原则转化为可执行步骤提供实用指南。

A. 准备与设置

此类别涵盖设置流程，专注于优化规则以实现一致的AI助手行为，并为特定项目内的有效任务执行提供必要的结构和设计上下文。

1. 设置助手规则和基础上下文

积极利用AI助手的自定义配置功能（如.cursor/rules、CLAUDE.md、.windsurfrules），预设并微调AI必须始终遵循的规则，以及应当参考的持久上下文信息。这包括团队编码标准摘要、架构原则、关键库列表/版本、GitFlow政策等项目级基础技术栈细节和约定。

2. 提供项目结构和设计上下文

要让AI助手在特定项目内正确修改或生成代码，理解项目独特的代码结构和设计意图至关重要。明确提供AI可参考的结构和设计上下文，包括关键目录、模块和类的角色职责、数据流模式，以及项目内特定库使用约定。

B. 战略性AI使用

此类别涵盖判断何时以及为何目的恰当使用AI以实现有效应用的实践。重点在于避免滥用并最大化AI优势的战略方法。

3. 定义任务特定的AI策略

启动任务前，判断这是否为AI可基于详细规范（需求、设计文档等）大致驱动实现的任务，如功能实现、重构或测试生成。或者，评估是否需要大量人类参与，包括深度设计审查、实现过程中的干预以及对最终输出的严格验证——典型例子如设计新核心架构、处理敏感数据逻辑或实现复杂业务规则等任务。基于此评估，决定恰当的人类干预水平和角色。对于AI驱动的任务，专注于提供高度详细清晰的规范，随后进行彻底验证。对于人类主导的任务，确保从初始设计到最终代码审查和修改的深度参与，以引导方向和管控风险。无论采用哪种方法，最终责任仍在开发者；避免完全自主执行。

4. 基于上下文调整AI策略

当AI明显阻碍进展时——如反复提供不准确代码、建议权宜之计、引入安全风险或显示其他明显性能局限——灵活调整AI使用策略，而非僵化地坚持初始方法。考虑尝试以下做法：

• 利用外部信息： 指示AI使用外部网络搜索或类似工具查找类似问题案例或最新解决方案。
• 考虑不同LLM： 当前模型可能不适合该任务。如果可能，尝试切换到不同类型的LLM。
• 重新定向AI并探究根本原因： 如果AI似乎困于问题表面层面，重新提供更广泛的代码上下文或系统架构信息，引导其分析潜在根本原因。
• 请求深度思考/规划： 使用"深入思考"、"慢慢来"或类似提示词（如果支持）鼓励AI为规划或分析问题分配更多资源（参见如Claude扩展思维提示）。

5. 利用多个助手（并行使用/协作）

超越单助手使用，考虑同时利用多个AI助手实例（不同助手类型或同一助手的多个窗口/标签）的策略，以提升开发效率和质量。例如：(1) 助手专业化： 一个生成代码，另一个审查质量/安全性。(2) 角色分工： 一个助手编写测试，另一个编写通过测试的代码。(3) 并行处理： 在多个助手窗口/标签中同时运行不同任务，充分利用响应等待时间。

C. 交互与提示

此类别详述了具体交互方法和提示工程技术的实践，以有效与AI沟通并达成期望结果。重点在于通过清晰指令、有效上下文利用和迭代改进来最大化AI性能。

6. 制作具体清晰的提示

AI无法完美推断人类意图或遗漏的上下文。避免模糊请求；相反，从AI角度制定尽可能具体明确的提示，清楚说明目标（做什么）、上下文（在哪里）、约束和要求（如何做）。始终假设对你来说清楚的内容对AI可能不够充分或模糊。如果输出不符合预期，迭代改进提示。

7. 将任务分解为可管理的单元

AI在清晰、可管理的工作单元上比在大型复杂任务上表现更佳。不要一次性分配主要功能请求，而是将工作分解为有意义的更小步骤（如函数、模块、小功能增量）。按顺序请求这些步骤并整合结果。但是，过度细化分解可能导致整体上下文或一致性的丢失。基于任务复杂性和AI能力找到恰当的分解层级，并在整合过程中始终检查整体一致性，这一点至关重要。

8. 通过代码示例确保一致性（少样本提示）

当提供具体示例（少样本提示）时，AI往往生成更准确一致的结果。添加或修改功能时，与其简单指示AI遵循模式，更有效的方式是在提示中包含相关现有代码片段或类似功能示例。这引导AI从示例中学习风格、结构和模式，并一致地实现新代码。

9. 在实现/规划前优先探索

处理复杂问题或不熟悉的代码库时，指示AI首先通过阅读指定文件、文档或URL来探索相关背景信息，然后再要求其实现代码或创建计划。在此探索阶段，明确防止AI过早生成代码或建议解决方案。这确保为后续规划和实现奠定更好的理解基础。

10. 采用"先规划，后编码"方法

对于复杂或关键任务，要求AI首先概述其实现计划或方法。这让你能在继续前验证其对上下文和指令的理解。只有在你审查并批准计划之后，才指示AI生成实际代码。这有助于早期发现误解或错误方法，最终节省时间和精力。

11. 在AI任务执行期间监控和干预

即使有清晰指令，AI有时也可能偏向意外方向。如果助手表现出意外或低效行为——如执行未请求的任务、在仅被问问题时修改代码，或不可预测地更改代码——立即中断其执行（如按Escape）并提供清晰反馈以重新定向。因此，避免使用将整个过程委托给AI的完全自主执行模式。

12. 通过开放式问题将AI用作学习伙伴

除了给出直接指令，还要将AI用作学习伙伴。积极提出开放式问题或请求替代方案，以探索解决方案或获得多样化想法，用于研究新技术/API、分析错误根本原因、理解代码库（入职培训）或头脑风暴问题解决方法等任务。例如："X的替代方法有哪些？"、"Y的利弊是什么？"、"对于Z我应该考虑哪些因素？"。这充分利用了AI的分析和探索能力。

13. 管理上下文窗口和分离会话

为最大化AI对上下文的利用，管理对话会话，使每个会话理想地专注于单一职责或任务（类似单一职责原则-SRP）。对新任务始终开始新会话，以防止先前对话的干扰。如果单一任务内的对话变得过长并有超出上下文窗口限制的风险（或者即使在达到限制前AI似乎也困惑），总结到目前为止的关键进展和上下文。将此摘要作为新会话的初始提示，以维持AI的专注和性能。

D. 代码审查与验证

此类别涵盖确保AI助手生成或修改的代码质量、正确性和安全性所需的基本审查和验证实践，并保证开发者完全理解其功能。记住，助手生成代码的最终责任在于开发者。

14. 立即检查生成的代码

在继续之前不检查生成的代码有复合错误的风险。代码生成后，立即审查以快速验证输出是否符合基本意图。如果发现问题，及早解决，避免在错误代码基础上进一步构建工作。

15. 禁止使用不可理解的代码

如果你无法清楚理解代码如何工作并向同事解释，绝不使用生成的代码。如果你怀疑它与设计意图不符或存在隐藏问题（bug、低效、安全漏洞等），不要使用它。相反，重新生成、修改或自己编写。向助手询问解释有助于理解，但理解和决定是否使用代码的最终责任完全在于开发者。

16. 检查基本代码质量和标准

集成前，验证生成的代码不仅在功能上可行，还要遵守团队编码标准（风格指南、命名约定等），并且没有明显的性能瓶颈或安全漏洞。这作为初始质量门槛，在功能测试或同行审查之前评估基本代码完整性和安全性，重点识别代码异味、标准违规和潜在风险。

17. 执行行为测试并验证测试代码

AI生成或修改的代码可能表现出意外行为或遗漏边缘情况。始终通过运行单元/集成测试或直接执行来验证其预期行为。关键是，验证生成的测试代码本身：确保它提供充分覆盖并采用正确的断言逻辑。必要时包括手动测试和边缘情况验证。

18. 验证准确性和时效性

AI提供的代码片段（如特定API使用、库版本）或解释（技术细节、使用模式）可能包含不准确性（幻觉）或过时信息。始终根据官方文档和权威技术资源等可信来源交叉验证代码和相关信息，确认准确性并确保它们反映最新信息。

19. 为有效同行审查做准备

通过同行代码审查进行交叉验证对AI生成的代码尤其关键。为促进有效审查，提交代码时：(1) 清楚表明使用了哪种AI工具及其贡献程度。(2) 清楚区分（如有必要）纯AI生成部分和开发者修改或完善的部分。这帮助审查者准确理解上下文，专注于AI特定陷阱（如常见幻觉模式或逻辑缺陷），实现更彻底的验证。

[注意] 代码质量应根据相同标准评估，无论是人类还是AI助手编写。但在AI代码生成技术的早期阶段，完全信任是困难的，可能存在助手特定的错误模式。如上所述透明分享AI参与信息，有助于同行审查者理解上下文，更仔细地审查代码可能存在的问题，并逐步建立对AI辅助工作流的信心。随着AI技术和团队协作实践的成熟，这些指导原则可能会演进。

E. 质量、标准与安全

此类别概述了确保通过AI辅助生成的代码以及开发过程本身满足团队和公司质量标准、技术标准和安全要求的实践。这些对维持代码库的长期健康和可靠性至关重要。

20. 确保生成的代码遵守团队标准

由于AI助手不了解团队特定的编码标准、风格指南或架构规则，确保生成代码的合规性是开发者的责任。使用以下方法的组合：

• 提供前期指导： 用团队标准/约定配置助手工具（见A#1）或在提示中包含相关代码示例（见C#8），引导助手尽可能遵循现有风格。
• 自动化检查： 强制使用代码检查器和格式化器，在提交前运行以自动检查风格问题和基本规则违规。
• 最终审查和纠正： 即使自动化检查通过，执行最终手动审查以修复任何剩余的团队标准不合规问题，或请求助手修改。

21. 将敏感数据与代码/提示分离

将API密钥和个人信息等敏感数据与代码库完全分离。使用.env文件（添加到.gitignore）或专用密钥管理工具（如Secrets Manager）等方法安全存储。避免在代码中硬编码敏感数据，严格禁止在与AI助手交互时直接在提示中输入或粘贴此类信息。

22. 验证和应用助手工具安全设置

(1) 助手工作区索引可能通过将敏感文件内容包含在外部共享的聊天上下文中来暴露它们。使用相关配置文件（如.cursorignore）明确排除敏感文件和目录不被索引。(2) 始终验证并启用AI服务提供商的选择退出数据用于训练或类似安全设置的选项，以防止提交的代码和数据被用于模型改进。

23. 重构生成的代码以满足质量标准

将生成的代码视为初稿，因为它往往缺乏对更广泛系统上下文的认识，可能采用非常规模式，或可能效率低下。即使在通过功能验证（#17）和基本质量检查（#16）后，在集成前始终批判性地重构代码以符合团队标准。关注可读性、效率、消除重复、可维护性以及遵循设计原则/模式等标准。积极改进助手引入的不清楚或非标准名称（变量、函数等）和不必要的复杂性。

F. 工作流与心态

最后这一类别涵盖与整体开发工作流习惯、有效工具使用模式以及成功采用和协作AI助手所需的基本心态相关的实践。它旨在促进可持续的协作文化，超越纯技术层面。

24. 使用状态和上下文进行复杂任务管理

对于涉及多个步骤或依赖先前状态的复杂任务（如大规模重构、迁移），通过指示助手使用专用上下文空间（如plan.md文件或详细Jira工单）跟踪任务状态和参考进展，引导系统性进展。这有助于助手有效管理和遵循整体计划。

25. 管理检查点并无畏回滚

助手偶尔可能在错误路径上走得太远，使手动回退变得困难。为减轻这种情况，细致管理可回滚检查点：(1) 进行频繁、有意义的Git提交。(2) 如果工具支持，利用对话或任务级还原点。由于用AI重新生成代码往往成本较低，如果你确定过程已偏离，不要犹豫回滚到最近的检查点。用修订的指令或上下文重新开始过程，解决偏离的原因。

26. 利用AI进行更智能的调试

利用AI助手简化调试过程。(1) 至少向助手提供确切错误消息和相关代码片段，进行根本原因分析和潜在解决方案。(2) 有了强大的日志系统，你甚至可以引导助手分析日志以主动检测和建议修复问题。(3) 一些高级助手可以通过自主插入、执行和删除临时调试代码（如日志语句）来执行主动调试，以精确定位和解决问题。利用这些方法减少调试时间并创造学习机会。

27. 分享经验促进团队学习

团队级学习对有效AI协作至关重要。使用既定团队渠道（如Wiki、内部博客）积极分享和讨论相关经验：(1) 对特定任务效果良好或导致失败/低效的提示示例。(2) 助手错误（如幻觉）或意外成功的具体实例。(3) 问题解决过程中获得的诀窍或有用发现。这种集体分享提高了团队使用AI助手和解决问题的整体熟练程度。

28. 无畏实验并享受乐趣

将AI助手不仅视为工具，而是多面的协作伙伴：有时是协助代码生成的结对程序员，有时是减轻重复任务负担的助手，有时是提供问题解决提示的导师，或是通往新知识的门户。有了安全的实验环境（得益于检查点，#25），有效使用的关键是保持好奇心，尝试多样化的协作方法，享受探索可能性的过程。

结论

AI编程助手的出现不仅仅代表一种技术趋势；它标志着软件开发的根本性范式变迁。我们可能还记得过去从文本编辑器转向集成开发环境（IDE）带来的生产力提升。然而，AI编程助手带来的变化可能会超越那次转变。这是因为它不仅仅是使用更好的工具——它从根本上重新定义了我们的工作方式。"智能体编程"是这一变化浪潮中的一种方法，它不仅将AI视为自动化工具，而是作为放大开发者创造力和战略思维的协作伙伴，旨在负责任地创造更高层次的成果。

本文档中提出的原则和实践是当前有效协作的指导方针。它们强调开发者主动作用、批判性思维和最终责任的重要性，在确保AI生成输出质量和安全性并使其适用于生产环境级别的过程中。

当然，挑战在前。这些包括确保AI生成代码的长期可维护性，弥补知识差距使所有开发者都能有效使用AI工具，防止因过度依赖技术而导致批判性思维技能的削弱。与此同时，巨大的机遇正在显现：编程的准入门槛正在降低，开发者有更多能力专注于创造性和创新性问题解决，从重复任务中解脱出来。

归根结底，如何利用这项技术比技术本身更重要。即使在AI时代，人类创造力、道德判断和专业专长仍将是软件开发的核心要素。随着AI技术和开发方法论的持续演进，这些指导原则应被视为持续学习和适应的起点。

"能够生存的物种，不是最聪明的，也不是最强壮的，而是最能适应和调整其所处变化环境的物种。" - 查尔斯·达尔文

参考资料

• Vibe Coding is not an excuse for low-quality work
• Claude Code: Best practices for agentic coding
• A Guide to Master the Art of Vibe Coding

实验

• Is Vibe Coding the start of a new development paradigm?

感觉写作

"本文档通过与Gemini-2.5-Pro的'感觉写作'创建，基于从上述参考文档和'vibecoding'与'agentic coding'实验中获得的见解。原则通过20多轮对话共同制定，实践通过300多轮对话协作微调。"

贡献

通过Issues、Discussions或Pull Requests分享您的经验和见解，将大大帮助我们所有人共同推进"智能体编程"。

许可证

版权所有 (c) 2025 Benedict Lee

本作品根据知识共享署名4.0国际许可证授权。要查看此许可证的副本，请访问http://creativecommons.org/licenses/by/4.0/ 或查看LICENSE文件。