┌───────────────────────────────────────────┐
│         编程层 (Programming Layer)         │
│   BashTool, EditTool, ReadTool,          │
│   WriteTool, WebSearch, WebFetch...      │
├───────────────────────────────────────────┤
│         集成层 (Integration Layer)         │
│   Harness Agentic Loop                   │
│   上下文组装 → LLM推理 → 工具调用 → 结果注入  │
├───────────────────────────────────────────┤
│         扩展层 (Extension Layer)           │
│   Skills · MCP · Hooks · Plugins         │
│   SlashCommands · Custom Agents         │
├───────────────────────────────────────────┤
│         记忆层 (Memory Layer)              │
│   CLAUDE.md 五层体系 · 条件化规则          │
│   项目记忆 · 个人记忆 · 对话记忆           │
└───────────────────────────────────────────┘

Harness Agentic Loop:
┌───────┐    ┌───────┐    ┌───────┐    ┌───────┐
│ 上下文  │ → │ LLM   │ → │ 工具   │ → │ 结果   │
│ 组装    │    │ 推理   │    │ 调用   │    │ 注入   │
└───────┘    └───────┘    └───────┘    └───┬───┘
                    ↑                       │
                    └───────────────────────┘
                       (循环直到任务完成)

my-project/
├── CLAUDE.md              # 项目级记忆（提交到 Git）
├── .claude/
│   ├── skills/            # 项目专属 Skills
│   │   ├── react-patterns.md
│   │   └── api-design.md
│   ├── hooks/             # 项目 Hooks（可选）
│   └── settings.json      # 项目级设置
├── .gitignore             # 确保不提交敏感记忆
└── src/                   # 你的源代码

# 项目记忆

<span style="font-size:0.5pt;">§TOC0-5§</span>
## 技术栈
- 前端：React 18 + TypeScript + Vite
- 后端：Node.js 20 + Express
- 数据库：PostgreSQL 15

<span style="font-size:0.5pt;">§TOC0-6§</span>
## 编码规范
- 使用函数组件 + Hooks，不使用 Class 组件
- 类型定义放在 `types/` 目录
- API 路由统一前缀 `/api/v1`

<span style="font-size:0.5pt;">§TOC0-7§</span>
## 项目约束
- Node.js 版本 >= 20.0.0
- 所有 API 必须返回 JSON 格式
- 单元测试覆盖率 > 80%

[用户输入] "帮我在 src/utils/format.ts 里加一个 formatPhoneNumber 函数"

Harness 上下文组装阶段 (Context Assembly):
├─ 从五层记忆体系收集 CLAUDE.md 规则
├─ 加载可用 Skills 的 description 列表
├─ 加载可用工具的函数签名清单
├─ 附加当前对话历史（含之前的工具调用结果）
└─ 拼装为完整的 system prompt + user message
    → 总 token: ~3500

LLM 推理阶段 (LLM Inference):
├─ 模型分析任务：需要读取文件 → 理解现有代码 → 编写新函数
├─ 生成第一个工具调用：Read(file_path="src/utils/format.ts")
└─ 注意：模型只声明工具调用，不执行

Harness 工具执行阶段 (Tool Execution):
├─ 解析模型输出的工具调用
├─ 匹配到 ReadTool
├─ 读取 src/utils/format.ts
├─ 将文件内容封装为 tool_result
└─ tool_result 注入到对话历史

[第二轮]
Harness 上下文组装:
├─ 所有 CLAUDE.md + Skills 再次注入（注意：这是每次必做的）
├─ 对话历史：用户消息 + Read 调用 + Read 结果
└─ 总 token: ~4200（增加了文件内容）

LLM 推理:
├─ 分析 format.ts 的代码风格和现有函数模式
├─ 生成 Edit 调用：在文件末尾插入 formatPhoneNumber 函数
└─ 使用 fuzzy matching 策略确定插入位置

Harness 工具执行:
├─ EditTool 使用 patch 模式
├─ 9 种 fuzzy matching 策略依次尝试，找到最佳匹配位置
├─ 执行编辑
└─ tool_result 注入对话历史

[第三轮]
LLM 推理:
├─ 检查编辑结果
├─ 认为任务完成
└─ 无工具调用，循环终止

工具调用 → Harness 权限检查
├─ 白名单工具（Read, Grep, Glob） → 自动执行
├─ 灰名单工具（Edit, Write, Bash*） → 根据权限模式决定
│   ├─ default mode: 首次使用需用户确认，后续自动
│   ├─ acceptEdits mode: 编辑自动，命令需确认
│   ├─ bypassPermissions mode: 全部自动（CI/CD 等信任环境）
│   └─ plan mode: 全部阻止，只展示计划
└─ 黑名单（无） → Claude Code 没有硬编码的黑名单工具

┌──────────────────────────────────────────────────┐
│  CLI  │ Desktop │ VS Code │ JetBrains │ Web      │  ← 端层（UI壳）
├──────────────────────────────────────────────────┤
│              统一 Harness 引擎                      │  ← 引擎层（核心）
├──────────────────────────────────────────────────┤
│  CLAUDE.md │ Skills │ Hooks │ MCP │ Plugins      │  ← 配置层（数据）
└──────────────────────────────────────────────────┘

场景：一个全栈功能的开发日

早上 9:00  VS Code 端:
  └─ 在编辑器中打开项目，用 Claude Code 插件生成初始代码框架

上午 10:30  CLI 端:
  └─ 在终端中运行 claude，让 Agent 执行批量重构
  └─ 利用 CLI 的 headless 模式自动处理 14 个文件的模式替换

下午 2:00  Desktop 端:
  └─ 打开 Desktop 应用，与 Claude 进行交互式调试
  └─ 利用视觉反馈能力查看图表和架构图

下午 4:00  JetBrains 端:
  └─ 在 IntelliJ 中打开后端代码，利用 Claude Code 插件优化 Java 代码

全天   同一个引擎 + 同一套 CLAUDE.md + 同一组 Skills

[用户输入] "帮我在 src/utils/format.ts 里加一个 formatPhoneNumber 函数"

━━━ 第一轮 ━━━

【阶段1: 上下文组装 (Context Assembly)】
Harness 收集:
├─ 五层记忆体系中的 CLAUDE.md 规则
├─ 可用 Skills 的 description 列表
├─ 可用工具的函数签名清单
├─ 当前对话历史（含之前的工具调用结果）
└─ 拼装为完整的 system prompt + user message
    → 总 token: ~3500

【阶段2: LLM推理 (LLM Inference)】
模型分析任务:
├─ 需要读取文件 → 理解现有代码 → 编写新函数
├─ 生成工具调用: Read(file_path="src/utils/format.ts")
└─ 注意: 模型只声明工具调用，不执行

【阶段3: 工具执行 (Tool Execution)】
Harness 执行:
├─ 解析模型输出的工具调用
├─ 匹配到 ReadTool
├─ 读取 src/utils/format.ts
├─ 将文件内容封装为 tool_result
└─ tool_result 注入到对话历史 → 进入下一轮

━━━ 第二轮 ━━━

【阶段1: 上下文组装】
├─ 所有 CLAUDE.md 再次注入（每轮必做！）
├─ 对话历史: 用户消息 + Read调用 + Read结果
└─ 总 token: ~4200（增加了文件内容）

【阶段2: LLM推理】
├─ 分析 format.ts 代码风格和现有函数模式
├─ 生成 Edit 调用: 在文件末尾插入 formatPhoneNumber 函数
└─ 使用 fuzzy matching 策略确定插入位置

【阶段3: 工具执行】
├─ EditTool 使用9种fuzzy matching策略定位
├─ 执行编辑
└─ tool_result 注入对话历史 → 进入下一轮

━━━ 第三轮 ━━━

LLM推理:
├─ 检查编辑结果
├─ 认为任务完成
└─ 无工具调用 → 循环终止

工具调用 → Harness 权限检查
├─ 读操作（Read, Grep, Glob） → 自动执行
├─ 写操作（Edit, Write）      → 根据权限模式决定
├─ 命令执行（Bash）           → 根据权限模式决定
└─ 网络操作（WebSearch等）    → 根据权限模式决定

优先级从低到高 ↓  （高优先级覆盖低优先级）

第1层  AUTO.md          — 自动生成，Claude 自我总结的对话记忆
第2层  CLAUDE.md        — 项目根目录，团队共享的公共规则（提交到 Git）
第3层  .claude/CLAUDE.md— 本地覆盖，个人加入但不提交的规则（.gitignore）
第4层  项目级记忆        — 通过 /memory 命令写入的项目持久记忆
第5层  个人级记忆        — 跨项目的用户全局记忆（~/.claude/CLAUDE.md）

# AUTO.md (自动生成示例)
- 用户偏好使用 pnpm 而非 npm
- 项目使用 Vitest 做测试，配置文件在 vitest.config.ts
- API base URL 是 https://api.example.com/v2

# 个人偏好
- 我的本地数据库端口是 5433（不同于团队默认的 5432）
- 我的 npm registry 使用公司内部镜像

# 老王的工作偏好
- 代码注释使用中文
- 变量命名偏好驼峰式（camelCase）
- 错误处理喜欢 early return 模式
- 测试框架偏好 Vitest（前端）和 Jest（后端）

合并示意：

第5层(个人): "使用 pnpm" + "注释用英文"
第2层(项目): "使用 yarn" + "缩进用2空格"
第3层(本地): "缩进用4空格"  ← 个人本地覆盖

最终结果: "使用 yarn" + "注释用英文" + "缩进用4空格"
         (项目yarn覆盖了个人pnpm，本地缩进覆盖了项目缩进)

# 全局规则（总是生效）
- 所有 API 返回 JSON 格式

<!-- if: language == "typescript" -->
<span style="font-size:0.5pt;">§TOC2-4§</span>
## TypeScript 规则
- 使用 `as` 语法做类型断言，不用 `<Type>` 语法
- 启用 strict mode
- 避免使用 `any`
<!-- endif -->

<!-- if: framework == "react" -->
<span style="font-size:0.5pt;">§TOC2-5§</span>
## React 规则
- 使用函数组件 + Hooks
- 状态管理优先使用 useState/useReducer
- 避免过早引入状态管理库
<!-- endif -->

<!-- if: context contains("testing") -->
<span style="font-size:0.5pt;">§TOC2-6§</span>
## 测试规则
- 测试文件命名：`*.test.ts`
- 使用 describe/it 模式
- 每个 describe 不超过 5 个测试用例
<!-- endif -->

react-dashboard/
├── CLAUDE.md
├── .claude/
│   └── CLAUDE.md   (本地覆盖，gitignore)
├── src/
│   ├── components/
│   ├── hooks/
│   ├── types/
│   └── utils/
└── package.json

# React Dashboard — 项目记忆

<span style="font-size:0.5pt;">§TOC2-8§</span>
## 技术栈
- React 18 + TypeScript 5
- 构建工具：Vite 5
- 状态管理：Zustand
- 样式方案：TailwindCSS 3
- 测试：Vitest + React Testing Library
- 包管理：pnpm

<span style="font-size:0.5pt;">§TOC2-9§</span>
## 组件规范
- 每个组件一个文件，组件名即文件名（PascalCase）
- 组件文件内结构：imports → types → component → exports
- 使用 React.memo() 包裹纯展示组件
- Props 接口命名为 `{ComponentName}Props`

<!-- if: file_path matches "src/components/**" -->
<span style="font-size:0.5pt;">§TOC2-10§</span>
## 组件目录结构
- 复杂组件使用文件夹：`Button/Button.tsx + Button.test.tsx + index.ts`
- 简单组件使用单文件：`Spinner.tsx`
- 导出统一使用 barrel export（index.ts）
<!-- endif -->

<!-- if: task == "testing" -->
<span style="font-size:0.5pt;">§TOC2-11§</span>
## 测试策略
- 组件测试优先测试用户交互，而非实现细节
- 使用 screen.getByRole 而非 getByTestId
- 异步操作使用 waitFor 和 findBy*
<!-- endif -->

<span style="font-size:0.5pt;">§TOC2-12§</span>
## 代码风格
- 函数声明：箭头函数（const 声明）
- 解构 Props：在函数参数中直接解构
- Hooks 调用顺序：useState → useEffect → 自定义 hooks
- 不要在 JSX 中写复杂逻辑，提取为函数或变量

# 个人本地覆盖

<span style="font-size:0.5pt;">§TOC2-13§</span>
## 开发环境
- 本地 API 代理端口：3000
- mock 数据服务器：`pnpm mock` 启动在 3001

<span style="font-size:0.5pt;">§TOC2-14§</span>
## 个人偏好
- 我喜欢在组件顶部加 JSDoc 注释描述用途
- 调试时优先使用 console.table 而非 console.log

# API Server — 项目记忆

<span style="font-size:0.5pt;">§TOC2-15§</span>
## 技术栈
- Runtime: Node.js 20 LTS
- 框架: Express 4 + TypeScript
- 数据库: PostgreSQL 15 + Prisma ORM
- 缓存: Redis 7
- 消息队列: BullMQ
- 测试: Jest + Supertest

<span style="font-size:0.5pt;">§TOC2-16§</span>
## 架构约束
- 分层架构：Controller → Service → Repository
- Controller 只做参数校验和响应格式化，不写业务逻辑
- Service 层写所有业务逻辑，可跨 Repository 调用
- Repository 层只管数据访问，不包含业务判断

<!-- if: file_path matches "src/controllers/**" -->
<span style="font-size:0.5pt;">§TOC2-17§</span>
## Controller 规范
- 使用 express-async-errors 统一处理异步错误
- 响应格式统一为 `{ code: number, data: T, message: string }`
- 参数校验使用 Zod schema，在 controller 入口完成
<!-- endif -->

<!-- if: file_path matches "src/services/**" -->
<span style="font-size:0.5pt;">§TOC2-18§</span>
## Service 规范
- 每个 Service 方法必须显式返回类型
- 事务操作必须通过 Prisma 的 $transaction
- 外部 API 调用必须有超时设置（默认 5s）和重试（最多 2 次）
<!-- endif -->

<span style="font-size:0.5pt;">§TOC2-19§</span>
## 数据库规范
- 迁移文件只通过 Prisma Migrate 生成，不手动编辑
- 查询默认包含软删除过滤（deletedAt IS NULL）
- N+1 查询：关联数据使用 Prisma 的 include/select

<span style="font-size:0.5pt;">§TOC2-20§</span>
## 错误处理
- 所有 try-catch 的 catch 块必须做两件事：log + 抛出标准错误
- 自定义错误类继承 AppError（含 code + httpStatus）
- 禁止吞掉错误（bare catch）

# ML Pipeline — 项目记忆

<span style="font-size:0.5pt;">§TOC2-21§</span>
## 技术栈
- Python 3.11
- 数据处理：Pandas 2 + Polars（新代码迁移中）
- ML 框架：scikit-learn 1.5 + XGBoost 2
- 实验追踪：MLflow
- 环境管理：Poetry（依赖）+ pyenv（Python 版本）
- 代码质量：Ruff（lint）+ MyPy（type check）

<span style="font-size:0.5pt;">§TOC2-22§</span>
## Python 规范
- 类型注解：所有函数参数和返回值必须有类型注解
- 文档字符串：公共函数使用 Google style docstring
- 导入顺序：stdlib → third-party → local，每组之间空一行

<!-- if: context contains("notebook") -->
<span style="font-size:0.5pt;">§TOC2-23§</span>
## Notebook 规范
- 每个 Notebook 的第一个 cell 是 markdown，描述目的和输入输出
- Notebook 不包含超过 50 行的 cell
- 完成后执行 Kernel → Restart & Run All 确保可复现
<!-- endif -->

<!-- if: file_path matches "src/features/**" -->
<span style="font-size:0.5pt;">§TOC2-24§</span>
## Feature Engineering 规范
- 特征工程函数必须是无状态的纯函数
- 输入输出都是 Pandas DataFrame，不依赖全局状态
- 函数名使用 `build_` 前缀（build_date_features, build_text_features）
<!-- endif -->

<span style="font-size:0.5pt;">§TOC2-25§</span>
## 数据处理最佳实践
- 链式调用优先于逐步赋值（df.pipe().assign().query()）
- 避免 inplace=True 操作
- 使用 .loc[] 和 .iloc[]，不用链式索引 df[col][row]
- 缺失值处理必须在 Pipeline 中显式声明策略

<span style="font-size:0.5pt;">§TOC2-26§</span>
## 实验管理
- 每次实验记录参数、指标、数据版本到 MLflow
- 实验命名：`{日期}_{简短描述}_{关键参数}`
- 废弃代码不删除，移动到 `archive/` 目录

# 差
- 注重代码性能

# 好
- 避免在 render 中创建新对象/函数引用
- List 渲染必须使用 key prop（禁止使用 index 作为 key）
- 超过 100 项的数据使用虚拟滚动（react-window）

┌──────────────────────────────────────────────┐
│            Skills 图书馆（每轮对话可见）        │
│                                              │
│  📚 react-patterns       React 组件设计模式    │
│  📚 api-design           RESTful API 设计规范  │
│  📚 db-optimization      数据库查询优化        │
│  📚 testing-strategy     测试策略与模式        │
│  📚 error-handling       错误处理最佳实践      │
│  ...                                         │
│                                              │
│  每个 Skill 只暴露：名称 + description (≤200字符) │
└──────────────────────────────────────────────┘

[System Prompt]
... CLAUDE.md (200行) ...
... react-patterns.md (150行) ...
... api-design.md (180行) ...
... db-optimization.md (200行) ...
... testing-strategy.md (160行) ...
... error-handling.md (120行) ...
总 token 消耗：~5000+ token，其中大部分与当前任务无关

[System Prompt]
... CLAUDE.md (200行) ...
可用 Skills：
- react-patterns: React 组件设计模式与最佳实践
- api-design: RESTful API 设计规范与命名约定
- db-optimization: 常见数据库查询性能优化方法
- testing-strategy: 前端与后端测试策略选择指南
- error-handling: 错误处理模式与异常传播策略
总 token 消耗（目录）：~3500 token

当 Claude 判断需要 react-patterns 时：
[注入 react-patterns.md 完整内容：150 行]
额外 token 消耗：~1500 token
但只在需要时发生！

# 差：太泛，Claude 不知道什么时候激活
description: "React 开发相关的最佳实践"

# 差：太啰嗦，浪费了 token 却没有更多信息量
description: "本 Skill 包含了我们团队在多年 React 开发中积累的各种最佳实践，
包括组件设计模式、状态管理策略、性能优化技巧以及测试方法等等"

# 好：精准、有边界、含触发信号
description: "React 组件设计模式。当创建新组件或重构现有组件时激活。
含组合模式、Render Props、HOC、自定义 Hooks 的选择决策树。"

用户: "帮我创建一个用户登录表单组件"
         ↓
Claude 判断: 创建 React 组件 → 需要 react-patterns Skill
         ↓
Claude: skill_view(name='react-patterns')
         ↓
系统注入 react-patterns.md 全部内容
         ↓
Claude 基于 Skill 知识开始编码

用户: "用 api-design skill 帮我设计用户模块的 API"
或
用户: /api-design

用户输入
    │
    ▼
┌─────────────┐
│  Harness     │  ← 加载所有 Skills 的 description
│  (路由器)     │
└──────┬──────┘
       │ 匹配？
       │
   ┌───┴───┬───────┬──────────┐
   ▼       ▼       ▼          ▼
Skill A  Skill B  Skill C   无匹配
(注入)   (注入)   (注入)    (仅用CLAUDE.md)

# 差：随机拆分
api-design-part1.md  (350行)
api-design-part2.md  (320行)
→ Claude 不知道什么时候激活哪个，路由混乱

# 好：按子域拆分
api-rest-design.md       (400行) — RESTful API 设计
api-graphql-design.md    (350行) — GraphQL schema 设计  
api-error-handling.md    (200行) — 错误码和异常处理
api-versioning.md        (180行) — API 版本管理策略
→ 每个子域独立路由，各自有精准的 description

Skill 超过 500 行？
  ├─ 是 → 是否有自然子域分界？
  │        ├─ 是 → 按子域拆分
  │        └─ 否 → 内容是否包含大量代码示例？
  │                 ├─ 是 → 精简要义，代码示例精简到最小可用
  │                 └─ 否 → 考虑是否部分内容更适合 CLAUDE.md
  └─ 否 → 保持现状

---
name: db-migration
description: 数据库迁移操作指南。当需要创建、运行或回滚数据库迁移时激活。
allowed-tools: Bash(git:*), Bash(prisma:*), Read, Write
---

# 最小权限示例：数据库迁移 Skill
---
allowed-tools: Bash(prisma:migrate, prisma:generate), Read, Write(src/migrations/**)
---

# 适度权限示例：测试 Skill
---
allowed-tools: Bash(npm:test, pnpm:test, jest:*), Read, Grep
---

# 开放权限示例：代码规范 Skill（纯知识，不需要工具）
---
# 不声明 allowed-tools，继承默认权限
---

---
name: api-review
description: API 设计评审 checklist。当设计新 API 或修改现有 API 接口时激活。
---

# API 设计评审流程

<span style="font-size:0.5pt;">§TOC3-9§</span>
## 步骤 1：路径设计
- 资源名使用复数名词：`/users` 而非 `/user`
- 层级关系体现为路径嵌套：`/users/{id}/orders`
- 非 CRUD 操作使用动词后缀：`/users/{id}/activate`

<span style="font-size:0.5pt;">§TOC3-10§</span>
## 步骤 2：请求设计
- GET 请求参数不超过 5 个，否则考虑 POST + body
- 分页参数统一为 `page` + `page_size`
- 排序参数格式：`sort=field:asc|desc`

<span style="font-size:0.5pt;">§TOC3-11§</span>
## 步骤 3：响应设计
- 成功响应统一包裹：`{ code: 0, data: T, message: "ok" }`
- 列表响应包含分页信息：`{ items: [], total: N, page: N, page_size: N }`

---
name: error-patterns
description: 错误处理模式库。含 Result/Option 模式、异常链、降级策略的选择指南。
---

# 错误处理模式

<span style="font-size:0.5pt;">§TOC3-12§</span>
## 模式选择决策树

<span style="font-size:0.5pt;">§TOC3-13§</span>
## 模式 1：Result<T, E>（推荐）

```typescript
type Result<T, E = Error> = 
  | { success: true; data: T }
  | { success: false; error: E };

// 使用
function divide(a: number, b: number): Result<number> {
  if (b === 0) return { success: false, error: new Error('除零错误') };
  return { success: true, data: a / b };
}

### 范式三：决策型 Skill（Decision Skill）

**定义：** 帮助 Claude 在多个可选项之间做出正确的技术决策。

**特征：**
- 明确的选择题（A vs B vs C）
- 决策矩阵（条件→推荐方案）
- 不涉及具体代码实现

**示例：状态管理选型 Skill**

```markdown
---
name: state-management
description: 前端状态管理方案选型指南。当项目中需要选择状态管理方案时激活。
---

# 状态管理方案选型

<span style="font-size:0.5pt;">§TOC3-14§</span>
## 决策矩阵

| 条件 | 推荐方案 | 原因 |
|------|---------|------|
| 组件局部状态，不需共享 | useState | 最简单，零依赖 |
| 少量跨组件共享状态 | useContext + useReducer | 原生方案，轻量 |
| 中型应用，复杂状态逻辑 | Zustand | 轻量、TS 友好、无 boilerplate |
| 大型应用，多人协作 | Redux Toolkit | 规范化结构、DevTools、中间件生态 |
| 服务端状态为主 | TanStack Query | 专注异步状态、缓存、同步 |

<span style="font-size:0.5pt;">§TOC3-15§</span>
## 硬性约束（不参与决策，直接执行）
- 新项目默认使用 Zustand（除非明确需要 Redux）
- 禁止同时使用两个状态管理库

---
name: tech-stack
description: 公司技术栈清单。含各项目使用的框架、版本和服务地址。当需要了解技术环境时激活。
---

# 公司技术栈

<span style="font-size:0.5pt;">§TOC3-16§</span>
## 项目清单

| 项目 | 前端 | 后端 | 数据库 | 部署 |
|------|------|------|--------|------|
| user-center | React 18 | Node.js 20 | PostgreSQL 15 | K8s |
| payment-svc | - | Go 1.21 | MySQL 8.0 | K8s |
| admin-dashboard | Vue 3 | Java 17/Spring | PostgreSQL 15 | Docker |

<span style="font-size:0.5pt;">§TOC3-17§</span>
## 服务地址

| 服务 | 开发环境 | 测试环境 | 生产环境 |
|------|---------|---------|---------|
| API Gateway | localhost:8080 | api-test.example.com | api.example.com |
| Auth Service | localhost:8081 | auth-test.example.com | auth.example.com |

主对话 (Main Agent)
│
├── 子智能体 A: "扫描所有遗留的 console.log"
│   └── 结果: 找到 23 处，已生成修复建议
│
├── 子智能体 B: "检查所有 API 路由的错误处理"
│   └── 结果: 3 个路由缺少 try-catch
│
└── 子智能体 C: "生成 CHANGELOG.md"
    └── 结果: 已生成

主 Agent: "在合并 PR 之前，做一次全面的代码审查"
    │
    ├── 子智能体 1（只读）: 审查 src/components/ 目录
    │   搜索：未使用的导入、console.log、TODO 注释、any 类型
    │   返回：发现 5 个问题（3 个 console.log, 2 个 any 类型）
    │
    ├── 子智能体 2（只读）: 审查 src/utils/ 目录
    │   返回：发现 2 个问题（1 个未使用函数, 1 个缺失类型）
    │
    └── 子智能体 3（只读）: 审查 package.json + 依赖
        返回：发现 1 个问题（lodash 可替换为原生方法）

在对话中：
> 派生一个只读子智能体，扫描 src/ 下所有 .tsx 文件，
> 检查是否有未使用的 import 和 console.log，汇报结果

主 Agent: "重构 UserService，将业务逻辑从 Controller 移到 Service 层"
    │
    └── 子智能体（执行）:
        输入: src/controllers/userController.ts + src/services/userService.ts
        任务: 重构
        输出: 修改后的两个文件 + 修改说明
        约束: 不改变 API 行为，不修改测试文件

# 好：任务边界清晰
"将 utils/formatDate.ts 中的所有函数改为 TypeScript，添加完整类型注解"

# 差：任务边界模糊
"优化 utils 目录下的代码质量"
# — 什么是「优化」？什么算「质量」？子智能体会迷失方向

任务：[一句话描述]
输入文件：[明确的文件路径列表]
约束条件：
- [约束1：不修改什么]
- [约束2：遵循什么规范]
- [约束3：边界条件]
期望输出：
- [产物1]
- [产物2]

主 Agent: "为 src/ 下每个一级子目录生成单元测试"

┌─ 子智能体 1: 为 src/components/ 生成测试 ──────── 2 min ─┐
├─ 子智能体 2: 为 src/hooks/ 生成测试 ──────────── 1 min ─┤
├─ 子智能体 3: 为 src/utils/ 生成测试 ───────────── 1 min ─┤
└─ 子智能体 4: 为 src/services/ 生成测试 ────────── 3 min ─┘
   并行执行，总耗时 3 min（而非串行的 7 min）

主 Agent 收集结果 → 汇总报告

┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│ 子智能体 1    │    │ 子智能体 2    │    │ 子智能体 3    │    │ 主 Agent     │
│              │───→│              │───→│              │───→│              │
│ 生成功能代码  │    │ 审查代码质量  │    │ 生成单元测试  │    │ 汇总与提交    │
│              │    │ 提出修改意见  │    │ 运行测试      │    │              │
└──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘
     2 min               1 min               2 min              1 min
                                                         总耗时: ~6 min

阶段 1: 子智能体 A（设计）
  输入: API 需求描述
  任务: 设计路由 + 请求/响应 Schema
  输出: API 设计文档 + OpenAPI spec

阶段 2: 子智能体 B（实现）
  输入: 阶段 1 的设计文档
  任务: 实现 Controller + Service + Repository
  输出: 实现代码 + 迁移文件

阶段 3: 子智能体 C（测试）
  输入: 阶段 2 的实现代码
  任务: 编写集成测试 + 运行测试
  输出: 测试文件 + 测试结果报告

阶段 4: 主 Agent（审查）
  输入: 阶段 1-3 的全部产物
  任务: 最终审查 + 合并

主 Agent (Team Lead)
  │
  ├── 前端 Agent: "实现用户管理页面"
  │   职责: React 组件 + 状态管理 + API 对接
  │
  ├── 后端 Agent: "实现用户管理 API"
  │   职责: 路由 + Service + Repository + 迁移
  │
  ├── 数据库 Agent: "设计用户相关表结构"
  │   职责: Schema 设计 + 索引优化 + 迁移脚本
  │
  └── 测试 Agent: "端到端测试用户管理流程"
      职责: 集成测试 + E2E 测试

协调点 1: API 契约（前后端 Agent 之间）
  前端 Agent 需要: GET /api/users 返回 User[]
  后端 Agent 产出: 确认该接口的 Request/Response 格式
  协调方式: 主 Agent 传递「契约文档」，双方独立工作但遵守同一契约

协调点 2: 数据库 Schema（后端 ↔ 数据库 Agent 之间）
  数据库 Agent 产出: Prisma schema
  后端 Agent 消费: 基于 schema 生成 Prisma Client 查询
  协调方式: Schema 写好后，后端 Agent 再启动

// .claude/teams.json
{
  "teams": {
    "fullstack-dev": {
      "description": "全栈开发团队：前端+后端+测试协同",
      "agents": [
        {
          "name": "frontend",
          "role": "React 前端开发",
          "skills": ["react-patterns", "api-design"],
          "permission_mode": "default",
          "workdir": "src/frontend"
        },
        {
          "name": "backend",
          "role": "Node.js 后端开发",
          "skills": ["api-design", "db-optimization"],
          "permission_mode": "default",
          "workdir": "src/backend"
        },
        {
          "name": "qa",
          "role": "测试工程师",
          "skills": ["testing-strategy"],
          "permission_mode": "readonly",
          "workdir": "."
        }
      ]
    }
  }
}

第一步：数据库 Agent（独立执行）
  → 设计 comments 表，生成 Prisma 迁移
  → 产物: prisma/schema.prisma + 迁移文件

第二步：后端 Agent + 前端 Agent（并行执行）
  后端 Agent:
    → 基于数据库 Schema 实现 CRUD API
    → 产物: controller + service + repository
  前端 Agent:
    → 实现评论列表 + 评论输入组件
    → 产物: React 组件文件

第三步：测试 Agent（依赖前两步）
  → 验证 API 行为 + 组件渲染
  → 产物: 测试文件 + 测试报告

第四步：主 Agent 整合审查
  → 检查所有产物
  → 运行 lint + 测试
  → 提供最终报告

主仓库: /project/main
  │
  ├── Worktree: /project/worktrees/agent-001 (前端 Agent)
  ├── Worktree: /project/worktrees/agent-002 (后端 Agent)
  └── Worktree: /project/worktrees/agent-003 (测试 Agent)

1. 主 Agent 为每个子 Agent 创建 worktree
   git worktree add /tmp/cc-worktrees/frontend main

2. 子 Agent 在 worktree 中独立工作
   cd /tmp/cc-worktrees/frontend && [修改文件]

3. 子 Agent 完成后，主 Agent 审查变更
   git -C /tmp/cc-worktrees/frontend diff

4. 主 Agent 合并所有 worktree 的变更
   → 逐文件 cherry-pick 或 merge
   → 处理冲突（如有）

5. 清理 worktree
   git worktree remove /tmp/cc-worktrees/frontend

# 差：三个小任务各开一个子智能体
子智能体 A: 改文件1 (200 token)
子智能体 B: 改文件2 (200 token)  
子智能体 C: 改文件3 (300 token)
总: 700 + 3×overhead (~600) = 1300 token

# 好：合并为一个任务
子智能体 A: 改文件1、2、3 (600 token)
总: 600 + 1×overhead (~200) = 800 token  ← 节省 38%

# 在子智能体任务描述中加入：
"完成后只需返回：修改了哪些文件、关键决策、遇到的问题（不超过 200 字）"

提出需求 → AI 生成代码 → 人工审查 → 修改 → 再审查 → 通过

有 Hooks:
提出需求 → AI 规划修改 → [Hook: 检查] → ✅ 通过 → AI 写入文件
                                    → ❌ 拒绝 → AI 重新规划

高频（每次对话触发多次）
  ████████ PreToolUse       ← 最核心的事件
  ████████ PostToolUse
  ██████   PreWrite
  █████    PostWrite

中频（每次对话触发 1-2 次）
  ████     SessionStart
  ████     UserPromptSubmit
  ███      PreCommand
  ███      PostCommand

低频（按需触发）
  ██       PermissionRequest
  █        SubagentStart / SubagentStop
  █        PostToolUseFailure
  █        Error / Stop / Notification / SessionEnd

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "pnpm lint-staged --diff",
        "description": "在编辑文件前运行 lint 检查"
      }
    ]
  }
}

Hook 触发 → 执行 command
  ├─ 退出码 0: 通过，允许操作继续
  ├─ 退出码 1: 警告，显示 stderr 但允许操作继续
  └─ 退出码 2+: 阻止，操作被取消，stderr 反馈给 Claude

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "*",
        "prompt": "注意：用户最近多次提到性能问题，请在回答中优先关注性能影响。",
        "description": "上下文感知提示"
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit",
        "agent": {
          "prompt": "检查即将编辑的文件。如果修改涉及安全敏感代码（认证、授权、加密），请验证修改是否安全。如果不安全，返回非 0 退出码并解释原因。",
          "permission_mode": "readonly"
        },
        "description": "安全 Agent 审查"
      }
    ]
  }
}

{
  "hooks": {
    "PreCommand": [
      {
        "matcher": "*",
        "command": "danger-check.sh",
        "description": "拦截危险命令"
      }
    ]
  }
}

#!/bin/bash
# 读取 Claude 要执行的命令
COMMAND="$CLAUDE_TOOL_INPUT"

# 黑名单检查
DANGEROUS_PATTERNS=(
  "rm -rf /"
  "git push --force origin main"
  "DROP TABLE"
  "DROP DATABASE"
  "> /dev/sda"
  "chmod 777"
  "curl.*|.*sh"
)

for pattern in "${DANGEROUS_PATTERNS[@]}"; do
  if echo "$COMMAND" | grep -qi "$pattern"; then
    echo "❌ 拦截危险命令: $pattern" >&2
    echo "命令已被安全策略阻止。如需执行，请手动操作。" >&2
    exit 2  # 阻止执行
  fi
done

exit 0  # 安全，允许执行

{
  "hooks": {
    "PreWrite": [
      {
        "matcher": "*.env|*.pem|*.key|credentials.*|secrets.*",
        "command": "sensitive-file-guard.sh",
        "description": "防止 AI 修改敏感文件"
      }
    ],
    "PreRead": [
      {
        "matcher": "*.env|*.pem|*.key",
        "command": "secret-read-guard.sh",
        "description": "防止 AI 读取密钥文件"
      }
    ]
  }
}

#!/bin/bash
FILE="$CLAUDE_FILE_PATH"

echo "⚠️ 文件 $FILE 被标记为敏感文件。" >&2
echo "AI 不能修改密钥、证书和凭证文件。请手动操作。" >&2
exit 2

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|Bash",
        "command": "audit-log.sh",
        "description": "记录所有写操作和命令执行"
      }
    ]
  }
}

#!/bin/bash
LOG_FILE=".claude/audit.log"

echo "[$(date -Iseconds)] EVENT=$CLAUDE_EVENT TOOL=$CLAUDE_TOOL_NAME FILE=$CLAUDE_FILE_PATH" >> "$LOG_FILE"

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "Bash*",
        "command": "permission-approval.sh",
        "description": "命令执行需要额外审批"
      }
    ]
  }
}

{
  "hooks": {
    "Error": [
      {
        "matcher": "*",
        "command": "error-alert.sh",
        "description": "异常发生时发送告警"
      }
    ]
  }
}

#!/bin/bash
# 发送 Slack/飞书/钉钉 通知
curl -X POST "$WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d "{\"text\": \"⚠️ Claude Code 异常: $CLAUDE_EVENT\"}"

{
  "hooks": {
    "PreWrite": [
      {
        "matcher": "*.ts|*.tsx",
        "command": "npx eslint --stdin --stdin-filename \"$CLAUDE_FILE_PATH\"",
        "description": "TypeScript 文件写入前 ESLint 检查"
      },
      {
        "matcher": "*.py",
        "command": "ruff check --stdin-filename \"$CLAUDE_FILE_PATH\" -",
        "description": "Python 文件写入前 Ruff 检查"
      }
    ]
  }
}

{
  "hooks": {
    "PostWrite": [
      {
        "matcher": "*.ts|*.tsx|*.js|*.json|*.md",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\"",
        "description": "文件写入后自动格式化"
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit",
        "command": "typecheck-guard.sh",
        "description": "编辑前运行类型检查作为基线"
      }
    ]
  }
}

#!/bin/bash
# 在编辑前运行类型检查，确保当前状态是干净的
npx tsc --noEmit 2>&1 | head -20
exit_code=$?

if [ $exit_code -ne 0 ]; then
  echo "⚠️ 当前代码存在类型错误，请先修复再继续编辑。" >&2
  exit 1  # 警告而非阻止
fi
exit 0

{
  "hooks": {
    "PostWrite": [
      {
        "matcher": "src/**/*.ts",
        "command": "related-test-check.sh",
        "description": "检查修改的文件是否有对应测试"
      }
    ]
  }
}

#!/bin/bash
FILE="$CLAUDE_FILE_PATH"
TEST_FILE="${FILE/src\//src/__tests__/}"
TEST_FILE="${TEST_FILE/.ts/.test.ts}"

if [ ! -f "$TEST_FILE" ]; then
  echo "⚠️ 文件 $FILE 没有对应的测试文件 $TEST_FILE" >&2
  echo "请考虑添加测试。" >&2
  exit 1  # 警告，不阻止
fi
exit 0

项目级 Hooks:
  .claude/settings.json   → 提交到 Git，团队共享

个人级 Hooks:
  ~/.claude/settings.json → 个人偏好，不提交

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "*",
        "command": "node .claude/hooks/session-start.js",
        "description": "检查开发环境是否就绪"
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": ".claude/hooks/pre-write-check.sh",
        "description": "写入前安全检查 + lint"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": ".claude/hooks/auto-format.sh",
        "description": "自动格式化"
      },
      {
        "matcher": "Edit|Write|Bash",
        "command": ".claude/hooks/audit-log.sh",
        "description": "审计日志"
      }
    ],
    "PreCommand": [
      {
        "matcher": "*",
        "command": ".claude/hooks/danger-check.sh",
        "description": "危险命令拦截"
      }
    ],
    "Error": [
      {
        "matcher": "*",
        "command": ".claude/hooks/error-notify.sh",
        "description": "异常告警"
      }
    ]
  }
}

# Claude Code 将 Hook 执行日志写入
cat ~/.claude/logs/hooks.log

#!/bin/bash
# 所有 stderr 输出会显示给用户（当 Hook 失败时）
echo "[DEBUG] Hook triggered: $CLAUDE_EVENT" >> /tmp/claude-hook-debug.log
echo "[DEBUG] Tool: $CLAUDE_TOOL_NAME" >> /tmp/claude-hook-debug.log
echo "[DEBUG] File: $CLAUDE_FILE_PATH" >> /tmp/claude-hook-debug.log

# 实际检查逻辑...

# Hook 通过
echo "[DEBUG] Hook passed" >> /tmp/claude-hook-debug.log
exit 0

#!/bin/bash
FILE="$CLAUDE_FILE_PATH"

# dry-run 模式：手动测试时使用
if [ "$1" = "--dry-run" ]; then
  echo "Dry-run mode: would check $FILE"
  exit 0
fi

# 实际检查逻辑...

// ❌ 不要这样
{
  "hooks": {
    "PreToolUse": [
      { "command": "check1.sh" },
      { "command": "check2.sh" },
      { "command": "check3.sh" },
      { "command": "check4.sh" },
      { "command": "check5.sh" }
    ]
  }
}
// 每次工具调用前执行 5 个 Hook → 响应延迟 10+ 秒

#!/bin/bash
# all-checks.sh — 一次执行所有检查
check_lint
check_types
check_security
check_format

// ❌ PostWrite Hook 中执行 sed 替换
{
  "PostWrite": [
    {
      "command": "sed -i 's/var/let/g' \"$CLAUDE_FILE_PATH\""
    }
  ]
}
// 问题：Claude 不知道文件被修改了，产生不一致

// ❌ PostWrite 中触发文件修改，又触发 PostWrite...
{
  "PostWrite": [
    {
      "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
    }
  ]
}

┌──────────────────┐         ┌──────────────────┐
│   Claude Code    │ ◄─MCP─► │   MCP Server     │
│   (MCP Client)   │         │   (你的代码)      │
└──────────────────┘         └──────┬───────────┘
                                    │
                           ┌────────▼───────────┐
                           │ PostgreSQL / Redis  │
                           │ 文件系统 / 外部API  │
                           └────────────────────┘

{
  "mcpServers": {
    "my-db-server": {
      "command": "python",
      "args": ["-m", "my_mcp_db_server"],
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/mydb"
      }
    }
  }
}

# server.py — stdio模式MCP服务器骨架
import asyncio
from mcp.server import Server
from mcp.server.stdio import stdio_server

server = Server("my-db-server")

@server.list_tools()
async def list_tools():
    return [
        {"name": "query_db", "description": "执行SQL查询"},
        {"name": "list_tables", "description": "列出所有表"},
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "query_db":
        return await execute_query(arguments["sql"])
    # ...

async def main():
    async with stdio_server() as (read, write):
        await server.run(read, write, server.create_initialization_options())

asyncio.run(main())

# http_server.py — HTTP+SSE模式
from mcp.server.sse import SseServerTransport
from starlette.applications import Starlette
from starlette.routing import Route

transport = SseServerTransport("/messages/")

async def handle_sse(request):
    async with transport.connect_sse(request.scope, request.receive, request._send) as streams:
        await server.run(streams[0], streams[1], server.create_initialization_options())

app = Starlette(routes=[
    Route("/sse", endpoint=handle_sse),
    Route("/messages/", endpoint=transport.handle_post_message, methods=["POST"]),
])

{
  "mcpServers": {
    "remote-db": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer sk-xxx"
      }
    }
  }
}

# pg_mcp_server.py — PostgreSQL MCP服务器
import asyncpg
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import Tool, TextContent

server = Server("pg-explorer")

@server.list_tools()
async def list_tools() -> list[Tool]:
    return [
        Tool(name="list_tables", description="列出数据库所有表"),
        Tool(name="describe_table", description="查看表结构",
             inputSchema={"type": "object", "properties": {"table": {"type": "string"}}}),
        Tool(name="run_query", description="执行只读SQL查询",
             inputSchema={"type": "object", "properties": {"sql": {"type": "string"}}}),
    ]

# 全局连接池
pool: asyncpg.Pool = None

async def get_pool():
    global pool
    if pool is None:
        pool = await asyncpg.create_pool(
            dsn="postgresql://user:pass@localhost:5432/mydb",
            min_size=1, max_size=5
        )
    return pool

@server.call_tool()
async def call_tool(name: str, arguments: dict):
    p = await get_pool()
    if name == "list_tables":
        async with p.acquire() as conn:
            rows = await conn.fetch(
                "SELECT table_name FROM information_schema.tables WHERE table_schema='public'"
            )
            return [TextContent(type="text", text=str([r['table_name'] for r in rows]))]
    elif name == "describe_table":
        async with p.acquire() as conn:
            rows = await conn.fetch(
                "SELECT column_name, data_type, is_nullable FROM information_schema.columns WHERE table_name=$1",
                arguments["table"]
            )
            return [TextContent(type="text", text=str([dict(r) for r in rows]))]
    elif name == "run_query":
        sql = arguments["sql"].strip().upper()
        # 安全：只允许SELECT
        if not sql.startswith("SELECT"):
            return [TextContent(type="text", text="错误：只允许SELECT查询")]
        async with p.acquire() as conn:
            rows = await conn.fetch(arguments["sql"])
            return [TextContent(type="text", text=str([dict(r) for r in rows[:100]]))]

async def main():
    async with stdio_server() as (read, write):
        await server.run(read, write, server.create_initialization_options())

import asyncio
asyncio.run(main())

你：帮我分析一下users表里有多少用户是上周注册的

Claude Code：[调用 list_tables] → [调用 describe_table table="users"]
         → [调用 run_query sql="SELECT COUNT(*) FROM users WHERE created_at > NOW() - INTERVAL '7 days'"]

回复：上周新注册了284位用户，详细分布如下...

<span style="font-size:0.5pt;">§TOC6-6§</span>
## 数据库操作安全规则

- 永远不要执行 DROP、TRUNCATE、ALTER、CREATE、INSERT、UPDATE、DELETE 语句
- 查询时必须带 LIMIT，默认 LIMIT 100
- 涉及用户隐私数据（email, phone, password_hash）的查询必须跳过这些列
- 查询超过1000行的，先 COUNT 确认规模，再分页

# 安全中间件：SQL白名单
FORBIDDEN_KEYWORDS = ["DROP", "DELETE", "UPDATE", "INSERT", "ALTER", "TRUNCATE", "CREATE"]
MINIMUM_REQUIRED_KEYWORDS = ["SELECT"]

async def safe_query(conn, sql: str):
    upper_sql = sql.upper().strip()
    for kw in FORBIDDEN_KEYWORDS:
        if kw in upper_sql:
            raise PermissionError(f"FORBIDDEN_KEYWORDS: {kw}")
    if not any(kw in upper_sql for kw in MINIMUM_REQUIRED_KEYWORDS):
        raise PermissionError("Only SELECT is allowed")
    if "LIMIT" not in upper_sql:
        sql = sql.rstrip(";") + " LIMIT 100"
    return await conn.fetch(sql)

-- 创建MCP专用只读角色
CREATE ROLE mcp_readonly WITH LOGIN PASSWORD 'xxx';
GRANT CONNECT ON DATABASE mydb TO mcp_readonly;
GRANT USAGE ON SCHEMA public TO mcp_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO mcp_readonly;

# 数据库管理员助手

<span style="font-size:0.5pt;">§TOC6-8§</span>
## 分析流程
当用户询问数据库相关问题时，遵循以下流程：

1. **了解全貌**：先用 list_tables 了解数据库有哪些表
2. **定位问题表**：根据用户描述，用 describe_table 查看相关表结构
3. **编写查询**：基于表结构，编写精确的SQL查询
4. **验证结果**：确保返回数据符合预期

<span style="font-size:0.5pt;">§TOC6-9§</span>
## 性能优化规则
- 查询大表时务必使用索引列作为WHERE条件
- 如果 users 表超过 100 万行，按 created_at 分区查询
- 关联查询超过 3 张表时，建议先查主表再逐步关联

<span style="font-size:0.5pt;">§TOC6-10§</span>
## 数据解释规范
- 金额字段以人民币显示，格式: ¥x,xxx.xx
- 时间字段显示为北京时间（UTC+8）
- 百分比保留一位小数

{
  "mcpServers": {
    "pg-explorer": {
      "command": "python",
      "args": ["-m", "pg_mcp_server"]
    }
  },
  "skills": ["dba-assistant.md"]
}

# filesystem_mcp.py
import os, glob
from pathlib import Path
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import Tool, TextContent

server = Server("fs-explorer")

# 白名单：只允许访问这些目录
ALLOWED_ROOTS = ["/Users/wangguobao/projects", "/Users/wangguobao/documents"]

def is_allowed(path: str) -> bool:
    real = os.path.realpath(path)
    return any(real.startswith(os.path.realpath(root)) for root in ALLOWED_ROOTS)

@server.list_tools()
async def list_tools():
    return [
        Tool(name="list_dir", description="列出目录内容",
             inputSchema={"type": "object", "properties": {"path": {"type": "string"}}, "required": ["path"]}),
        Tool(name="read_file", description="读取文件内容（限制10KB）",
             inputSchema={"type": "object", "properties": {"path": {"type": "string"}}, "required": ["path"]}),
        Tool(name="search_files", description="按glob模式搜索文件",
             inputSchema={"type": "object", "properties": {"pattern": {"type": "string"}}, "required": ["pattern"]}),
        Tool(name="grep", description="在文件中搜索内容",
             inputSchema={"type": "object", "properties": {"path": {"type": "string"}, "pattern": {"type": "string"}}, "required": ["path", "pattern"]}),
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "list_dir":
        path = arguments["path"]
        if not is_allowed(path):
            return [TextContent(type="text", text="拒绝访问：路径不在白名单中")]
        try:
            items = os.listdir(path)
            return [TextContent(type="text", text=str(items))]
        except Exception as e:
            return [TextContent(type="text", text=str(e))]

    elif name == "read_file":
        path = arguments["path"]
        if not is_allowed(path):
            return [TextContent(type="text", text="拒绝访问")]
        size = os.path.getsize(path)
        if size > 10 * 1024:
            return [TextContent(type="text", text=f"文件过大（{size}B），限制10KB")]
        with open(path) as f:
            return [TextContent(type="text", text=f.read())]

    elif name == "search_files":
        pattern = arguments["pattern"]
        results = []
        for root in ALLOWED_ROOTS:
            for p in glob.glob(os.path.join(root, pattern), recursive=True):
                if is_allowed(p):
                    results.append(p)
        return [TextContent(type="text", text=str(results))]

    elif name == "grep":
        import subprocess
        path, pattern = arguments["path"], arguments["pattern"]
        if not is_allowed(path):
            return [TextContent(type="text", text="拒绝访问")]
        result = subprocess.run(["grep", "-rn", "-m", "20", pattern, path],
                                capture_output=True, text=True, timeout=10)
        return [TextContent(type="text", text=result.stdout or "无匹配")]

async def main():
    async with stdio_server() as (read, write):
        await server.run(read, write, server.create_initialization_options())

import asyncio
asyncio.run(main())

# 直接传入prompt
claude -p "帮我审查这个PR中的安全漏洞" --print

# 从--system-prompt注入系统级指令
claude -p "review pr" \
  --system-prompt "你是资深安全审计专家。只关注OWASP Top 10相关漏洞。用Markdown格式输出。"

# 引用文件作为上下文
claude -p "审查 src/auth.py 的安全问题" \
  --add-dir src/ \
  --print

# 权限模式三档
claude -p "fix this" --permission-mode acceptEdits  # 只接受文件修改
claude -p "check this" --permission-mode bypassPermissions  # 自动跳过确认（危险！）
claude -p "review" --permission-mode plan  # 只读模式，不修改任何文件

# --print 把最终回复打印到stdout（CI必备）
claude -p "分析代码质量" --print

# --output-format json 输出结构化JSON
claude -p "分析循环复杂度" --output-format json --print

# --max-turns 限制交互轮次，防止失控
claude -p "重构这个函数" --max-turns 5

# --verbose 显示详细日志
claude -p "debug" --verbose

# --resume 从上次中断的会话继续
claude --resume <session-id> -p "继续上次的任务"

# --continue 自动恢复最近的会话
claude --continue

# 列出所有会话
claude --resume

# .github/workflows/claude-review.yml
name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4

      - name: Claude Code PR Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "审查这个PR的所有变更。关注安全问题、代码质量、潜在的bug。
          输出简洁的审查意见，每个问题标注文件和行号。" \
            --print \
            --permission-mode plan \
            --output-format json > review.json

      - name: Post Review Comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = JSON.parse(fs.readFileSync('review.json', 'utf8'));
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: `## 🤖 Claude Code 审查意见\n\n${review.result}`
            });

name: Production Claude Review

on:
  pull_request:
    paths:
      - 'src/**'
      - 'lib/**'
      - '*.py'
      - '*.js'
      - '*.ts'

jobs:
  claude-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get Changed Files
        id: changed-files
        uses: tj-actions/changed-files@v41
        with:
          files: |
            src/**
            lib/**

      - name: Skip if no relevant changes
        if: steps.changed-files.outputs.any_changed != 'true'
        run: echo "No relevant files changed, skipping"

      - name: Claude Code Review
        if: steps.changed-files.outputs.any_changed == 'true'
        id: claude
        continue-on-error: true  # 关键：不因为AI不稳定而阻断CI
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          # 只审查变更的文件
          FILES="${{ steps.changed-files.outputs.all_changed_files }}"
          claude -p "只审查这些文件：$FILES。评估代码质量、安全性和可维护性。" \
            --print \
            --permission-mode plan \
            --add-dir src/ \
            --max-turns 10 \
            | tee review.md

      - name: Post Review or Fallback
        if: always()
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            let body;
            if (fs.existsSync('review.md')) {
              body = fs.readFileSync('review.md', 'utf8');
            } else {
              body = '⚠️ Claude Code 审查跳过（无相关文件变更或AI服务不可用）';
            }
            await github.rest.issues.createComment({
              issue_number: context.issue.number,
              body: body
            });

# 使用 OIDC + AWS Secrets Manager 获取 API Key
- name: Configure AWS Credentials
  uses: aws-actions/configure-aws-credentials@v4
  with:
    role-to-assume: arn:aws:iam::123456789:role/github-actions-role
    aws-region: us-east-1

- name: Get API Key from Secrets Manager
  run: |
    export ANTHROPIC_API_KEY=$(aws secretsmanager get-secret-value \
      --secret-id anthropic/api-key \
      --query SecretString --output text | jq -r '.ANTHROPIC_API_KEY')
    claude -p "review" --print --permission-mode plan

# .gitlab-ci.yml
claude-review:
  image: node:20
  stage: review
  only:
    - merge_requests
  before_script:
    - npm install -g @anthropic-ai/claude-code
  script:
    - |
      claude -p "审查这个MR的所有变更。输出格式：
      ## 严重问题
      - ...
      ## 建议改进
      - ...
      ## 总结
      " \
        --print \
        --permission-mode plan \
        --output-format json > review.json
    - |
      # 通过GitLab API发评论
      curl --request POST \
        --header "PRIVATE-TOKEN: $GITLAB_API_TOKEN" \
        --header "Content-Type: application/json" \
        --data "{\"body\": $(jq -Rs . review.json)}" \
        "$CI_API_V4_URL/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes"
  allow_failure: true  # GitLab 的等价于 continue-on-error

// Jenkinsfile
pipeline {
    agent {
        docker {
            image 'node:20'
            args '-v $HOME/.claude:/root/.claude'
        }
    }
    environment {
        ANTHROPIC_API_KEY = credentials('anthropic-api-key')
    }
    stages {
        stage('Claude Review') {
            steps {
                script {
                    sh '''
                        npm install -g @anthropic-ai/claude-code
                        claude -p "审查代码变更" --print --permission-mode plan
                    '''
                }
            }
        }
    }
    post {
        failure {
            echo 'Claude review failed but pipeline continues'
        }
    }
}

# .claude/routines/daily-standup.md
# 每天早上9:30自动生成团队站会摘要

cron: 30 9 * * 1-5
channel: slack-standup
permission-mode: plan
max-turns: 5
---

分析昨天今天的工作进展：

1. 查看 git log --since="24 hours ago" 获取所有提交
2. 总结主要变更：按功能分类（新功能/修复/重构）
3. 标注正在进行的任务
4. 输出格式为 Slack Markdown，适合直接发送

# .claude/routines/weekly-report.md
# 每周五下午5点生成周报

cron: 0 17 * * 5
channel: email-report
permission-mode: plan
max-turns: 10
---

生成本周工作总结：

1. 汇总本周所有 git 提交
2. 统计代码变更量（增删行数）
3. 列出本周关闭的 issues
4. 输出为中文周报格式，包含：
   - 本周完成
   - 下周计划
   - 风险/阻塞

# .claude/channels/telegram.md
channel: telegram
config:
  bot_token: ${TELEGRAM_BOT_TOKEN}
  chat_id: "-1001234567890"
---

# 当Claude完成重要任务时，推送通知到这个频道

# .claude/routines/error-monitor.md
cron: */30 * * * *
channel: telegram  # 结果推送到Telegram
permission-mode: plan
---

分析最近30分钟的日志，发现ERROR/FATAL级别的异常立即报警。

# .claude/channels/discord.md
channel: discord
config:
  webhook_url: ${DISCORD_WEBHOOK_URL}

# .claude/channels/custom-webhook.md
channel: webhook
config:
  url: "https://api.your-company.com/claude-results"
  headers:
    Authorization: "Bearer ${WEBHOOK_TOKEN}"
    Content-Type: "application/json"

# .claude/channels/imessage.md
channel: imessage
config:
  recipients:
    - "+8613800138000"
    - "lao.k@icloud.com"

┌─────────────┐    PR事件    ┌──────────────┐   审查结果   ┌───────────────┐
│ GitHub Repo │─────────────►│ GitHub Actions│────────────►│ PR Comment    │
└─────────────┘              │  (Claude)    │             └───────────────┘
                              └──────┬───────┘
                                     │ 异常/定时
                              ┌──────▼───────┐
                              │  Routine     │
                              │  daily-report│
                              └──────┬───────┘
                                     │
                              ┌──────▼───────┐
                              │  Telegram    │
                              │  Channel     │
                              └──────────────┘

# .github/workflows/ai-pipeline.yml
name: AI Pipeline

on:
  pull_request:
    types: [opened, synchronize, reopened]
  issue_comment:
    types: [created]

jobs:
  # Job 1: 代码审查
  code-review:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Claude Review
        run: |
          claude -p "$(cat .claude/prompts/pr-review.md)" \
            --print \
            --permission-mode plan \
            --max-turns 10 \
            --output-format json > review.json || echo '{"result":"AI审查暂时不可用"}' > review.json

  # Job 2: 注释触发的检查
  comment-trigger:
    if: github.event_name == 'issue_comment' && contains(github.event.comment.body, '/claude')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Process Command
        run: |
          COMMAND=$(echo "${{ github.event.comment.body }}" | sed 's/\/claude //')
          claude -p "$COMMAND" --print --permission-mode acceptEdits --max-turns 5

# .claude/routines/daily-code-health.md
cron: 0 9 * * 1-5
channel: telegram
permission-mode: plan
max-turns: 8
---

分析昨日所有仓库的提交，生成代码健康日报：

1. 检查是否有 TODO/FIXME/HACK 注释增加
2. 检查是否有大文件提交（>500行变更）
3. 检查测试覆盖率变化
4. 输出简洁的Markdown报告

# .claude/channels/telegram.md
channel: telegram
config:
  bot_token: ${TELEGRAM_BOT_TOKEN}
  chat_id: ${TELEGRAM_CHAT_ID}
  parse_mode: Markdown

from anthropic import Anthropic

client = Anthropic()
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=4096,
    messages=[{"role": "user", "content": "帮我审查这段代码的安全性"}]
)

from claude_agent_sdk import ClaudeAgent, tool

agent = ClaudeAgent(
    model="claude-sonnet-4-20250514",
    max_turns=10,        # 最多10轮工具调用
    permission_mode="plan",
)

response = agent.query("分析src/auth.py的安全问题")
print(response.result)

response = agent.query(
    prompt="审查所有Python文件的类型注解完整性",

    # === 上下文注入 ===
    system_prompt="你是Python类型系统专家。用中文回复。",  # 系统级指令
    allowed_tools=["Bash", "Read", "Grep"],              # 工具白名单
    disallowed_tools=["Write", "Edit"],                  # 工具黑名单
    add_dir=["src/", "lib/"],                            # 额外工作目录

    # === 行为控制 ===
    max_turns=15,                    # 最大推理轮数
    permission_mode="acceptEdits",   # 权限模式
    model="claude-sonnet-4-20250514", # 模型选择

    # === 输出控制 ===
    output_format="json",            # text | json | stream-json
    verbose=True,                    # 详细日志

    # === 高级 ===
    resume="session_abc123",         # 恢复会话
    mcp_servers=["pg-explorer"],     # 加载MCP服务器
    skills=["code-review.md"],       # 加载Skills
)

from claude_agent_sdk import types as t

messages = [
    t.user("帮我分析这个函数的性能"),
    t.assistant("我来分析。首先读取文件内容。"),
    t.tool_use(id="call_1", name="Read", input={"file_path": "src/heavy.py"}),
    t.tool_result(
        tool_use_id="call_1",
        content="def heavy(): ...",
        is_error=False
    ),
    # Claude继续推理...
]

async for event in agent.stream_query("分析代码质量"):
    match event:
        case t.TextDelta(text=chunk):
            print(chunk, end="", flush=True)  # 逐字输出
        case t.ToolUse(name=name, input=params):
            print(f"\n🔧 调用工具: {name}({params})")
        case t.ToolResult(output=content):
            print(f"✅ 工具完成: {len(content)} chars")
        case t.AssistantMessage(content=final):
            print(f"\n\n=== 最终回复 ===\n{final}")
        case t.Error(message=msg):
            print(f"\n❌ 错误: {msg}")

# 模式1：无状态（每次query独立）
agent.query("fix bug in auth.py")

# 模式2：手动管理会话
session = agent.create_session()
session.query("read auth.py")
session.query("find the security issue")
session.query("fix it")
session.close()  # 释放资源
stats = session.usage  # 获取token用量

# 模式3：持久化会话（保存到磁盘）
session = agent.create_session(
    session_id="my-project-session",
    persist=True,  # 自动保存到 ~/.claude/sessions/
)
session.query("analyze codebase")
# 程序退出后...
session2 = agent.resume_session("my-project-session")
session2.query("continue the analysis")

# 查看当前会话状态
info = session.info()
print(f"消息数: {info.message_count}")
print(f"Token用量: {info.total_tokens}")
print(f"工具调用次数: {info.tool_calls}")

# 获取会话完整历史
history = session.get_messages()
for msg in history:
    print(f"{msg.role}: {msg.content[:80]}...")