近年来，随着大型语言模型（LLM）技术的飞速发展，智能代理工程逐渐成为软件开发领域的新兴热点。许多开发者尝试将这些智能代理视为辅助工具来提升编程效率，甚至试图让它们替代部分人工工作。然而，实际应用过程中，这一领域仍存在诸多挑战，尤其是在面对大型、成熟代码库时，智能代理的表现往往难以令人满意。本文将深度剖析智能代理工程中的痛点，探讨一种创新思路——将提示语（prompt）视为“代码”，而将.json和.md文件用作“状态”，以此实现对智能代理行为的精细控制和管理，从而驯服这一复杂而充满不确定性的系统，并促进高效、可控的软件开发。\n\n智能代理为何尚未真正成为“工程”\n许多程序员对智能代理怀有极大期待，想借助其强大的自然语言处理和代码生成能力解决繁重的编码任务。市场上出现了如Claude Code等多种辅助开发工具，它们在快速生成小规模代码段或原型测试时，表现颇佳。
然而，当需要在庞大、结构复杂的代码库上进行高质量改动时，这些工具却暴露出严重缺陷。核心问题往往是“上下文的不完整与混乱”。智能代理难以全面掌握整个项目的关联结构和业务逻辑，且其模型的上下文窗口有限，无法容纳庞杂的代码和说明文档。即便采用分步推理等技术，模型仍然难以顺畅跟踪代码执行流程，尤其是涉及多进程、客户端-服务器架构、并发等复杂场景时。\n\n此外，智能代理生成的代码通常缺乏“品味”，亦即缺乏简洁、优雅、低耦合的代码架构。它们更多依据训练时统计概率选择“平均做法”，导致产出代码可能过度复杂、难以维护，且容易埋藏潜在的bug。
随着交互轮次的增加，上下文信息的衰减和被挤压更进一步恶化这一问题，使得模型在后期生成结果时常常出现错误。最后，由于许多工具运营商考虑成本中间利润，用户实际上对模型所处理的上下文内容控制有限，这使得重要信息可能被截断或以不合适的格式输入，进一步影响结果质量。\n\n把提示语理解为代码，文件作为状态，实现工程化管理\n面对如此混乱且难以预测的现状，何以“驯服”智能代理工程？答案在于将我们作为软件工程师的系统思维应用于智能代理交互流程。具体来说，我们不再将与模型的互动视作自然语言聊天，而是将“提示语”转化为一段程序代码，.json和.md文件则充当了程序运行的“状态”。这样，我们带来了多种软件工程优势——结构化信息、可重复执行的流程、可持久化的状态管理以及明确的输入输出界定。\n\n在这种框架下，提示语不再是模糊请求，而是详细编写的程序，指定输入来源、状态更新方式和输出目标。
输入包括代码库文档、项目架构概述以及用户交互等，保证模型始终获得所需必要上下文。状态则通过不断更新的.json格式结构化文件进行持久化，包括当前工作进度、已处理类型列表、依赖关系等，避免了上下文窗口过载问题。由于.json和.md文件可随时被读取和更新，整个流程得以在多次交互中保持连续性。输出不仅是生成的代码，更包括日志、差异比较以及进度报告，方便人工监督和后续处理。\n\n通过将智能代理运行于这样一个有着严格定义的“输入—状态—输出”体系内，开发者能够精确控制工作流程的步骤，捕获异常，并在关键节点进行人工确认。整个过程中，复杂的端到端任务被拆解为模块化代码段执行，体现了“元编程”的理念——用自然语言写出运营代码的程序，再让这套程序产出实际运行于CPU的代码。
\n\n真实案例——Spine运行时的跨语言移植\n这一思想并非纸上谈兵。在实际项目中，开发者Mario Zechner以二维骨骼动画软件Spine的运行时跨语言移植为契机，探索了智能代理工程的可能。Spine运行时拥有多种语言实现，包括Java、C++、C#、Dart、Swift等。核心挑战在于，每当参考实现（Java）更新后，需要手动将改动移植到其他所有语言的对应运行时，而这一过程繁琐且易错。传统自动转译器难以胜任，原因包括类型系统和内存管理截然不同、代码风格要求各异等。\n\nZechner基于上述“提示语为代码”和“状态文件持久化”的理念，设计了一个名为“Port Java to X”的结构化程序，将移植计划和进度保存在porting-plan.json中，并用port.md定义整体流程。
这个程序按计划读取变更的Java类型，调用一系列工具自动完成机械性代码移植工作，同时保留人工在关键点的主动权以做决策。每一次交互与改动都清晰被记录下来，允许随时暂停和恢复工作，极大提升了工作效率，从数周缩短为数天。\n\n程序首次运行时会读取porting-plan.json，获取源代码路径、目标语言、移植顺序和已完成项，接着自动打开相关代码文件并生成对比，等待用户确认后开始移植。移植过程中，程序严格遵守已有语言的代码规范与习惯，从类结构、接口定义到方法实现，都需达到与Java原版功能完全匹配。Error handling、命名约定、内存管理等细节则遵循预先定义好的conventions.md。每完成一个类型的移植，会更新状态文件，标注为完成，记录遇到的特殊情况到porting-notes.md。
\n\n该过程配合专用工具（如jq解析JSON、命令行编译检测脚本和编辑器扩展vs-claude）形成闭环，实现了对复杂AI辅助开发流程的工程化管理。\n\n智能代理工程的未来展望\n这场探索不仅展示了如何解决现实工作中的痛点，更为未来AI辅助软件工程指明了趋势。管理上下文信息、状态同步和多步交互的可控执行，将成为提升AI在软件开发领域实用性的关键。通过建设更加严谨的子代理编排机制，实现任务分解和通信渠道的透明化，有望实现大规模、多角色智能代理协同开发。\n\n此外，随着模型和调用机制的进步，对流程执行进行测试、调试和状态追踪也将变为可能。体系化的异常捕捉和决策回退机制或将使智能代理成为像传统编译器一样可预测、稳定的工具。
\n\n总结来说，当前的智能代理工程尚处于从“扔粪墙上看什么能粘”的混沌阶段，真正意义上的智能“工程”需要转变观念：把模型当成一台“速度极慢且不完全可靠的低效计算机”，用自然语言写出可控执行的伪代码，并用结构化文件管理状态。通过这种方式，开发者能够在复杂项目中以一种编程式思维驾驭AI，极大地提高合作效率与质量。未来，随着框架进一步成熟，人工智能助力的软件开发必将呈现出令人惊叹的生产力。
