构建极简且具倾向性的编程代理的经验总结

基本信息

导语

构建一个既具备鲜明观点又保持极简架构的编程智能体，往往比单纯堆砌功能更能触及工程实践的本质。本文作者基于实际开发经验，深入探讨了如何在“自动化”与“人工干预”之间寻找平衡点，以及这种设计哲学如何提升系统的可控性与可维护性。阅读本文，你将了解到构建此类 Agent 的核心取舍逻辑，以及如何通过最小化设计实现更高效的代码辅助工作流。

评论

以下是基于文章标题《What I learned building an opinionated and minimal coding agent》的深度评价。

中心观点

构建 AI 编程代理的有效路径并非追求功能完备，而是通过极简的架构设计与固化的工作流约束，限制大语言模型（LLM）的决策范围，从而在特定场景下提升系统的确定性与执行效率。

深度评价与支撑理由

1. 内容深度：从“通用”到“聚焦”的架构取舍

  • 支撑理由：文章指出了当前 Agent 开发中的一个常见误区：试图赋予 LLM 过多的动态决策权（如自主检索文件、动态规划路径）。作者提出的方案是减少 Agent 的操作自由度（例如限定修改范围、固定 CLI 命令），这种“约束驱动”的设计降低了系统状态的不可预测性，提高了单一任务流的鲁棒性。
  • 边界条件：这种“极简主义”在处理跨文件的大型重构或系统级迁移时存在局限性。当任务需要同时修改数十个文件并保持逻辑一致性时，缺乏全局规划能力的极简 Agent 可能难以处理复杂的依赖关系。

2. 实用价值：工程落地的确定性

  • 支撑理由：文章对工程实践具有参考价值。相比于依赖难以捉摸的 Prompt Engineering，作者主张将工程规范（如强制运行测试、代码检查）硬编码到 Agent 的工作流中。这种“固执己见”的流程控制，使得 Agent 的行为更符合标准化的软件开发周期。
  • 边界条件：该方法的效能高度依赖于预设工作流的质量。如果初始脚手架或固化规则本身存在缺陷（如配置了错误的 Lint 规则），Agent 会严格执行错误指令，导致难以通过自然语言干预进行即时纠正。

3. 创新性：重新定义 Agent 的能力边界

  • 支撑理由：文章提出了一个值得探讨的视角：Agent 的可靠性取决于工作流的确定性，而非模型的自由度。通过将 Agent 定位为“流水线执行者”而非“规划者”，规避了 LLM 在长链条推理中容易出现的注意力分散问题。
  • 边界条件：随着具备强推理能力的模型（如 OpenAI o1）的普及，过度限制模型可能会抑制其处理复杂逻辑的潜力。未来的架构可能会向“动态约束”发展，即根据任务难度动态调整工具链的复杂程度。

事实陈述 vs 作者观点 vs 你的推断

  • [事实陈述]：现有的通用编程 Agent（如 AutoGPT、Devon）在生产环境中常面临上下文溢出、执行循环错误和成本控制困难的问题。
  • [作者观点]：通过移除复杂的规划层和动态文件选择逻辑，仅保留核心的代码生成和执行能力，可以构建出更稳定、易用的编程代理。
  • [你的推断]：这种“极简 Agent”本质上是一种工作流增强工具，而非具备完全自主性的智能体。它更适合作为 IDE 的深度集成插件，用于处理明确的编码任务，而非替代开发者进行宏观的架构决策。

可验证的检查方式

为了验证文章中“极简且固执己见”方法的有效性，建议进行以下验证：

  1. SWE-bench 专项测试对比：

    • 指标：在 SWE-bench 数据集上，对比“全能型 Agent”与“极简型 Agent”的任务通过率。
    • 预期：极简型 Agent 在单文件或简单 Bug 修复中通过率较高，而在涉及多文件联动的复杂 Issue 中表现可能较弱。

  2. Token 消耗与延迟监控：

    • 指标：记录完成同类任务的平均 Token 数和端到端延迟。
    • 预期：极简架构因减少了中间思考步骤和工具调用，Token 消耗应有所降低，响应延迟相应减少。

  3. 错误恢复能力测试：

    • 实验：在环境中设置缺失依赖或配置错误，观察 Agent 的行为。
    • 观察窗口：对比全能型 Agent 与极简型 Agent 在遇到环境错误时的重试次数和恢复成功率，评估“固执己见”的工作流是否会导致死循环。

代码示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

# 示例1：基于工具调用的最小化Agent实现
from typing import Callable, Dict, Any

class MinimalAgent:
    def __init__(self):
        """初始化Agent，注册可用工具"""
        self.tools: Dict[str, Callable] = {
            "calculate": self._calculate,
            "search": self._search
        }
    
    def _calculate(self, expression: str) -> float:
        """计算工具：安全执行数学表达式"""
        try:
            return eval(expression, {"__builtins__": None}, {})
        except Exception as e:
            return f"计算错误: {str(e)}"
    
    def _search(self, query: str) -> str:
        """搜索工具：模拟返回搜索结果"""
        return f"关于'{query}'的搜索结果..."
    
    def process(self, user_input: str) -> Any:
        """处理用户输入并调用相应工具"""
        # 简单的关键词匹配路由
        if "计算" in user_input:
            expr = user_input.split("计算")[-1].strip()
            return self.tools["calculate"](expr)
        elif "搜索" in user_input:
            query = user_input.split("搜索")[-1].strip()
            return self.tools["search"](query)
        return "抱歉，我无法理解该指令"

# 测试代码
if __name__ == "__main__":
    agent = MinimalAgent()
    print(agent.process("计算 2 + 3 * 4"))  # 输出: 14.0
    print(agent.process("搜索 Python教程"))  # 输出: 搜索结果...

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

# 示例2：带记忆的对话上下文管理
from collections import deque

class ConversationMemory:
    def __init__(self, max_history: int = 5):
        """初始化记忆系统，设置最大历史记录数"""
        self.history = deque(maxlen=max_history)
    
    def add(self, role: str, content: str):
        """添加对话记录"""
        self.history.append({"role": role, "content": content})
    
    def get_context(self) -> str:
        """生成格式化的上下文字符串"""
        return "\n".join(
            f"{msg['role']}: {msg['content']}" 
            for msg in self.history
        )
    
    def clear(self):
        """清空历史记录"""
        self.history.clear()

# 使用示例
memory = ConversationMemory()
memory.add("用户", "今天天气怎么样？")
memory.add("助手", "我无法获取实时天气信息。")
print(memory.get_context())
# 输出:
# 用户: 今天天气怎么样？
# 助手: 我无法获取实时天气信息。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# 示例3：简单的工具调用解析器
import re

def parse_tool_call(text: str) -> tuple[str, dict]:
    """从文本中解析工具调用指令
    
    支持格式: [工具名] 参数1=值1 参数2=值2
    返回: (工具名, 参数字典)
    """
    pattern = r'\[(\w+)\]\s*(.*)'
    match = re.match(pattern, text.strip())
    
    if not match:
        return None, {}
    
    tool_name = match.group(1)
    params = {}
    
    # 解析键值对参数
    for pair in match.group(2).split():
        if '=' in pair:
            key, value = pair.split('=', 1)
            params[key.strip()] = value.strip()
    
    return tool_name, params

# 测试用例
print(parse_tool_call("[search] query=Python教程 limit=5"))
# 输出: ('search', {'query': 'Python教程', 'limit': '5'})

案例研究

1：某金融科技初创公司的内部工具开发

1：某金融科技初创公司的内部工具开发

背景: 该公司拥有一支小型的全栈工程团队，需要快速构建和维护一套供内部运营人员使用的管理后台。由于业务逻辑变更频繁，开发人员往往陷入编写增删改查（CRUD）代码的重复劳动中，导致核心业务功能的开发进度受阻。

问题: 开发团队面临“样板代码地狱”。每次产品经理提出一个新的数据字段需求，前端需要修改表单和表格，后端需要修改数据库模型和接口，测试人员还需要回归测试。这种机械性的工作占据了开发人员 60% 以上的时间，且容易产生低级错误。

解决方案: 团队引入了一个基于“固执己见”和“极简主义”理念构建的编码代理。该代理被严格限制在特定的技术栈内（例如使用 NestJS 和 React），并预设了公司的代码规范。开发人员只需在命令行输入自然语言指令，例如“为贷款产品增加一个‘复利周期’字段，包含前端校验和后端存储”，代理便会自动生成所需的数据库迁移文件、API 接口代码以及前端表单组件。

效果: 内部工具的开发迭代速度提升了 3 倍。开发人员不再需要手动编写 80% 的样板代码，从而能够专注于复杂的业务逻辑实现。由于代理遵循统一的代码风格，代码审查的时间也缩短了 50%，显著降低了因人为疏忽导致的 Bug 率。

2：SaaS 平台的遗留系统重构

2：SaaS 平台的遗留系统重构

背景: 一家拥有 5 年历史的 SaaS 企业，其早期产品中包含大量使用旧版本框架编写的业务逻辑。随着技术栈的升级（例如从 Angular.js 迁移到 React，或从 Python 2 升级到 Python 3），这些遗留代码成为了维护负担，但完全重写又耗时过长。

问题: 手动重构遗留代码风险高且枯燥乏味。工程师需要逐行阅读旧代码，理解其意图，然后在新框架中重新实现。这不仅效率低下，而且在转换过程中容易引入新的逻辑错误，导致系统不稳定。

解决方案: 技术团队部署了一个定制的极简编码代理，专门用于代码翻译。该代理被配置为“非交互式”，即它不会尝试理解复杂的业务背景，而是专注于将特定模式的旧代码语法转换为新语法。对于逻辑复杂的模块，代理会添加详细的 TODO 注释供人工确认，而对于简单的声明式代码，则直接进行转换。

效果: 该代理在两周内完成了原本需要两名工程师耗时三个月才能完成的基础代码迁移工作。通过让机器处理繁琐的语法转换，团队仅需处理代理标记的 20% 复杂逻辑节点。这不仅加快了技术栈的升级进程，还让团队在重构过程中保持了高昂的士气。

最佳实践

最佳实践指南

实践 1：明确并限制 Agent 的职责范围

说明: 构建一个"固执己见"（Opinionated）的 Agent 意味着它应该在特定领域内表现出色，而不是试图解决所有问题。通过明确限制 Agent 的职责范围（例如仅处理特定语言、特定框架或特定类型的任务），可以显著降低幻觉产生的概率，并提高输出质量。最小化的 Agent 专注于做对一件事，而不是做错所有事。

实施步骤:

  1. 在系统提示词中明确列出 Agent 的能力边界和禁止事项。
  2. 针对特定任务（如 “Refactoring Python code”）设计专门的 Agent，而不是构建通用的 “Full-stack Developer”。
  3. 当用户请求超出范围时，设计明确的拒绝或转接机制，而不是强行生成。

注意事项: 避免陷入"全能 Agent"的陷阱。范围越广，不可控因素越多，调试难度呈指数级上升。

实践 2：构建高度确定性的工作流

说明: AI 模型本质上是概率性的，但工程化的 Agent 应当追求确定性的输出。为了构建可靠的 Agent，必须将 LLM 视为工作流中的一个函数节点，而非整个系统。通过结构化的步骤（如：读取 -> 分析 -> 规划 -> 执行 -> 验证），可以减少模型随机性带来的不稳定性。

实施步骤:

  1. 将复杂的任务分解为线性的、步骤明确的流水线。
  2. 在每一步执行后增加验证逻辑，确保输出符合预期再进入下一步。
  3. 对于关键路径，尽量使用代码逻辑而非 LLM 逻辑（例如使用正则匹配而非让 LLM 提取字符串）。

注意事项: 不要过度依赖 LLM 的"推理能力"来弥补流程设计的缺陷。流程越清晰，结果越可控。

实践 3：实施小步快跑与原子化提交

说明: 在代码生成或修改过程中，一次性生成大量代码往往难以调试且容易出错。最佳实践是让 Agent 采取"小步快跑"的策略，每次只进行最小单位的原子性修改，并立即验证。这符合 DevOps 中持续集成的理念，能够快速定位问题。

实施步骤:

  1. 限制 Agent 每次操作的文件数量或代码行数。
  2. 强制要求 Agent 在每次修改后运行测试或构建脚本。
  3. 只有当前步骤验证通过后，才允许进行下一步修改。

注意事项: 确保每一步操作都是可回滚的。如果某一步失败，系统应能自动回退到上一个稳定状态。

实践 4：建立严格的反馈与验证闭环

说明: 没有反馈的 Agent 是盲目的。一个健壮的 Agent 必须具备自我检查和修正的能力。这不仅仅是指检查代码语法，更包括检查代码是否真正解决了用户的问题，以及是否符合项目的编码规范。

实施步骤:

  1. 在执行关键操作前，要求 Agent 先列出执行计划并请求用户确认。
  2. 利用 Linting 工具（如 ESLint, Pylint）或单元测试作为硬性约束，测试不通过则禁止提交。
  3. 设计"自我修正"循环，如果错误发生，自动将错误信息反馈给 LLM 进行修复。

注意事项: 验证逻辑应当独立于生成逻辑。不要相信 Agent 自己说的"我已修复"，要相信测试结果。

实践 5：优先使用工具而非提示词工程

说明: 虽然提示词工程很重要，但通过工具（Tools）赋予 Agent 能力往往比通过提示词"教" Agent 能力更可靠。例如，给 Agent 提供一个执行 Shell 命令的工具，比让 Agent 凭空猜测命令输出要准确得多。

实施步骤:

  1. 为 Agent 配置执行环境（如 Docker 容器），允许它实际运行代码而非臆测结果。
  2. 接入文件系统搜索工具（如 grep 或 ripgrep），而非依赖 LLM 的上下文窗口来查找文件。
  3. 使用特定的 API 客户端工具处理外部请求，而不是让 LLM 生成 HTTP 请求代码。

注意事项: 工具调用会增加延迟和成本，需要在"速度"和"准确性"之间找到平衡点。对于简单的确定性任务，优先使用传统代码逻辑。

实践 6：优化上下文管理策略

说明: LLM 的上下文窗口是有限的，且"迷失中间"（Lost in the Middle）现象会导致模型忽略长上下文中的关键信息。最小化 Agent 的关键在于高效地管理上下文，只提供最必要的信息。

实施步骤:

  1. 实施滚动上下文窗口：始终保留最新的 N 条消息和最相关的系统指令。
  2. 使用 RAG（检索增强生成）技术，仅根据当前任务检索相关的代码片段，而不是将整个代码库塞进 Prompt。
  3. 在系统提示词中明确区分"指令"（优先级高）和"背景信息"（优先级低）。

注意事项: 上下文不是越多

学习要点

  • 将复杂任务拆解为原子化步骤并强制按顺序执行，是防止 LLM 产生幻觉和逻辑混乱的最有效手段。
  • 在执行代码前先让模型生成完整的修改计划并交由用户确认，能极大降低不可逆操作带来的风险。
  • 限制上下文窗口的大小并仅保留最相关的代码片段，比将整个代码库塞入提示词更能提高生成准确度。
  • 构建高度专一化的单一功能 Agent，其表现往往优于试图解决所有问题的通用型全能 Agent。
  • 不要盲目信任模型的输出，必须通过沙箱环境或严格的语法检查来验证生成的代码是否能够运行。
  • 极简的系统提示词配合具体的指令示例，比冗长复杂的提示词工程更能获得稳定的结果。
  • 将 Agent 的核心逻辑与工具调用解耦，使其具备在不修改主程序的情况下扩展新工具的能力。

常见问题

1: 什么是 “Opinionated”（有主见/固执）的编程代理？

1: 什么是 “Opinionated”（有主见/固执）的编程代理？

A: 在软件开发中，“Opinionated” 指的是工具或框架强制开发者遵循特定的约定和工作流，而不是提供无限的灵活性。对于编程代理而言，这意味着该代理不是试图满足所有人的所有需求，而是针对特定的技术栈（如特定的语言、框架或项目结构）进行深度优化。它可能会强制执行特定的代码风格、目录结构或库选择，从而减少决策疲劳，并在其熟悉的领域内提供更高质量的代码生成和重构能力。

2: 为什么选择构建 “Minimal”（极简）的代理，而不是功能全面的通用型代理？

2: 为什么选择构建 “Minimal”（极简）的代理，而不是功能全面的通用型代理？

A: 构建极简代理的核心原因在于可控性和调试难度。功能全面的通用型代理（如某些全能型 Copilot）往往包含复杂的提示词链、多步推理和庞大的上下文，这使得当代理出错时，开发者很难定位是哪一环节出了问题。极简代理通常只关注单一任务（如“修复这个 bug”或“编写这个函数”），代码库小，逻辑清晰。这使得开发者能够更容易理解代理的输出逻辑，并在出现幻觉或错误时迅速修正。

3: 这种编程代理通常使用什么底层模型？

3: 这种编程代理通常使用什么底层模型？

A: 虽然文章可能基于特定的实验，但这类构建通常倾向于使用能力较强且上下文窗口较大的模型。常见的选择包括 GPT-4o 或 Claude 3.5 Sonnet。选择这些模型的原因在于，编写和修改代码需要极强的逻辑推理能力和对长上下文（例如整个文件的代码）的理解能力。极简代理的设计哲学允许开发者在不依赖极度复杂 RAG（检索增强生成）系统的情况下，直接利用模型本身的能力来处理任务。

4: 如何解决 AI 代理产生的代码幻觉或错误引用问题？

4: 如何解决 AI 代理产生的代码幻觉或错误引用问题？

A: 在构建此类代理时，通常采用以下几种策略来缓解幻觉问题：

  1. 上下文感知：确保代理在生成代码前，能够获取到项目中相关文件的完整内容，而不是仅依赖文件名或模糊的记忆。
  2. 小步迭代：将大任务分解为极小的步骤，每一步都生成代码并验证，而不是一次性生成整个应用。
  3. 严格的工具使用：强制代理使用 shell 命令或 LSP（语言服务协议）来验证符号是否存在，而不是“猜”函数名。

5: 在构建过程中，最大的技术挑战是什么？

5: 在构建过程中，最大的技术挑战是什么？

A: 最大的挑战通常在于上下文管理和状态同步。AI 模型是无状态的，但代码编辑是有状态的。如何让代理知道它刚刚修改了哪一行代码，或者如何让代理理解它的修改导致了其他文件的引用错误，是非常困难的。极简代理往往通过限制操作范围（例如每次只操作一个文件）来规避复杂的状态同步问题，但这同时也限制了其处理跨文件复杂重构的能力。

6: 这种自建的代理与现有的商业产品（如 GitHub Copilot）相比有何优劣？

6: 这种自建的代理与现有的商业产品（如 GitHub Copilot）相比有何优劣？

A:

  • 优势：完全的可定制性和透明度。你可以确切知道代理发送给模型的提示词是什么，可以针对个人独特的编码习惯进行微调，且不需要支付商业软件的订阅费（仅需支付 API 费用）。此外，它没有数据隐私方面的顾虑，代码不会发送给第三方厂商训练。
  • 劣势：易用性和稳定性。商业产品经过了大量的工程化打磨，拥有更好的默认体验和错误处理机制。自建的极简代理往往需要用户具备一定的调试能力，当代理卡死或输出格式错误时，需要人工干预。

7: 普通开发者应该如何开始构建自己的编程代理？

7: 普通开发者应该如何开始构建自己的编程代理？

A: 建议从“脚本化”开始，而不是直接构建一个复杂的 Agent 系统。

  1. 定义单一任务：例如，“自动为我的代码生成单元测试”。
  2. 编写简单的 Prompt：将当前文件的代码作为上下文传递给模型。
  3. 处理输出：编写脚本将模型的输出解析并写回文件或直接在终端显示。 通过这种最简化的 MVP（最小可行性产品）入手，理解模型如何与代码交互，然后再逐步引入循环、多步推理等复杂特性。

思考题

## 挑战与思考题

### 挑战 1: 提示词的极简与固执平衡

问题**：在构建一个最小化的编码代理时，如何设计一个系统提示词，使其既能保持“固执己见”的风格，又能严格遵守“最小化”原则，避免生成不必要的代码或解释？

提示**：考虑在提示词工程中如何使用约束性语言。思考如何明确界定代理的“拒绝”边界，即当用户提出什么类型的需求时，代理应该拒绝生成代码。可以尝试对比“乐于助人的助手”与“极简主义专家”在指令设定上的区别。

引用

注：文中事实性信息以以上引用为准；观点与推断为 AI Stack 的分析。

站内链接

相关文章