thinking-tools

结构化思考框架 - 提升 Agent 工作质量的自我反思模式。 - 验证所收集信息的完整性 - 确保遵循原始任务要求 - 在停止前确认工作确已完成 - 识别理解或实现方面的不足 - 防止范围蔓延和偏离主题

概述

此技能提供三种结构化思考模式，Agent 应在任务执行的关键节点使用。这些模式有助于保持质量，并避免研究不完整、任务偏离和过早结束等常见错误。

思考模式 1：思考已收集的信息

何时使用：完成一系列复杂的搜索步骤后，例如：

• 阅读多个文件
• 搜索符号或模式
• 探索目录结构
• 收集需求

自我评估问题：

## Information Completeness Check

1. **Sufficiency**: Do I have enough information to proceed?
   - [ ] I understand the relevant code structure
   - [ ] I know the dependencies and relationships
   - [ ] I have identified all affected components

2. **Relevance**: Is all collected information relevant?
   - [ ] Information directly relates to the task
   - [ ] No tangential exploration
   - [ ] Focused on actionable insights

3. **Gaps**: What am I missing?
   - [ ] Are there files I should read but haven't?
   - [ ] Are there patterns I should search for?
   - [ ] Do I need to understand related systems?

4. **Confidence**: How confident am I in my understanding?
   - [ ] High: Ready to proceed
   - [ ] Medium: Minor clarification needed
   - [ ] Low: More research required

**Decision**: [Proceed / Gather More Information / Ask User]

反思示例：

I've read the authentication module (auth.ts) and the user model (user.ts).
I understand how login works but I haven't checked:
- How session tokens are managed
- Where logout is implemented
- What the error handling pattern is

Decision: Read session.ts and error-handler.ts before proceeding.

思考模式 2：思考是否遵循任务要求

何时使用：进行任何代码更改（插入、替换、删除）之前。此步骤对于确保你仍在解决原始问题至关重要。

自我评估问题：

## Task Adherence Check

1. **Original Task**: What was I asked to do?
   - Restate the original request clearly
   - Identify the core goal

2. **Current Action**: What am I about to do?
   - Describe the planned change
   - Explain how it relates to the goal

3. **Alignment Check**:
   - [ ] This action directly addresses the original task
   - [ ] I am not adding unrequested features
   - [ ] I am not "improving" code that wasn't asked about
   - [ ] The scope is appropriate for the request

4. **Scope Creep Warning Signs**:
   - Am I refactoring code that works?
   - Am I adding "nice to have" features?
   - Am I fixing unrelated issues I noticed?
   - Have I drifted from the original ask?

**Decision**: [Proceed / Refocus / Ask User for Clarification]

反思示例：

Original Task: "Fix the login timeout error"

I'm about to:
1. Fix the timeout by increasing the limit (directly addresses task)
2. Also refactor the error messages (NOT requested)
3. Also add retry logic (NOT requested)

Decision: Only implement #1. The other changes are scope creep.
If user wants those improvements, they can request them separately.

思考模式 3：思考是否已经完成

何时使用：当你认为已完成任务时。此步骤可以防止过早结束，并确保质量。

自我评估问题：

## Completion Validation Check

1. **Requirements Met**:
   - [ ] All explicit requirements addressed
   - [ ] All implicit requirements considered
   - [ ] Edge cases handled

2. **Quality Checks**:
   - [ ] Code compiles/runs without errors
   - [ ] Tests pass (or new tests written)
   - [ ] No regressions introduced
   - [ ] Follows project conventions

3. **Documentation**:
   - [ ] Code is self-documenting or commented where needed
   - [ ] README updated if needed
   - [ ] Breaking changes documented

4. **Verification Steps Taken**:
   - [ ] Ran relevant tests
   - [ ] Tested manually if applicable
   - [ ] Checked for lint/type errors

5. **Loose Ends**:
   - Any open tasks introduced?
   - Any known limitations?
   - Any follow-up work needed?

**Decision**: [Complete / Additional Work Needed / Partial Completion]

反思示例：

Task: "Add user email validation"

Requirements Check:
- [x] Email format validation added
- [x] Error message shows for invalid email
- [ ] Did NOT check: what about empty email?

Quality Check:
- [x] TypeScript compiles
- [ ] Tests: No tests written yet!

Decision: NOT complete. Need to:
1. Handle empty email case
2. Write unit tests for validation

集成指南

工作流集成

[Research Phase]
    |
    v
Think About Collected Information
    |
    v
[Planning Phase]
    |
    v
Think About Task Adherence (before each change)
    |
    v
[Implementation Phase]
    |
    v
Think About Whether You Are Done
    |
    v
[Completion or Iterate]

不适用场景

• 简单、琐碎的任务（修复拼写错误、重命名变量）
• 用户明确要求跳过验证时
• 不涉及代码更改的快速回答

记录反思

对于重要任务，将反思记录到记忆中：

## Task: [description]

## Reflection Log

### Information Gathering

- Files read: [list]
- Gaps identified: [list]
- Decision: [proceed/gather more]

### Task Adherence Check

- Original task: [description]
- Planned changes: [list]
- Scope assessment: [in-scope/adjusted]

### Completion Check

- Requirements: [met/partial/not met]
- Tests: [passed/failed/not run]
- Final status: [complete/needs work]

**场景**：Agent 被要求“修复失效的搜索功能”

阶段 1 - 研究后：

Think About Collected Information:
- Read search.ts, index.ts, searchUtils.ts
- Found the bug: incorrect regex pattern
- Checked: test file exists (search.test.ts)
- Gap: Haven't checked if there are related search files
Decision: Quick grep for "search" to ensure completeness...
Found search-config.ts which is relevant. Reading now.

阶段 2 - 编码前：

Think About Task Adherence:
- Original: "fix the broken search feature"
- Planned: Fix regex pattern in searchUtils.ts line 45
- Scope check: This directly fixes the bug. NOT adding new search features.
Decision: Proceed with targeted fix.

阶段 3 - 实现后：

Think About Whether You Are Done:
- [x] Bug fixed (regex corrected)
- [x] Existing tests still pass
- [ ] No new test for this specific case
Decision: Add regression test, then complete.

</usage_example>

**相关技能**： - `verification-before-completion` - 补充完成情况验证 - `tdd` - 测试驱动开发与完成情况检查相结合 - `sequential-thinking` - 结构化问题分解

铁律

1. 始终在任何研究或探索阶段后、进入实现阶段前，执行 think-about-collected-information
2. 绝不在“快完成”时跳过检查点——越接近完成，越要严格执行检查
3. 始终如实回答检查点问题；自我反思若流于自我辩解，就失去了意义
4. 绝不把检查点当作形式流程——如果检查点发现了不足，就先停下来解决，再继续
5. 始终在任务元数据中记录检查点的失败及其解决方式，以便追踪

反模式

反模式	失败原因	正确做法
快完成时跳过检查点	大多数错误会在后期显现；跳过检查点会掩盖这些错误	无论进度如何，都执行全部三个检查点
草草回答检查点问题	敷衍的回答会造成虚假的信心	每个检查点花 30 秒，如实作答
为警示信号找借口	借口会掩盖真正的问题	停下来修复检查点发现的任何问题
把检查点当作形式流程	不经反思地勾选复选框毫无价值	认真评估每个问题，并根据发现采取行动
只执行最后一个检查点	较早的检查点可以避免代价高昂的返工	在各自指定的触发节点使用全部三个检查点

记忆协议（必须遵守）

开始前： 阅读 .claude/context/memory/learnings.md

完成后：

• 发现新模式 -> .claude/context/memory/learnings.md
• 遇到问题 -> .claude/context/memory/issues.md
• 做出决定 -> .claude/context/memory/decisions.md

假设任务会被中断：如果没有记录在记忆中，就等于没发生。