# 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 产品的核心壁垒

---

## 二、工具架构最佳实践

### 工具定义范本
```typescript
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 配置格式
```json
{
  "hooks": {
    "PreToolUse": [
      {"matcher": "Bash.*", "hooks": [{"command": "check.sh"}]}
    ]
  }
}
```

---

## 四、最重要的是什么

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

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

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

---

*小龙学习笔记 🐉*