题目 1:为什么 Coding Agent 进入陌生项目以后应该优先扫描 Workspace 和读取 AGENTS.md,而不是直接修改代码?
因为陌生项目的目录结构、测试方式、运行版本和修改约束都未知。直接改代码意味着模型在猜。先扫描 Workspace 可以知道真实文件和目录,读取 AGENTS.md 可以知道不能修改 tests/、是否允许新增依赖、测试命令是什么。这样后续 Tool Call 才有明确边界,也能避免“技术上修好了、项目规则却违反了”的情况。
题目 2:为什么 Coding Agent 的 Completion Criteria 不能只有“模型说完成了”或“局部测试通过”?
模型可能提前结束,也可能没有执行证据却声称成功;局部测试通过也不代表整个项目没有回归。更可靠的 Completion Gate 应检查目标 Bug 是否解决、要求的相关测试和全量测试是否通过、AGENTS.md 与用户约束是否满足、是否还有 pending approval。只有这些条件都满足,Run 才应该进入 COMPLETED。
题目 3:编程实现——定义一个最小 CodingState,包含 run_id、goal、modified_files 与 full_tests_passed。
from dataclasses import (
dataclass,
field,
)
@dataclass
class CodingState:
run_id: str
goal: str
modified_files: list[str] = field(
default_factory=list
)
full_tests_passed: bool = False
if __name__ == "__main__":
state = CodingState(
run_id="run_demo",
goal="修复 pytest 失败",
)
state.modified_files.append(
"calculator.py"
)
state.full_tests_passed = True
print(state)
#真实系统还会继续保存 step、status、current_error、project_rules、tool_history 和 Working Memory。
题目 4:为什么 read_file、edit_file、run_pytest 这种窄 Tool 通常比万能 run_shell 更适合 Coding Agent?
窄 Tool 的能力边界更清晰,可以单独做 Path Validation、权限判断、参数 Schema、风险等级和 Trace。比如 edit_file 可以明确保护 tests/,run_pytest 可以固定执行 pytest 而不开放任意 Shell。万能 run_shell 虽然灵活,但能读写文件、联网、启动任意程序,攻击面更大,也更难审计。生产 Agent 更适合默认使用窄 Tool。
题目 5:测试错误从 ImportError 变成 TypeError,Agent 应如何理解这种变化?
错误类型变化通常意味着系统状态发生了进展:原来的 ImportError 可能已经被解决,执行继续深入后暴露新的 TypeError。Agent 不应该简单认为“修改失败了”,而应更新 Working Memory 中的 current_error,读取新的 traceback,重新定位相关代码。Trace 也应该保留错误签名变化,帮助后续判断每次修改是否产生实质进展。
题目 6:为什么 Flask Route 不应该直接承载完整 Agent Main Loop?
Flask Route 应主要负责 HTTP 请求解析、参数校验和调用 AgentService。真正 Main Loop、Tool Registry、ContextBuilder、Memory、Trace 等逻辑如果全塞在 Route 中,会难以复用到 CLI、定时任务、飞书或其他入口,也不利于测试。更成熟的架构是 Flask → AgentService → AgentEngine → Harness,各层职责清晰。
题目 7:如何把一次 Coding Agent 失败转化成长期系统能力?
先通过 Trace 找到 First Bad Step,判断属于 Context、Decision、Arguments、Tool、Recovery、Policy 或 Termination 哪一层;修复对应模块后,把失败任务加入 Regression Benchmark,并定义明确 Success Criteria,例如 tests/ 不得变化、pytest 必须通过。以后每次更换模型、Prompt、Skill 或 Tool,都自动重跑这个任务,防止问题回归。
进一步阅读
- Coding Agent Architecture:理解 Agent Engine、Tool Registry、Workspace 与 Test Runner 的组合。
- Patch Validation:代码修改以后如何做静态检查、单测和全量测试。
- Git Diff Analysis:未来如何让 Agent 用结构化 Diff 做修改审计。
- Sandboxed Code Execution:真实代码执行为什么应该放在更强隔离环境。
- Regression Benchmark:把真实 Bug Case 变成长期测试任务。
- Project Rules:AGENTS.md 如何约束真实 Coding Agent。
- AgentOps:Tracing、Metrics 和 Evaluation 如何进入完整项目。
- Background Execution:长时间 Agent Run 如何从同步 Flask 升级为异步 Worker。
术语表
- Coding Agent:围绕代码理解、修改、测试和验证形成闭环的 Agent,不只是一次代码生成,而是多步受控执行系统。
- Project Scan:Agent 进入陌生项目后读取目录结构、配置文件和项目规则的初始阶段。
- Baseline Test:在修改代码之前先运行测试,用于复现当前错误并建立修复前基线。
- Completion Gate:Run 进入 COMPLETED 前进行的确定性检查,例如全量测试、项目规则和审批状态是否满足。
- Modified Files:当前 Run 中真正发生修改的文件集合,应进入 Working Memory、Trace 和最终报告。
- Error Signature:用于表示当前失败类型和关键错误信息的结构,可用于判断失败是否重复或发生变化。
- Project Policy:由 AGENTS.md 等项目规则解析得到的可执行约束,例如禁止修改 tests/、禁止新增依赖。
- Coding Harness:围绕 LLM 决策层提供 Tool、Workspace、Memory、Trace、Safety、Run 和 Evaluation 的完整执行框架。
本章总结
这一章,我们终于把整门课程前面学到的组件真正组装成了一个完整的 Coding Agent。
任务非常清楚,给 Agent 一个陌生 Python 项目,让它自动定位并修复 Bug。
完整链路是:
用户提交任务
↓
扫描项目
↓
读取 AGENTS.md
↓
查找相关文件
↓
读取代码
↓
运行测试
↓
分析报错
↓
修改代码
↓
再次测试
↓
测试通过
↓
输出修改报告
这一章最重要的第一条原则是,陌生项目先观察,再行动。
Coding Agent 进入 Workspace 后,第一件事不是改代码。
而是:
确认 Workspace
读取 AGENTS.md
扫描项目
复现错误
只有拿到真实 Observation,后续修改才有依据。
第二条原则是,LLM 负责决策,Harness 负责执行。
模型可以说:
下一步读 calculator.py。
真正读取文件的是:
read_file Tool。
模型可以说:
把 return a - b 改成 return a + b。
真正修改的是:
edit_file Tool。
模型可以判断:
应该运行测试。
真正执行的是:
run_pytest。
这就是 Agent 与纯代码生成的核心区别。
第三条原则是,Coding Agent 必须有项目规则意识。
AGENTS.md 不是装饰。
像:
禁止修改 tests/
禁止新增依赖
必须 pytest
会直接决定:
什么动作允许
什么动作禁止
什么条件才算完成
第四条原则是,测试不是最后的附加动作,而是 Main Loop 的核心 Observation。
Coding Agent 的执行链其实非常像:
修改
↓
测试
↓
观察
↓
再修改
测试结果会不断改变 Agent 的下一步策略。
如果错误从:
ImportError
变成:
TypeError
说明系统状态已经发生变化。
Agent 应该基于新的 Error Signature 继续,而不是机械重复旧策略。
第五条原则是,最终完成必须经过 Completion Gate。
不能只听模型说:
“我完成了。”
Harness 至少应该检查:
全量测试通过
项目规则满足
没有未决审批
没有明显违规修改
只有通过以后:
Run → COMPLETED
第六条原则是,真正可维护的 Coding Agent 一定要有 Trace。
用户最终不只需要:
修好了。
还需要知道:
根因是什么
改了哪些文件
为什么这样改
测试跑了什么
结果是什么
有没有违反项目规则
所以最终报告应该建立在真实 Trace 和 Tool Result 上。
第七条原则是,Flask 只是服务入口,不是 Agent 本身。
成熟架构应该是:
Client
↓
Flask
↓
AgentService
↓
AgentEngine
↓
ContextBuilder
↓
LLM Provider
↓
Tool Registry
↓
Middleware / Sandbox
↓
Workspace
↓
Trace / Memory
这样同一个 AgentEngine 才可以未来同时服务:
Web
CLI
飞书
定时任务
内部平台
到这里,我们已经拥有一个真正完整的 Coding Agent 设计。
它不再只是:
LLM
+
Shell
而是:
Python
+
Flask
+
LLM
+
Tool Registry
+
Memory
+
Tracing
+
Workspace
+
AGENTS.md
+
Safety
+
Evaluation
组成的完整 Harness。
下一节,我们会做第二个完整项目,从 0 打造 Data Analysis Agent。
它和 Coding Agent 最大区别是:
Coding Agent
→ 围绕代码、测试、修改形成闭环
Data Analysis Agent
→ 围绕指标、查询、Observation、下钻形成闭环
用户只需要问,“为什么昨天收入突然下降?”
Agent 就要自己:
理解问题
查询整体指标
判断异常
选择下钻方向
再次查询
收集证据
判断是否继续
输出结论
这会让我们真正看到,Agent 相比传统 Text-to-SQL,多出来的到底是什么。

















请登录后查看评论内容