16gagent/research/claude-code-learnings.md

Claude Code 学习笔记 - 可落地部分

从 fazxes/Claude-code 提取的实战精华
适用于构建自己的 AI Agent / 编程助手 2026-05-30 小龙 🐉

---

一、提示词设计十大准则

1. 人格一句话定义身份

你是X。用Y方式。注意Z。

→ 不要啰嗦。没人读长介绍。

2. 行为约束用否定句

❌ "请帮助用户" → 空洞
✅ "不要增加需求以外的功能" → 有执行力

• 不要加功能、不要重构、不要注释——这些否定限制才是真正有用的 prompt

3. 工具优先级显式声明

专用工具 > Bash：
FileRead 代替 cat
FileEdit 代替 sed
Glob 代替 find

→ 不说"合理使用工具"，直接说"用X不要用Y"

4. 风险分层锁定行动范围

可逆本地 → 自由
中等 → 确认
不可逆 → 绝对确认

→ 模糊的"小心操作"不如分层的具体规则

5. 错误处理要内嵌法

如果失败 → 诊断 → 修正 → 重试
如果3次失败 → circuit breaker → 报告用户
如果权限被拒 → 换方案，不重复尝试

→ 不赌模型能自己判断好所有场景

6. 诚实优先于体面

"测试没有通过" > "部分测试可能有轻微问题"
"我没做验证" > "看起来应该可以"

→ 模型天然倾向于讨好用户，要刻意压制

7. Feature Flag 门控

if (feature('UNRELEASED')) {
  // 只有内部构建才生效
}

→ 所有未发布功能用 feature flag 开关，泄露也不怕

8. 上下文注入机制

CLAUDE.md + MEMORY.md + frontmatter paths

→ 在系统提示词中注入项目知识，让AI"理解"项目

9. 流式输出 + 异步使用

文本 → 即时输出
tool_use → 走权限流程 → 异步执行

→ 不让用户等

10. 自动压缩 + 记忆保持

消息接近窗口 → 压缩旧消息为摘要
关键决策 + 未完成任务 → 保留

→ context window 管理是 agent 产品的核心壁垒

---

二、工具架构最佳实践

工具定义范本

class MyTool extends Tool {
  // 1. 描述给模型看（决定模型会不会用它）
  description(): string { return "..." }
  
  // 2. 输入 Schema（模型按这个填参数）
  inputSchema = z.object({ ... })
  
  // 3. 提示词注入（告诉模型什么时候用）
  prompt = "..."
  
  // 4. 权限检查（自动/手动/拒绝）
  checkPermissions(input, context): PermissionResult
  
  // 5. 执行逻辑
  call(input, context): ToolResultBlockParam[]
}

工具设计原则

• 每个工具一个目录，包含 constants/prompt/tool 三个文件
• 工具间可感知 — Bash读过的 FileEdit 知道，不重复操作
• 工具可以被搜索 — ToolSearchTool 让模型自己发现工具
• 并行调用最大化 — 没有依赖的工具调用全部并行

---

三、Hook 系统模式

事件驱动架构

触发 → Pre Hook → 执行 → Post Hook → 继续

Hook 返回值决定行为

Hook 返回 "继续" → 正常执行
Hook 返回 "拒绝" → 工具不执行
Hook 返回 "修改" → 用修改后的参数执行

Hook 配置格式

{
  "hooks": {
    "PreToolUse": [
      {"matcher": "Bash.*", "hooks": [{"command": "check.sh"}]}
    ]
  }
}

---

四、最重要的是什么

提示词工程 > 工具数量 > UI精致度

Claude Code 真正值钱的是 prompts.ts 里那176条原则，不是45个工具。工具只是手脚，提示词是大脑。

拿到任何一个 AI Agent 源码，第一件事读 prompts.ts，第二件事读 query.ts（对话循环），第三件事看 Tool.ts（抽象层）。其他的都是辅助。

---

小龙学习笔记 🐉