面向软件工程师的编码代理

Source: Dev.to

请提供您希望翻译的具体文本内容，我将按照要求保持原有的格式、Markdown 语法以及技术术语，仅翻译正文部分。谢谢！

1️⃣ 什么是编码代理？

A coding agent is not just an LLM. It is a system:

IDE / CLI
    ↓
Agent Runtime
    ↓
Context Builder
    ↓
LLM Inference
    ↓
Tool Execution (fs, git, tests, shell)
    ↓
Loop

• The model is only the reasoning engine.
• The runtime handles orchestration.

2️⃣ 编码代理的通用架构

一个生产级别的编码代理包括：

1. 索引层

   • 仓库扫描
   • 符号提取
   • 依赖图
   • 可选的嵌入

2. 上下文构建器

   • 选择相关文件
   • 注入指令
   • 添加计划 / 速记本
   • 添加最近的编辑

3. LLM 推理层

   • 已分词的提示
   • 上下文窗口约束
   • 流式输出

4. 工具层

   • 文件读取/写入
   • 测试执行
   • Git diff/patch
   • Lint / 构建命令

5. 循环控制器

   • 计划
   • 执行
   • 验证
   • 迭代

模型并 不 “看到仓库”。代理自行决定发送哪些内容。

3️⃣ 什么是上下文窗口？

上下文窗口是模型在单次推理调用中能够关注的最大 token 数量。它包括：

System instructions
+ AGENTS.md / policies
+ Scratchpad / plan files
+ Relevant source files
+ Recent conversation
+ Tool outputs
+ Your current request
+ Model output

所有内容必须适配在窗口内。更大的窗口 并不 意味着你应该发送所有内容。

4️⃣ Tokenization 在哪里发生？

通常情况下：

• 代理运行时在本地（客户端）进行 token 化。
• 在调用模型之前，它会估算 token 使用量。
• 服务器在推理过程中仍然会处理 token。

为什么客户端 token 化很重要

• 避免超出上下文限制
• 控制成本
• 控制分块
• 优化文件选择

5️⃣ 实际消耗 Token 的是什么？

在编码工作流中，Token 成本通常来源于：

• 大型源文件
• 测试文件
• 日志
• 重放的对话历史
• 重复的系统指令
• 草稿本增长

你的指令冗长很少是主要成本——文件选择才是关键。

6️⃣ 什么是“高质量”上下文？

Good context is:

• ✅ Relevant – only include files that matter. – 只包含重要的文件。
• ✅ Structured – clear task → constraints → deliverable. – 清晰的任务 → 约束 → 可交付物。
• ✅ Deterministic – explicit scope boundaries. – 明确的范围边界。
• ✅ Minimal but sufficient – no narrative fluff, no repeated architecture explanation. – 最小但足够——没有冗长的叙述，没有重复的架构说明。

Bad context includes:

• Entire repo dump – 整个仓库的全部导出
• Long emotional explanations – 冗长的情感化解释
• Old irrelevant chat history – 过时的无关聊天记录
• Ambiguous instructions – 模糊的指令

7️⃣ 实际上什么能提升编码响应？

1️⃣ 清晰的范围

Bad: “Improve authentication system.”

Good:

Scope:
- src/auth/*
- src/middleware/auth.ts
Do not touch:
- public API
- schema definitions

2️⃣ 明确的约束

示例：

• 不要更改公共接口。
• 保持测试行为不变。
• 不添加新依赖。
• 保持差异最小化。

约束可以减少幻觉式的重构。

3️⃣ 定义的输出格式

Deliverable:
- Unified diff only
- Brief explanation (The model does **not** remember it; the agent injects it into context each time.)

9️⃣ 高效的编码代理项目结构

Recommended layout:

/AGENTS.md        # Global behavior rules (minimal)
/PLAN.md          # Task plan (editable)
/src/...
/tests/...

AGENTS.md 应包含

• 编码规范
• 测试命令
• “先计划”规则
• 防护措施

保持简短；它会经常被注入。

🔟 高效编码代理使用模式

模式 A — 受限补丁

Task:
Optimize middleware performance.

Scope:
src/auth/middleware.ts

Constraints:
- Preserve API
- No new deps

Output:
Unified diff only.

模式 B — 增量执行

Implement only Step 1 from PLAN.md.
Run tests.
Update PLAN.md.
Stop.

模式 C — 范围锁定

显式限制目录：

Touch only:
src/auth/*
Do not modify:
src/db/*

这可以防止令牌浪费和意外编辑。

1️⃣1️⃣ 什么不该做

• ❌ 发送整个仓库
• ❌ 每次都重新解释系统架构
• ❌ 让草稿本无限增长
• ❌ 让范围不明确
• ❌ 要求“改进所有”

1️⃣2️⃣ 大上下文神话

1 M 令牌的上下文窗口 并不意味着你应该发送 1 M 令牌，也不意味着它会更快或更准确。

更长的上下文：

• 增加延迟
• 增加成本
• 增加噪声风险

智能的上下文选择胜过单纯的大小。

1️⃣3️⃣ 工程师的思维模型

把编码代理视作如下：

LLM = Stateless reasoning engine
Context = Input data packet
Agent = Orchestrator
Scratchpad = External memory

你的任务：优化数据包。

---

1️⃣4️⃣ 核心优化原则

• 结构 > 冗长
• 相关性 超过 纯粹的数量

完整性

• 约束 > 自由
• 迭代 > 大型提示
• 计划 → 执行 → 验证

最终要点

• 任务范围明确
• 约束条件明确
• 上下文经过筛选
• 计划已外部化
• 历史已裁剪
• 输出格式受限