thinking-tools

構造化思考フレームワーク - エージェントの質の高い作業のための自己振り返りパターン。 - 収集した情報の完全性を検証する - 元のタスクに沿っていることを確認する - 作業を本当に完了してから停止する - 理解や実装における不足を特定する - スコープの拡大や本筋から外れた作業を防ぐ

概要

このスキルでは、タスクの実行中に重要なタイミングでエージェントが使用する、3つの構造化思考パターンを紹介します。これらのパターンは、品質を維持し、不十分な調査、タスクの逸脱、早すぎる完了といったよくある間違いを防ぐのに役立ちます。

思考パターン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]

**シナリオ**：エージェントが「壊れた検索機能を修正して」と依頼される

フェーズ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. 調査または探索のフェーズ後、実装に進む前に、必ず収集した情報について考える
2. 「ほぼ完了」の段階でも、チェックポイントを省略してはならない — 完了間際こそ、最も厳密に適用する
3. チェックポイントの質問には、必ず正直に答える。合理化は自己振り返りの目的を損なう
4. チェックポイントを形式的な儀式として使ってはならない — チェックポイントで不足が明らかになったら、作業を止め、先に解決する
5. 追跡可能性を確保するため、チェックポイントで見つかった問題とその解決策を、必ずタスクのメタデータに記録する

アンチパターン

アンチパターン	失敗する理由	適切なアプローチ
完了間際にチェックポイントを省略する	ほとんどのエラーは終盤に表面化するため、省略すると見逃す	進捗にかかわらず、3つすべてのチェックポイントを適用する
チェックポイントの質問に急いで答える	表面的な回答は誤った安心感を生む	チェックポイントごとに30秒かけ、正直に答える
危険信号を合理化して無視する	言い訳によって本当の問題が覆い隠される	チェックポイントで明らかになった問題は、作業を止めて修正する
チェックポイントを形式的な儀式として使う	振り返りのないチェック項目の確認には価値がない	各質問を真剣に評価し、見つかった問題に対処する
最後のチェックポイントだけを実施する	早い段階のチェックポイントが、コストのかかるやり直しを防ぐ	指定されたタイミングで3つすべてを使用する

## メモリプロトコル（必須）

開始前： .claude/context/memory/learnings.md を読みます。

完了後：

• 新しいパターンを発見した場合 -> .claude/context/memory/learnings.md
• 問題が発生した場合 -> .claude/context/memory/issues.md
• 決定した場合 -> .claude/context/memory/decisions.md

中断が発生するものと想定してください。メモリに記録されていないことは、起きていないことと同じです。