1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

输出质量
     │
 100%├────────╮
     │        │╲
  80%│        │ ╲
     │        │  ╲ ← "中间迷失" 开始出现
  60%│        │   ╲
     │        │    ╲____
  40%│        │         ╲___
     │        │              ╲___
  20%│        │                   ╲
     └────────┴───────────────────────► Context 使用率 %
           20%   40%   60%   80%  100%

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

# Claude Code 错误日志

## 记录格式
- **Date**: 
- **Prompt**: [确切的文本]
- **Context %**: 
- **Files Loaded**: 
- **Failure Mode**: [wrong-output | hallucination | refusal | infinite-loop | context-rot]
- **What Claude Did**: 
- **What I Expected**: 
- **Root Cause**: [prompting | context | model-limitation]
- **Fix Applied**: 
- **Pattern Identified**: 

---

## 2025-01-03 | Auth 重构中的 Context 腐烂

**Prompt**: "Now refactor the auth module to use the new pattern" (现在重构 auth 模块以使用新模式)

**Context %**: 78%

**Files Loaded**: 12 files from src/auth/, 3 config files, previous conversation

**Failure Mode**: wrong-output (输出错误)

**What Claude Did**: 使用了旧模式，尽管 30 条消息前已经展示了新模式

**What I Expected**: 应用第 4 条消息中的新 auth 模式

**Root Cause**: context - 新模式处于“中间迷失”区域

**Fix Applied**: /clear → 重新陈述模式 → 指向包含该模式的具体文件

**Pattern Identified**: 如果 Context 使用率 >50%，在要求实施之前，务必重新陈述关键模式

---

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

---
description: Log a Claude Code error for pattern analysis
argument-hint: [failure-mode] [brief-description]
---

我需要为我的学习系统记录一个错误。请帮我填写这个模板：

**Failure Mode**: $1
**Brief Description**: $2

请一次一个地问我以下问题：
1. 触发此问题的确切 Prompt 是什么？
2. 发生时 Context % 是多少？
3. 加载了哪些文件？
4. 你预期的是什么 vs 实际发生了什么？
5. 你认为根本原因是什么？

然后将其格式化为 Markdown 条目，以便我可以将其追加到我的错误日志中。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

~/.claude/commands/          # 个人命令（随处可用）
├── quick/                   # 快速、简单的命令
│   ├── commit.md
│   ├── pr.md
│   └── review.md
├── research/                # 调查类命令
│   ├── deep-dive.md
│   ├── compare.md
│   └── audit.md
└── workflows/               # 多步骤流程
    ├── feature.md
    ├── debug.md
    └── refactor.md

.claude/commands/            # 项目命令（团队共享）
├── test.md
├── deploy.md
└── docs.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

---
description: Create a semantic commit with conventional format
allowed-tools: Bash(git diff:*), Bash(git status:*), Bash(git add:*), Bash(git commit:*)
model: claude-3-5-haiku-20241022
---

分析我暂存（staged）的更改并创建一个提交：

1. 运行 `git diff --cached` 查看暂存的更改
2. 运行 `git status` 了解范围
3. 生成遵循 Conventional Commits（约定式提交）的提交信息：
   - feat: 新功能
   - fix: 修复 bug
   - refactor: 代码重构
   - docs: 文档
   - test: 添加测试
   - chore: 维护杂项

4. 格式：`type(scope): brief description`
   - 保持在 72 个字符以内
   - 使用祈使语气（用 "add" 而不是 "added"）

5. 请求我确认，然后提交

如果没有暂存的更改，先帮我暂存相关文件。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

---
description: Create a comprehensive pull request
allowed-tools: Bash(git:*), Bash(gh:*)
argument-hint: [base-branch]
---

针对 $ARGUMENTS (默认: main) 创建一个 Pull Request：

1. 运行 `git log main..HEAD --oneline` 查看提交
2. 运行 `git diff main...HEAD --stat` 查看变更摘要
3. 生成包含以下内容的 PR：
   - Title: 符合主要变更的常规格式
   - Description:
     ## Summary
     [2-3 句话说明做了什么以及为什么]

     ## Changes
     - [关键变更的要点列表]

     ## Testing
     - [这是如何测试的]

     ## Screenshots
     [如果有 UI 变更，注明应添加截图]

4. 使用 `gh pr create` 和生成的内容创建 PR
5. 完成后输出 PR 的 URL

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

---
description: Deep dive into a bug or behavior
allowed-tools: Read, Grep, Glob, Bash(git log:*), Bash(git blame:*)
argument-hint: [issue-description]
---

调查：$ARGUMENTS

遵循这个系统化流程：

## 第一阶段：理解
- 预期行为是什么？
- 实际行为是什么？
- 什么时候开始的？（如果相关，检查 git log）

## 第二阶段：定位
- 使用 Grep 搜索相关代码
- 从入口点追踪代码路径
- 识别所有涉及的文件

## 第三阶段：分析
- 使用 git blame 了解历史
- 寻找可能导致此问题的近期更改
- 检查其他地方是否有相关问题/模式

## 第四阶段：报告
提供结构化报告：
1. **Root Cause (根本原因)**: [一句话]
2. **Affected Files (受影响文件)**: [列表]
3. **Recommended Fix (推荐修复)**: [方法]
4. **Risk Assessment (风险评估)**: [什么可能会坏]
5. **Test Plan (测试计划)**: [如何验证]

不要做任何更改。仅限调查。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

---
description: Generate comprehensive tests for a file or function
allowed-tools: Read, Write, Bash(npm test:*), Bash(pytest:*)
argument-hint: [file-or-function]
---

为以下内容生成测试：$ARGUMENTS

## 流程：

1. **阅读目标代码** - 理解所有路径和边缘情况
2. **确定测试框架** - 检查现有测试、package.json、pytest.ini
3. **生成覆盖以下内容的测试**：
   - Happy path (正常使用)
   - Edge cases (空值、null、边界值)
   - Error cases (无效输入、异常)
   - Integration points (外部依赖的 mock)

4. **遵循现有模式** - 匹配现有测试的风格
5. **运行测试** - 确保它们通过
6. **报告覆盖率缺口** - 还有什么未测试？

输出格式：遵循项目惯例创建测试文件。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

---
description: Security-focused code review
allowed-tools: Read, Grep, Glob
argument-hint: [file-or-directory]
---

对以下内容执行安全审计：$ARGUMENTS

## 检查：

### 输入验证
- [ ] SQL 注入漏洞
- [ ] XSS (跨站脚本)
- [ ] 命令注入
- [ ] 路径遍历

### 认证与授权
- [ ] 硬编码凭据
- [ ] 薄弱的会话处理
- [ ] 缺少权限检查
- [ ] 提权路径

### 数据处理
- [ ] 日志中的敏感数据
- [ ] 未加密的密钥
- [ ] PII (个人隐私信息) 暴露
- [ ] 不安全的反序列化

### 依赖项
- [ ] 已知的易受攻击包
- [ ] 过时的依赖项
- [ ] 未使用的依赖项

## 输出格式：
对于每个发现：
- **Severity (严重性)**: Critical / High / Medium / Low
- **Location (位置)**: file:line
- **Issue (问题)**: 描述
- **Recommendation (建议)**: 如何修复
- **Reference (参考)**: CWE 或 OWASP 链接（如果适用）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

---
description: Plan a refactoring without executing it
allowed-tools: Read, Grep, Glob
argument-hint: [what-to-refactor]
---

规划重构：$ARGUMENTS

## 不要进行任何更改 - 仅规划

### 分析阶段：
1. 阅读所有相关文件
2. 映射依赖关系（什么导入了这个？这个导入了什么？）
3. 确定测试覆盖率
4. 记录潜在的破坏性更改

### 输出重构计划：

```markdown
# Refactoring Plan: [title]

## Current State (当前状态)
[描述当前架构/代码]

## Desired State (目标状态)
[描述目标架构/代码]

## Steps (步骤 - 按顺序)
1. [ ] Step 1 - [描述] - 风险: Low/Med/High
2. [ ] Step 2 - [描述] - 风险: Low/Med/High
...

## Files to Modify (需修改的文件)
- `path/to/file.ts` - [什么变更]
- `path/to/other.ts` - [什么变更]

## Files to Create (需创建的文件)
- `path/to/new.ts` - [用途]

## Files to Delete (需删除的文件)
- `path/to/old.ts` - [为什么删除是安全的]

## Tests to Add/Update (需添加/更新的测试)
- [所需测试变更列表]

## Rollback Plan (回滚计划)
[如果出错如何撤销]

## Estimated Effort (预估工作量)
[时间预估]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

-----

## 4. 模式 3：用于确定性安全的 Hooks

### `--dangerously-skip-permissions` 的问题

`--dangerously-skip-permissions` 标志非常诱人。它消除了不断的“我可以运行 X 吗？”的提示，实现了真正的“心流”状态。但它之所以被称为“危险”，是因为 Claude 可以：
- 使用 `rm -rf` 删除文件
- 未经审查推送到 git
- 运行任意 shell 命令
- 修改系统文件

### 解决方案：通过 Hooks 建立护栏

Hooks（钩子）允许你在生命周期的各个点拦截 Claude 的动作并应用你自己的规则。模式如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

### Hook 配置

位置：`~/.claude/settings.json` 或 `.claude/settings.json`

#### 完整的安全 Hook 配置

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/bash-safety.sh"
          }
        ]
      },
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/write-safety.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write(*.py)",
        "hooks": [
          {
            "type": "command",
            "command": "python -m black \"$CLAUDE_FILE_PATHS\""
          }
        ]
      },
      {
        "matcher": "Write(*.ts)",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_FILE_PATHS\""
          }
        ]
      },
      {
        "matcher": "Write(*.tsx)",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_FILE_PATHS\" && npx tsc --noEmit \"$CLAUDE_FILE_PATHS\" 2>&1 || echo '⚠️ TypeScript errors'"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/session-summary.sh"
          }
        ]
      }
    ]
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

#!/bin/bash

# 从 stdin 读取工具输入
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# 定义危险模式
DANGEROUS_PATTERNS=(
    "rm -rf /"
    "rm -rf ~"
    "rm -rf \$HOME"
    "rm -rf \*"
    "> /dev/sd"
    "mkfs"
    "dd if="
    ":(){:|:&};:"         # Fork炸弹
    "chmod -R 777 /"
    "chown -R"
    "curl.*| bash"
    "wget.*| bash"
    "curl.*| sh"
    "wget.*| sh"
    "git push.*--force"
    "git push.*-f"
    "DROP TABLE"
    "DROP DATABASE"
    "DELETE FROM.*WHERE 1"
    "npm publish"
    "pip upload"
)

# 检查每个模式
for pattern in "${DANGEROUS_PATTERNS[@]}"; do
    if echo "$COMMAND" | grep -qE "$pattern"; then
        echo '{"decision": "block", "reason": "Blocked dangerous command pattern: '"$pattern"'"}'
        exit 0
    fi
done

# 阻止项目目录之外的操作（可选）
PROJECT_DIR=$(pwd)
if echo "$COMMAND" | grep -qE "cd\s+[^.]|cd\s+/(?!home)" ; then
    echo '{"decision": "ask", "reason": "Command navigates outside project directory"}'
    exit 0
fi

# 允许命令继续
exit 0

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

#!/bin/bash

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# 受保护的路径
PROTECTED_PATTERNS=(
    "^/etc/"
    "^/usr/"
    "^/bin/"
    "^/sbin/"
    "^\\.env$"
    "^\\.env\\."
    "^.*\\.pem$"
    "^.*\\.key$"
    "^.*_rsa$"
    "^package-lock\\.json$"
    "^yarn\\.lock$"
    "^pnpm-lock\\.yaml$"
)

for pattern in "${PROTECTED_PATTERNS[@]}"; do
    if echo "$FILE_PATH" | grep -qE "$pattern"; then
        echo '{"decision": "ask", "reason": "Protected file: '"$FILE_PATH"'"}'
        exit 0
    fi
done

exit 0

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

#!/bin/bash

# 记录会话结束和摘要
TIMESTAMP=$(date +%Y-%m-%d_%H:%M:%S)
LOG_FILE="$HOME/.claude/session-logs/$TIMESTAMP.log"

mkdir -p "$HOME/.claude/session-logs"

# 如果在 repo 中，获取 git diff
if git rev-parse --git-dir > /dev/null 2>&1; then
    echo "=== Session End: $TIMESTAMP ===" >> "$LOG_FILE"
    echo "" >> "$LOG_FILE"
    echo "=== Files Changed ===" >> "$LOG_FILE"
    git diff --name-only >> "$LOG_FILE"
    echo "" >> "$LOG_FILE"
    echo "=== Diff Summary ===" >> "$LOG_FILE"
    git diff --stat >> "$LOG_FILE"
fi

exit 0

1

chmod +x ~/.claude/hooks/*.sh

1
2
3
4
5

# 安全 YOLO 模式 - 跳过权限检查但 Hooks 会保护你
alias claude-yolo="claude --dangerously-skip-permissions"

# 额外安全 - 还在 Docker 中运行
alias claude-sandbox="docker run -it -v $(pwd):/workspace anthropic/claude-code --dangerously-skip-permissions"

1
2
3
4
5

## Context 管理规则

- NEVER auto-compact (绝对不要自动压缩)。我将手动管理 Context。
- 当 Context 超过 70% 时，立即警告我。
- 当超过 50% 时，在你的回复中包含 "Context: XX%" 的提示。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

---
description: Show current context status and recommendations
---

提供 Context 状态报告：

## Context Status (Context 状态)
- **Current Usage**: [X]% of context window
- **Estimated Tokens**: [X]k / 200k
- **Files in Context**: [主要文件列表]
- **Conversation Turns**: [X]

## Health Assessment (健康评估)
- [ ] Under 50%: ✅ 健康
- [ ] 50-70%: ⚠️ 考虑尽快清理
- [ ] Over 70%: 🔴 建议清理

## Recommendations (建议)
[如果超过 50%，建议可以清理或压缩什么]

## Key Context to Preserve (需保留的关键 Context)
[列出在 /clear 操作后应该保留的最重要事项]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   1. Start Fresh (全新开始): /clear                         │
│      └── 以干净的 Context 开始                              │
│                                                             │
│   2. Work Phase (工作阶段): 写代码，迭代                    │
│      └── 监控: "我的 Context 使用率是多少？"                │
│                                                             │
│   3. Checkpoint (检查点 - 50%): 记录状态                    │
│      └── 将重要决定保存到 CLAUDE.md 或笔记中                │
│                                                             │
│   4. Continue or Clear (继续或清理 - 70%):                  │
│      ├── 选项 A: 带明确指令的 /compact                      │
│      └── 选项 B: /clear + 从笔记恢复                        │
│                                                             │
│   5. Emergency (紧急情况): 双击 Esc                         │
│      └── 倒带回任意之前的状态                               │
│                                                             │
└─────────────────────────────────────────────────────────────┘

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

---
description: Compact context with explicit preservation rules
---

执行智能压缩：

## MUST PRESERVE (必须保留 - 永不总结掉):
1. 当前任务/目标
2. 过去 10 条消息中提到的所有文件路径
3. 我陈述的任何明确决定或约束
4. 错误信息及其解决方案
5. 当前计划/清单（如果存在）

## CAN SUMMARIZE (可以总结):
1. 导致死胡同的探索
2. 命令的冗长输出（只保留结论）
3. 未被修改的文件内容
4. 导致决策的一般性讨论（只保留决策）

## FORMAT (格式):
压缩后，在你的下一条消息开头加上：

1

现在带着这些规则执行 /compact。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

## Subagent Rules (子 Agent 规则)

- **ALWAYS use Opus for subagents (子 Agent 永远使用 Opus)** 除非我明确要求不这样做
- 子 Agent 应被用于：
  - 研究和调查任务
  - 多个文件的并行分析
  - 变更的代码审查
  - 测试生成
  - 文档编写
- 在生成子 Agent 之前，告诉我它将做什么
- 子 Agent 完成后，简洁地总结其发现

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

---
name: code-reviewer
description: Expert code review focusing on bugs, security, and maintainability
tools: Read, Grep, Glob
model: opus
---

你是一位资深代码审查员，专长于：
- 安全漏洞
- 性能问题
- 代码可维护性
- 测试缺口

在审查代码时：

1. **第一遍 - 关键问题**
   - 安全漏洞（注入、认证、数据暴露）
   - 可能导致 Bug 的逻辑错误
   - 竞态条件或并发问题

2. **第二遍 - 质量问题**
   - 代码重复
   - 需要重构的复杂函数
   - 缺少错误处理
   - 命名不清

3. **第三遍 - 建议**
   - 性能改进
   - 更好的模式/抽象
   - 文档需求

输出格式：

1

具体一点。包含行号。提出修复建议。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

---
name: test-writer
description: Writes comprehensive tests with edge case coverage
tools: Read, Write, Bash
model: opus
---

你是一位测试专家。在编写测试时：

## 原则
1. **测试行为，而非实现**
2. **每个测试一个断言**（在可行时）
3. **描述性的测试名称**: "should_return_empty_array_when_input_is_null"
4. **Arrange-Act-Assert** 结构
5. **系统性地覆盖边缘情况**

## 边缘情况清单
- [ ] Null/undefined 输入
- [ ] 空字符串/数组/对象
- [ ] 边界值 (0, -1, MAX_INT)
- [ ] 无效类型
- [ ] Unicode/特殊字符
- [ ] 并发访问（如果适用）
- [ ] 错误条件

## 测试结构

1

匹配代码库中现有的测试模式。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

---
name: architect
description: Analyzes codebase architecture and suggests improvements
tools: Read, Grep, Glob
model: opus
---

你是一位软件架构师。在分析代码时：

## 分析框架

### 1. 依赖分析
- 映射模块依赖
- 识别循环依赖
- 找出高耦合组件
- 定位上帝对象 (god objects)/模块

### 2. 模式识别
- 使用了什么架构模式？
- 它们的应用是否一致？
- 缺少什么模式会有帮助？

### 3. 可扩展性评估
- 瓶颈识别
- 水平扩展准备度
- 数据库/存储模式

### 4. 可维护性评分
1-10 分并给出理由：
- 代码组织
- 关注点分离
- 测试覆盖率
- 文档

## 输出格式
```markdown
# Architecture Analysis: [Component/System]

## Current State (当前状态)
[图表或描述]

## Strengths (优势)
- 

## Concerns (担忧)
-

## Recommendations (建议)
1. [优先级] 描述
2. [优先级] 描述

## Suggested Refactoring Roadmap (建议重构路线图)
Phase 1: [速赢项]
Phase 2: [中等工作量]
Phase 3: [重大重构]

1
2
3
4

### 编排器模式 (Orchestrator Pattern)

对于复杂任务，使用一个主 Agent + 专用子 Agent：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

### 子 Agent 监控仪表盘

参见 [第 8 节](#8-子-agent-监控仪表盘) 查看完整实现。

---

## 7. 模式 6：重提示（Reprompter）系统

### 手打 Prompt 的问题

- 高质量 Prompt 需要时间输入
- 打字会打断心流状态
- 容易忘记重要的约束条件
- Prompt 质量不一致

### 解决方案：语音 → 结构化管道

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

### 实现

#### 1. 语音输入设置

使用你的操作系统听写功能或类似工具：
- macOS: 内置听写 (Fn Fn)
- Windows: Windows 语音识别
- 跨平台: Whisper API, Talon

#### 2. Reprompter 命令 (`~/.claude/commands/reprompt.md`)

```markdown
---
description: Convert rough voice input into a structured prompt
argument-hint: [rough-idea]
---

我会给你一个粗糙的、语音口述的想法。你的工作是：

## Step 1: Understand (理解)
问我澄清性问题以了解：
- 具体目标是什么？
- 约束条件是什么？
- 成功是什么样子的？
- 我需要提供什么 Context？

一次问一个问题。等待我的回答。

## Step 2: Structure (结构化)
一旦你理解了，使用这种格式创建一个结构化的 Prompt：

```xml
<task>
  <goal>[清晰、具体的目标]</goal>

  <context>
    <files>[需阅读的相关文件]</files>
    <background>[关键背景]</background>
  </context>

  <constraints>
    <must>[必须包含的要素]</must>
    <must_not>[禁止的要素]</must_not>
  </constraints>

  <output>
    <format>[预期的输出格式]</format>
    <success_criteria>[如何验证成功]</success_criteria>
  </output>
</task>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

#### 3. 简单任务的快速重提示

创建 `~/.claude/commands/qr.md` (quick reprompt)：

```markdown
---
description: Quick reprompt - one clarifying question, then execute
argument-hint: [task]
---

任务：$ARGUMENTS

在执行之前，问我**一个**澄清性问题，以确保你理解这项任务最关键的方面。

在我回答后，继续执行。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

你: /reprompt 我需要重构那个 auth 的东西来使用我们讨论的新模式，你知道就是那个带中间件的

Claude: 我想确保我理解正确。当你说“带中间件的新模式”时，你指的是：
1. 我们在本此会话早些时候讨论的具体中间件模式？
2. 你们代码库中某处记录的模式？
3. 一个通用的中间件认证模式（比如 JWT 验证中间件）？

你: 第 2 个，在 docs/auth-v2.md 里

Claude: 明白了。再问一个问题：这次重构应该：
A) 完全替换现有的 auth 系统
B) 暂时与其并行运行（迁移路径）
C) 仅更新特定组件？

你: A，完全替换

Claude: 这是你的结构化 Prompt：

<task>
  <goal>重构认证系统以使用 docs/auth-v2.md 中定义的模式</goal>

  <context>
    <files>docs/auth-v2.md, src/auth/**, src/middleware/**</files>
    <background>现有 auth 的完全替换 - 无并行运行</background>
  </context>

  <constraints>
    <must>严格遵循 auth-v2.md 中记录的模式</must>
    <must>维护所有现有的受 auth 保护的路由</must>
    <must>包含现有用户会话的迁移</must>
    <must_not>保留任何已弃用的 auth 代码处于活动状态</must_not>
  </constraints>

  <output>
    <format>包含新 auth 实现的修改后的文件</format>
    <success_criteria>所有现有测试通过，添加了新 auth 测试，在 CHANGELOG 中记录</success_criteria>
  </output>
</task>

这是否捕捉了你的意图？准备好继续了吗？

1
2
3
4
5
6
7

# 创建监控目录
mkdir -p ~/.claude/monitoring
cd ~/.claude/monitoring

# 创建 package.json
npm init -y
npm install react react-dom next tailwindcss

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

import React, { useState, useEffect } from 'react';

interface SubagentLog {
  timestamp: string;
  agentName: string;
  task: string;
  model: string;
  tokensUsed: number;
  duration: number;
  status: 'running' | 'completed' | 'failed';
  result?: string;
}

interface SessionStats {
  totalTokens: number;
  totalDuration: number;
  agentBreakdown: Record<string, number>;
}

export default function Dashboard() {
  const [logs, setLogs] = useState<SubagentLog[]>([]);
  const [stats, setStats] = useState<SessionStats | null>(null);

  useEffect(() => {
    // 每 2 秒轮询一次更新
    const interval = setInterval(() => {
      fetchLogs();
    }, 2000);

    fetchLogs();
    return () => clearInterval(interval);
  }, []);

  const fetchLogs = async () => {
    try {
      const res = await fetch('/api/logs');
      const data = await res.json();
      setLogs(data.logs);
      setStats(data.stats);
    } catch (e) {
      console.error('Failed to fetch logs:', e);
    }
  };

  const getStatusColor = (status: string) => {
    switch (status) {
      case 'running': return 'bg-yellow-500';
      case 'completed': return 'bg-green-500';
      case 'failed': return 'bg-red-500';
      default: return 'bg-gray-500';
    }
  };

  return (
    <div className="min-h-screen bg-gray-900 text-white p-8">
      <h1 className="text-3xl font-bold mb-8">🤖 Subagent Monitor</h1>

      {/* 统计面板 */}
      {stats && (
        <div className="grid grid-cols-3 gap-4 mb-8">
          <div className="bg-gray-800 p-4 rounded-lg">
            <h3 className="text-gray-400 text-sm">Total Tokens</h3>
            <p className="text-2xl font-bold">{stats.totalTokens.toLocaleString()}</p>
          </div>
          <div className="bg-gray-800 p-4 rounded-lg">
            <h3 className="text-gray-400 text-sm">Total Duration</h3>
            <p className="text-2xl font-bold">{(stats.totalDuration / 1000).toFixed(1)}s</p>
          </div>
          <div className="bg-gray-800 p-4 rounded-lg">
            <h3 className="text-gray-400 text-sm">Active Agents</h3>
            <p className="text-2xl font-bold">
              {logs.filter(l => l.status === 'running').length}
            </p>
          </div>
        </div>
      )}

      {/* Agent 细分 */}
      {stats && (
        <div className="bg-gray-800 p-4 rounded-lg mb-8">
          <h3 className="text-lg font-semibold mb-4">Token Usage by Agent</h3>
          <div className="space-y-2">
            {Object.entries(stats.agentBreakdown).map(([agent, tokens]) => (
              <div key={agent} className="flex items-center">
                <span className="w-32 text-sm">{agent}</span>
                <div className="flex-1 bg-gray-700 rounded h-4">
                  <div 
                    className="bg-blue-500 h-4 rounded"
                    style={{ width: `${(tokens / stats.totalTokens) * 100}%` }}
                  />
                </div>
                <span className="w-24 text-right text-sm">
                  {tokens.toLocaleString()}
                </span>
              </div>
            ))}
          </div>
        </div>
      )}

      {/* 活动日志 */}
      <div className="bg-gray-800 rounded-lg overflow-hidden">
        <h3 className="text-lg font-semibold p-4 border-b border-gray-700">
          Activity Log
        </h3>
        <div className="divide-y divide-gray-700 max-h-96 overflow-y-auto">
          {logs.map((log, i) => (
            <div key={i} className="p-4 hover:bg-gray-750">
              <div className="flex items-center justify-between mb-2">
                <div className="flex items-center space-x-3">
                  <span className={`w-2 h-2 rounded-full ${getStatusColor(log.status)}`} />
                  <span className="font-medium">{log.agentName}</span>
                  <span className="text-gray-400 text-sm">({log.model})</span>
                </div>
                <span className="text-gray-400 text-sm">{log.timestamp}</span>
              </div>
              <p className="text-sm text-gray-300 mb-2">{log.task}</p>
              <div className="flex space-x-4 text-xs text-gray-500">
                <span>⏱ {log.duration}ms</span>
                <span>📊 {log.tokensUsed} tokens</span>
              </div>
              {log.result && log.status === 'completed' && (
                <div className="mt-2 p-2 bg-gray-900 rounded text-sm">
                  {log.result.substring(0, 200)}...
                </div>
              )}
            </div>
          ))}
        </div>
      </div>
    </div>
  );
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Task",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/monitoring/log-subagent.sh start"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Task",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/monitoring/log-subagent.sh complete"
          }
        ]
      }
    ]
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

#!/bin/bash

ACTION=$1
INPUT=$(cat)
TIMESTAMP=$(date -Iseconds)
LOG_FILE="$HOME/.claude/monitoring/logs/$(date +%Y-%m-%d).json"

mkdir -p "$HOME/.claude/monitoring/logs"

AGENT_NAME=$(echo "$INPUT" | jq -r '.tool_input.description // "unknown"')
MODEL=$(echo "$INPUT" | jq -r '.model // "unknown"')
TASK=$(echo "$INPUT" | jq -r '.tool_input.prompt // ""' | head -c 200)

if [ "$ACTION" = "start" ]; then
    echo "{\"timestamp\": \"$TIMESTAMP\", \"agentName\": \"$AGENT_NAME\", \"model\": \"$MODEL\", \"task\": \"$TASK\", \"status\": \"running\"}" >> "$LOG_FILE"
elif [ "$ACTION" = "complete" ]; then
    RESULT=$(echo "$INPUT" | jq -r '.result // ""' | head -c 500)
    TOKENS=$(echo "$INPUT" | jq -r '.tokens_used // 0')
    echo "{\"timestamp\": \"$TIMESTAMP\", \"agentName\": \"$AGENT_NAME\", \"model\": \"$MODEL\", \"status\": \"completed\", \"result\": \"$RESULT\", \"tokensUsed\": $TOKENS}" >> "$LOG_FILE"
fi

exit 0

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

Issue Detected (检测到问题)
      │
      ▼
  Small/Local? (小的/局部的?) ────Yes────▶ Escape Escape (Rewind)
      │                                       │
      No                                选取恢复点
      │                                       │
      ▼                                       ▼
  Code broken? (代码坏了?) ────Yes────▶ git checkout / git stash
      │
      No
      │
      ▼
  Context rot? (Context 腐烂?) ────Yes────▶ /clear + 带笔记重启
      │
      No
      │
      ▼
  Log to error journal for pattern analysis (记录到错误日志进行模式分析)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

# Project: [NAME]

## Overview
[2-3 句话描述项目]

## Tech Stack
- Language: [e.g., TypeScript 5.3]
- Framework: [e.g., Next.js 14]
- Database: [e.g., PostgreSQL + Prisma]
- Testing: [e.g., Jest + React Testing Library]

## Key Commands
- `npm run dev` - 启动开发服务器
- `npm run build` - 生产构建
- `npm run test` - 运行测试
- `npm run lint` - 运行 linter

## Project Structure

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

## Coding Standards (编码规范)
- 使用带 hooks 的函数式组件
- 优先使用具名导出 (named exports) 而非默认导出
- 每个文件一个组件
- 测试放在 `__tests__/` 目录中

## Important Patterns (重要模式)
- State management: [描述模式]
- API calls: [描述模式]
- Error handling: [描述模式]

## DO NOT (不要)
- 修改 `node_modules/` 中的文件
- 直接提交到 main 分支
- 跳过新功能的测试

## Subagent Rules (子 Agent 规则)
- 子 Agent 始终使用 Opus
- 生成子 Agent 前先通告
- 简洁总结子 Agent 的结果

## Context Management (Context 管理)
- 当 Context 超过 60% 时警告
- 当 >50% 时，在回复中包含 "Context: X%"
- 未经询问绝不自动压缩 (auto-compact)