Agentic Coding 第一性原理笔记

一、LLM 的本质

大语言模型的工作方式可概括为：预测下一个 token。

自回归生成过程：

计算当前位置与上下文中每个位置的相关程度
相关性高的位置获得更高权重，形成概率分布
根据权重加权聚合上下文信息，预测下一个 token

关键需求：

提供清晰的成功标准（明确的奖励信号）
允许试错，观察模型的决策模式

二、Coding Agent 的典型工具

文件操作：read_file、write_file、edit_file（支持局部编辑）
代码执行：shell/terminal（运行命令、安装依赖、执行测试）
代码搜索：grep/search（文本/模式搜索）、semantic_search（语义搜索）
项目导航：list_directory、find_files

工具的粒度、参数设计、返回格式直接决定 Agent 的能力边界。

三、常见挑战与解决方案

1. 会话间失忆

现象：会话之间无持久记忆。
方案：
- 使用结构化任务追踪（如 issue tracker）
- 会话结束生成状态摘要，供下次使用
- 将重要决策和发现记录在固定位置（而非对话历史）

2. 上下文窗口耗尽

方案：
- 精简工具输出，返回摘要或相关片段
- 简化工具 schema，避免深度嵌套结构
- 将大任务分解为子任务，每个使用新上下文

3. 有效上下文远小于标称值

即使 1M token 窗口，实际有效利用仅 10-15%。
「Dumb Zone」：窗口中间 40-60% 区域召回率下降、推理变差（Lost in the Middle）。
策略：将上下文利用率控制在 15% 以内可显著缓解。

4. 新发现的任务被丢弃

现象：LLM 发现问题但上下文紧张时选择忽略。
方案：
- 提供外部工具，让 Agent 随时记录发现
- 任务结束时要求列出未处理的问题
- 建立“发现即记录”的流程

5. 过早宣告完成

方案：
- 将整体计划保存在上下文外的固定位置
- 定期对照原始计划检查进度
- 使用结构化任务追踪，而非依赖 Agent 记忆

四、最佳实践

1. 短对话优于长对话

核心原则：保持对话简短、专注，每个对话只做一件事。

以对话为工作单位：

功能：用户登录后的会话管理
[对话1] 调研现有代码结构 → 输出关键文件列表
[对话2] 实现基础功能 → 核心 session 保存逻辑
[对话3] 添加错误处理 → 边界情况处理
[对话4] 编写测试 → 单元测试与集成测试
[对话5] 代码审查 → 检查规范与安全
[对话6] 清理与重构 → 根据审查调整

对话间上下文共享：
- 引用之前对话的结论
- 利用 Git 状态（查看 diff 或提交记录）
- 将决策记录在 AGENTS.md 等文件
- 直接 #mention 相关文件

不要在一个对话完成所有事；当任务完成或对话混乱时，立即开始新对话。

2. 编写有效的项目配置文件

回答三个问题：WHAT（技术栈/结构）、WHY（设计决策）、HOW（运行/测试命令）

少即是多：前沿模型可靠遵循约 150-200 条指令，Agent 系统提示已占用约 50 条。

✅ 简洁 + 指向详细文档
❌ 塞满所有规范细节

渐进式披露：

agent_docs/
├── building_the_project.md
├── running_tests.md
├── code_conventions.md
├── service_architecture.md
└── database_schema.md

偏好指针而非副本：用 file:line 引用权威代码位置，避免文档中嵌入过时代码片段。

不要让 Agent 做 Linter 的工作：代码风格应交由自动化工具，不写进配置文件。

花费时间仔细考量配置文件的每一行，是 ROI 最高的投资之一。

3. 实践建议

对话超过 80K-100K token → 开始新对话
完成独立子任务后 → 开始新对话
Agent 出现“醉酒”症状（重复、遗忘、偏离目标） → 立即开始新对话
将“开始新对话”视为正常流程，而非失败重试

五、Compounding Engineering（复利工程）

核心理念：不只是在解决问题，而是在教育系统。每个 PR、bug、代码审查都应成为永久教训，更新 Agent 的默认行为。

实践方式

将经验沉淀到项目文档
AGENTS.md 示例：

## 代码风格
- 使用 async/await 而非 Promise.then()
- 错误处理必须包含具体错误类型
- 变量命名遵循 PR #234 的模式

## 已知陷阱
- session 模块的 save() 是异步的，必须 await
- 不要在循环中调用 API，使用批量接口

## 成功模式
- 新增 API 端点，参考 PR #241 的错误处理
- 测试覆盖率要求参考 PR #219 的反馈

Bug 修复产生长期价值
- 添加 lint 规则预防
- 在 Rules/AGENTS.md 中记录陷阱
- 编写测试防止回归
- 更新代码审查清单
代码审查中提取模式
- 反馈是否适用于未来代码？→ 记录为编码规范
- Agent 下次能否自动应用？→ 固化知识

建立可复用工作流程

## 工作流程：添加新 API endpoint
1. 先编写接口测试（参考 tests/api/example.test.ts）
2. 实现端点，遵循 src/api/users.ts 的模式
3. 添加错误处理，使用 AppError 类
4. 更新 API 文档
5. 运行完整测试套件验证

值得投资的开发者体验

文档：架构决策记录（ADR）、API 使用示例、已知陷阱和常见错误
代码结构：清晰命名、单一职责、显式依赖
反馈速度：极致快速反馈，减少无效上下文堆积
快速校验脚本：组合类型检查、lint、局部测试，几秒出结果
就近文档：模块目录下放 README，Agent 直接读取
结构化错误信息：报错带原因、示例、参考文档

六、用工程约束“驯服”Agent

1. 强制执行标准（pre-commit hook）

#!/bin/bash
# .git/hooks/pre-commit
echo "Running type check..."
npm run typecheck || exit 1
echo "Running linter..."
npm run lint || exit 1
echo "Running tests..."
npm test || exit 1
echo "All checks passed!"

2. 拦截“偷懒”行为

Agent 可能尝试 git commit --no-verify 绕过检查，使用 wrapper 脚本拦截并给出明确指引：

$ git commit --no-verify
 ERROR: Commit Rejected.
 GUIDANCE FOR THE AI AGENT:
 You have attempted to bypass the required pre-commit verification.
 All code must pass quality checks before it can be committed.
 DO NOT BYPASS THE CHECKS. YOU MUST FIX THE UNDERLYING ERRORS.
 ...attempt the commit again *without* the '--no-verify' flag.

3. 设计 AI 友好的错误信息

格式：[错误代码] 错误原因 + 具体数据 + 怎么解决 + 文档位置

❌ throw new Error("Something went wrong")
✅ throw new Error("[AUTH_TOKEN_EXPIRED] 令牌已过期，过期时间：2024-01-15T10:30:00Z。请调用 refreshToken() 刷新。参考文档：docs/auth.md#token-refresh")