大海
154 lines
3.7 KiB
Markdown
154 lines
3.7 KiB
Markdown
# 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`（抽象层）。其他的都是辅助。
|
||
|
||
---
|
||
|
||
*小龙学习笔记 🐉*
|