🎉 init: 小龙的工作空间

research/claude-code-learnings.md

@@ -0,0 +1,153 @@
+# 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`（抽象层）。其他的都是辅助。
+
+---
+
+*小龙学习笔记 🐉*