research-synthesis について
research-synthesisは、Agent、スキル、ワークフロー、フック、スキーマ、テンプレートの作成前に調査結果を集約するエージェントスキルです。検索回数とレポート量を制限し、情報源間の矛盾の検出から調査手順、引き継ぎまでを定めています。
主な機能
- 01作成前の調査手順
- 02検索回数を3~5回に制限
- 03複数情報源の矛盾を検出
- 04調査レポートの構成
- 05作成スキルへの引き継ぎガイド
活用シーン
- 01スキル作成前の実装パターン調査
- 02複数情報源の推奨事項の比較
- 03連携やアーキテクチャ決定の計画
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/ / github.com/ oimiragieo/ agent-studio --skill research-synthesisインストール後、Claude Code で/research-synthesisを入力して読み込まれたか確認します。
同梱ファイル
SKILL.md と一緒にインストールされる参考資料やスクリプト。
commands/research-synthesis.mdhooks/post-execute.cjspre-execute.cjsreferences/research-requirements.mdrules/research-synthesis.mdschemas/input.schema.jsonoutput.schema.jsonscripts/main.cjstemplates/implementation-template.md詳細
Research Synthesis Skill
目的
新しい成果物(エージェント、スキル、ワークフロー、フック、スキーマ、テンプレート)を作成する前に、調査を行い、その結果を統合します。このスキルにより、すべての設計上の判断が次の根拠に基づくようになります。
- 現在のベストプラクティス(信頼できる情報源から)
- 実装パターン(実際の事例から)
- 既存のコードベースの規約(一貫性を維持するため)
- リスク評価(問題を予測するため)
このスキルを呼び出すタイミング
次の作業の前に必ず実施してください。
agent-creator- エージェントのパターンとドメインの専門知識を調査しますskill-creator- スキル実装のベストプラクティスを調査しますworkflow-creator- オーケストレーションのパターンを調査しますhook-creator- 検証と安全性のパターンを調査しますschema-creator- JSON Schema のパターンを調査しますtemplate-creator- コードのスキャフォールディングパターンを調査します
次の場合にも推奨します。
- 新機能の設計
- アーキテクチャに関する意思決定
- 技術の選定
- 統合の計画
絶対の原則
NO ARTIFACT CREATION WITHOUT RESEARCH FIRST
調査プロトコルを実行していない場合、成果物の作成に進むことはできません。
複数の情報源における矛盾の検出(Skill_Seekers unified_scraper に着想)
2 つ以上の情報源を統合する場合は、矛盾を積極的に検出して明示してください。これにより、矛盾する助言を知らないうちに採用することを防げます。
検出する矛盾の種類:
| 矛盾の種類 | 例 | 解決策 |
|---|---|---|
| バージョンの不一致 | 情報源 A は「v2 API を使用」とし、情報源 B は「v3 が必須」としている | 日付とともに明示し、より新しい情報を優先する |
| 相反する助言 | 情報源 A は「常に ORM を使用」とし、情報源 B は「性能のために生 SQL を使用」としている | 両方を背景とともに明示し、意思決定者に選んでもらう |
| 非推奨パターン | 情報源 A が推奨するパターンを、情報源 B が非推奨としている | 非推奨の通知とともに明示し、情報源 B を優先する |
| 互換性のない実装 | 情報源 A はコールバックを使用し、情報源 B は async/await を使用している | 入手可能な場合は移行方法も明示する |
検出プロトコル:
- すべての情報源から知見を収集した後、主張マトリクスを作成します。各情報源から事実に関する主張を抽出してください
- 同じトピックについて推奨内容が異なる場合を意味的な重複に基づいて検出し、主張を一つずつ比較します
- 矛盾ごとに、
{ claim_a, source_a, claim_b, source_b, conflictType, suggestedResolution }を記録します - 統合レポートに
conflictsセクションを含めます。一方を黙って選ぶことは決してしないでください
レポート内の矛盾の出力形式:
### Conflicts Detected (2)
1. **Version requirement** — React Router docs (2026-03) say v7 required for data loading; Stack Overflow answer (2025-11) assumes v6. **Resolution:** Use v7 (docs are authoritative and more recent).
2. **State management approach** — Official docs recommend Context API for simple state; community blog recommends Zustand universally. **Resolution:** Flag for architect — depends on app complexity.
クエリ上限(絶対の原則)
3-5 QUERIES MAXIMUM PER RESEARCH TASK
この上限を超えると、次の問題が発生します。
- メモリの枯渇(10 KB を超えるレポートにより、コンテキストウィンドウがあふれます)
- 情報過多(10 件以上の情報源を効果的に処理できません)
- 収穫逓減(量より質が重要です)
複雑さに応じたクエリ予算:
- 簡単な調査(事実確認、バージョン確認):3 クエリ
- 中程度の調査(機能の比較、実装パターン):4 クエリ
- 複雑な調査(包括的なベストプラクティス、エコシステムの概要):5 クエリ
絶対にしないこと:
- 1 回の調査セッションで 5 件を超えるクエリを実行する
- 範囲を定めない「すべてを調査する」クエリを実行する
- 関連のない複数の調査トピックを 1 回のセッションにまとめる
複数フェーズのパターン: 5 件を超えるクエリが必要な場合は、調査を複数のセッションに分割してください(下記の「複数フェーズの調査パターン」を参照)。
レポートサイズの上限(絶対遵守)
10 KB MAXIMUM PER RESEARCH REPORT
なぜ 10 KB なのですか?
- コンテキスト効率(10 KB = 約 2500 語 = 1 つのコンテキストウィンドウで読みやすい量)
- 優先順位付けを促す(必須の調査結果のみを含める)
- 「百科事典症候群」(記事全体をコピーすること)を防ぐ
形式に関する要件:
- 箇条書きを使う(簡潔にする)
- 内容をコピーする代わりに URL を参照する
- 情報源ごとの調査結果を 3 文未満で要約する
- ノイズを取り除き、重要な点を残す
10 KB に近づいた場合:
- 新しい情報源の追加をやめる
- 重複をまとめる
- 冗長な詳細を削除する
- 独自の知見に集中する
複雑なトピックの場合:
- 2~3 件のミニレポートに分割する(各 10 KB 未満)
- 各レポートは 1 つの側面に焦点を当てる
- サマリー内でレポート同士をリンクする
必須の調査プロトコル
ステップ 0:内部メモリの検索とコンテキスト負荷の確認(必須 - 最初のステップ)
外部の調査クエリを実行する前に、まずプロジェクトの内部メモリを検索してください。 内部に十分な信頼度の高い結果がある場合は、外部クエリを完全に省略してください。 その後、続行する前にコンテキスト負荷を確認してください。
// Sub-step 0a: Query internal RAG for cached research on the topic
const { searchInternalContext } = require('.claude/lib/memory/internal-rag.cjs');
const internalResults = await searchInternalContext(researchTopic, { limit: 5, threshold: 0.6 });
const avgSimilarity =
internalResults.results.length > 0
? internalResults.results.reduce((sum, r) => sum + (r.similarity || 0), 0) /
internalResults.results.length
: 0;
if (internalResults.results.length >= 3 && avgSimilarity > 0.7) {
// High-confidence internal hit — synthesize from internal results and skip external search
console.log(
'[research-synthesis] Internal RAG hit (avg similarity:',
avgSimilarity.toFixed(2),
') — skipping external search'
);
}
// Otherwise proceed to external queries below
// Sub-step 0b: Context pressure check
const { checkContextPressure } = require('.claude/lib/utils/context-pressure.cjs');
// Option A — token-budget-based (if budget info available)
const pressure = checkContextPressure({
tokenBudgetPercent: currentTokenBudgetPercent,
});
// Option B — text-based estimate (when budget % not available)
// const pressure = checkContextPressure({ text: recentContextSnapshot });
if (pressure.pressure === 'high') {
// STOP — compress context before researching
console.warn('[research-synthesis] High context pressure:', pressure.reason);
console.warn('Run context-compressor skill first, then re-invoke research-synthesis.');
// Return early without executing research queries
process.exit(0);
}
if (pressure.pressure === 'medium') {
// Proceed but limit to 3 queries (simple budget)
console.warn('[research-synthesis] Medium context pressure:', pressure.reason);
console.warn('Limiting to 3 queries. Consider compressing after research.');
}
// Low pressure → proceed normally with full query budget
遵守事項:
| 負荷 | アクション |
|---|---|
high | 停止 — context-compressor スキルを呼び出してから再試行する |
medium | クエリを 3 件に制限し、呼び出し元に警告する |
low | 通常どおり、クエリの全予算(3~5 件)を使って進める |
ステップ 1:調査範囲を定義し、クエリを計画する
クエリを実行する前に、調査範囲を定義し、クエリ数の予算を計画してください。
## Research Scope Definition
**Artifact Type**: [agent | skill | workflow | hook | schema | template]
**Domain/Capability**: [What this artifact will do]
**Complexity Assessment**:
- [ ] Simple (fact-checking, version checking) → 3 queries
- [ ] Medium (feature comparison, implementation patterns) → 4 queries
- [ ] Complex (comprehensive best practices, ecosystem overview) → 5 queries
**Planned Queries** (list 3-5 BEFORE executing):
1. [Query 1: Best practices - specific question]
2. [Query 2: Implementation patterns - specific question]
3. [Query 3: Framework/AI-specific - specific question]
4. [Optional Query 4: Security/performance - specific question]
5. [Optional Query 5: Trade-offs/alternatives - specific question]
**Key Questions**:
1. What are the best practices for this domain?
2. What implementation patterns exist?
3. What tools/frameworks should be used?
4. What are the common pitfalls?
**Existing Patterns to Examine**:
- .claude/[category]/ - Similar artifacts
- .claude/templates/ - Relevant templates
- .claude/schemas/ - Validation patterns
調査前チェックリスト:
[ ] Complexity assessed (3, 4, or 5 queries planned)
[ ] Queries planned BEFORE executing (prevents scope creep)
[ ] Each query is specific (not "research everything about X")
[ ] Report size target set (<10 KB)
[ ] Multi-phase split considered (if >5 queries needed)
ステップ 2:調査クエリを実行する(最大 3~5 件)
必ず 3~5 件の調査クエリを実行してください(これ以上は不可)。クエリが多すぎると、メモリの枯渇やコンテキストの喪失につながります。
クエリ 1:ベストプラクティス
// Using Exa (preferred for technical content)
mcp__Exa__web_search_exa({
query: '{artifact_type} {domain} best practices 2024 2025',
numResults: 5,
});
// Or using WebSearch (fallback)
WebSearch({
query: '{domain} best practices implementation guide',
});
クエリ 2:実装パターン
// Code-focused search
mcp__Exa__get_code_context_exa({
query: '{domain} implementation patterns examples github',
tokensNum: 5000,
});
// Or fetch from authoritative sources
WebFetch({
url: 'https://[authoritative-source]/docs/{topic}',
});
クエリ 3:Claude/AI エージェント固有の情報
// Framework-specific patterns
mcp__Exa__web_search_exa({
query: 'Claude AI agent {domain} {artifact_type} patterns',
numResults: 5,
});
// Or search for MCP patterns
WebSearch({
query: 'Model Context Protocol {domain} integration',
});
クエリ効率化のヒント:
- 一般的なクエリを 10 件使うより、質の高いクエリを 2~3 件使う
- 関連する質問は 1 つのクエリにまとめる(「X のベストプラクティス + 実装パターン」)
- 信頼できる情報源が既知の場合は WebFetch を使う(より高速で、焦点を絞れる)
- 独自の知見が十分に集まったら終了する(量より質)
ステップ 3:既存のコードベースを分析する
統合する前に、コードベース内の既存のパターンを確認してください。
// Find similar artifacts
Glob({ pattern: '.claude/{artifact_category}/**/*.md' });
// Search for related implementations
Grep({ pattern: '{related_keyword}', path: '.claude/' });
// Read existing examples
Read({ file_path: '.claude/{category}/{similar_artifact}' });
抽出する内容:
- 命名規則 - 類似の成果物にはどのような名前が付けられているか
- 構造パターン - どのようなセクションが含まれているか
- ツールの使用状況 - 類似の成果物でどのツールが使われているか
- スキルの依存関係 - よく割り当てられるスキルは何か
- 出力先 - 成果物の出力はどこに保存されるか
ステップ 4:調査結果を統合する
.claude/templates/reports/research-report-template.md に従って、構造化された調査レポートを出力します。
ファイルの場所:.claude/context/artifacts/research-reports/{topic}-research-{YYYY-MM-DD}.md
必須セクション:
- 出典情報ヘッダー:``
- エグゼクティブサマリー:主な調査結果の概要を 2~3 文で記載
- 調査方法:クエリの表 + 参照した情報源の表
- 詳細な調査結果:トピックごとに、主な知見、根拠、関連性を記載
- 学術文献:arXiv の論文、学術情報源(該当がない場合も記載)
- 実践的な推奨事項:P0/P1/P2 の優先順位付け
- リスク評価:影響度/発生確率/緩和策を含むリスク表
- 実装ロードマップ:次のステップとタイムライン
成果物の作成に関する調査では、以下も含めてください:
既存のコードベースのパターン
見つかった類似の成果物:
{path_1}- {その機能と使用しているパターン}{path_2}- {その機能と使用しているパターン}
特定された規約:
- 命名:{規約}
- 構造:{規約}
- ツール:{規約}
- 出力:{規約}
特定されたベストプラクティス
| # | プラクティス | 出典 | 確信度 | 根拠 |
|---|---|---|---|---|
| 1 | {practice} | {source_url_or_name} | 高 | {why_applicable} |
| 2 | {practice} | {source_url_or_name} | 中 | {why_applicable} |
| 3 | {practice} | {source_url_or_name} | 高 | {why_applicable} |
確信度のレベル:
- 高:複数の権威ある情報源で一致している
- 中:権威ある情報源が1つ、または二次情報源が複数ある
- 低:エビデンスが限られており、検証が必要
設計上の決定事項
| 決定事項 | 根拠 | 出典 | 検討した代替案 |
|---|---|---|---|
| {decision_1} | {why} | {source} | {what_else_was_considered} |
| {decision_2} | {why} | {source} | {what_else_was_considered} |
| {decision_3} | {why} | {source} | {what_else_was_considered} |
推奨される実装
ファイルの場所:.claude/{category}/{name}/
使用するテンプレート:.claude/templates/{template}.md
呼び出すスキル:
{skill_1}- {why}{skill_2}- {why}
必要なフック:
{hook_type}- {purpose}
依存関係:
- 既存の成果物:{list}
- 外部ツール:{list}
品質ゲートのチェックリスト
成果物の作成に進む前に、以下を確認します。
- 最低3件の調査クエリを実行済み
- 少なくとも3つの外部情報源を参照済み
- 既存のコードベースのパターンを文書化済み
- すべての設計上の決定事項に根拠と出典がある
- リスク評価を緩和策とともに完了済み
- 推奨する実装手順を文書化済み
- 正しい命名規則でレポートを保存済み:
{topic}-research-{YYYY-MM-DD}.md - 出典情報のヘッダーを含めている
次のステップ
- 作成スキルを呼び出す:
Skill({ skill: "{creator_skill}" }) - このレポートを入力として使用する:上記の決定事項を参照する
- チェックリストに照らして検証する:完了としてマークする前に行う
作成スキルとの連携
作成前のワークフロー
[AGENT] User requests: "Create a Slack notification skill"
[AGENT] Step 1: Research first
Skill({ skill: "research-synthesis" })
[RESEARCH-SYNTHESIS] Executing research protocol...
- Query 1: "Slack API best practices 2025"
- Query 2: "Slack MCP server integration patterns"
- Query 3: "Claude AI Slack notification skill"
- Analyzing: .claude/skills/*/SKILL.md for patterns
- Output: Research Report saved
[AGENT] Step 2: Create with research backing
Skill({ skill: "skill-creator" })
[SKILL-CREATOR] Using research report...
- Following design decisions from report
- Applying identified best practices
- Mitigating documented risks
引き継ぎ形式
調査の完了後、以下の内容を作成スキルに引き継ぎます。
## Research Handoff to: {creator_skill}
**Report Location**: `.claude/context/artifacts/research-reports/{artifact_name}-research.md`
**Summary**:
{2-3 sentence summary of key findings}
**Critical Decisions**:
1. {decision_1}
2. {decision_2}
3. {decision_3}
**Proceed with creation**: YES/NO
**Confidence Level**: High/Medium/Low
複数フェーズの調査パターン(複雑なトピック向け)
調査クエリが5件を超える場合は、フェーズに分割します。
フェーズ1:範囲と定義(2件のクエリ)
- トピック/テクノロジーとは何ですか?
- 重要な概念は何ですか?
フェーズ2:実装(2件のクエリ)
- 専門家はこれをどのように実装していますか?
- 一般的なパターンとベストプラクティスは何ですか?
フェーズ3:比較とトレードオフ(1件のクエリ)
- これは代替案と比べてどうですか?
- トレードオフと注意点は何ですか?
メリット:
- 各フェーズは独立しているため、コンテキストの混在を抑えられる
- スキルの呼び出しを分けて実行できる
- 整理が明確になる
- 調査結果を再利用しやすくなる
例:
Session 1: Research "Rust async/await" (Phase 1: 2 queries)
Session 2: Research "Tokio patterns" (Phase 2: 2 queries)
Session 3: Research "async-trait vs manual impl" (Phase 3: 1 query)
メモリを考慮したチャンク分割の例
良い例 - 焦点を絞ったクエリと分割されたレポート:
Query: "Rust async/await best practices 2026"
Report structure:
- Definition (100 words)
- Pattern 1: Tokio (200 words)
- Pattern 2: async-trait (150 words)
- Gotchas (100 words)
- Links (10 sources)
---Total: ~550 words, ~3 KB
悪い例 - 範囲が定められていない調査:
Query: "everything about Rust ecosystem 2026"
Report: 50 sources, 15 KB (truncated by context limit)
---Can't use findings without context loss
良い例 - フェーズに分けたアプローチ:
Phase 1 Report: Rust async fundamentals (3 KB)
Phase 2 Report: Tokio implementation patterns (4 KB)
Phase 3 Report: Performance comparison (2 KB)
---Total: 9 KB across 3 sessions (all usable)
悪い例 - 巨大なレポート1件にまとめる:
Single Report: Comprehensive Rust async guide (25 KB)
---Truncated to 10 KB, missing critical sections
品質ゲート
以下の項目がすべて合格した時点で、調査は完了です。
[ ] 3-5 research queries executed (NO MORE THAN 5)
[ ] At least 3 external sources consulted (URLs or authoritative names)
[ ] Existing codebase patterns documented (at least 2 similar artifacts)
[ ] ALL design decisions have rationale AND source
[ ] Risk assessment completed (at least 3 risks with mitigations)
[ ] Recommended implementation path documented
[ ] Report saved to output location
[ ] Report size <10 KB (check file size before saving)
作業停止条件:項目に1つでも不合格がある場合、調査は未完了です。成果物の作成に進まないでください。
出力先
- 調査レポート:
.claude/context/artifacts/research-reports/ - 一時メモ:
.claude/context/tmp/research/ - メモリの更新:
.claude/context/memory/learnings.md
レポートの命名規則(必須)
形式:{topic}-research-{YYYY-MM-DD}.md
- トピック:説明的なケバブケースの名前
- 日付の前に必ず
-research-を含めます - 日付:ハイフン区切りの ISO 8601 形式(YYYY-MM-DD)
例:
- ✓
oauth2-security-research-2026-02-09.md - ✓
json-schema-patterns-research-2026-02-09.md - ✓
slack-integration-best-practices-research-2026-02-09.md - ✗
agent-keywords-core.md(日付がありません) - ✗
oauth2-auth-2026-02-09.md(-research-の接尾辞がありません) - ✗
bmad-method-analysis-20260128-104050.md(日付形式が正しくありません)
テンプレート:すべての調査レポートで .claude/templates/reports/research-report-template.md を使用します
例
例 1:Slack スキルの作成前に調査する
// Step 1: Define scope
// Artifact: skill, Domain: Slack notifications
// Step 2: Execute queries
mcp__Exa__web_search_exa({
query: 'Slack API webhook best practices 2025',
numResults: 5,
});
mcp__Exa__get_code_context_exa({
query: 'Slack notification system implementation Node.js',
tokensNum: 5000,
});
WebSearch({
query: 'Claude AI MCP Slack server integration',
});
// Step 3: Analyze codebase
Glob({ pattern: '.claude/skills/*notification*/SKILL.md' });
Glob({ pattern: '.claude/skills/*slack*/SKILL.md' });
Read({ file_path: '.claude/skills/skill-creator/SKILL.md' });
// Step 4: Synthesize and output report
Write({
file_path: '.claude/context/artifacts/research-reports/slack-notifications-research.md',
content: '## Research Report: Slack Notifications Skill...',
});
例 2:データベースエージェントの作成前に調査する
// Research queries for database-architect agent
mcp__Exa__web_search_exa({
query: 'database design architecture best practices 2025',
numResults: 5,
});
WebFetch({
url: 'https://docs.postgresql.org/current/ddl.html',
});
mcp__Exa__web_search_exa({
query: 'AI agent database schema design automation',
numResults: 5,
});
// Analyze existing agents
Glob({ pattern: '.claude/agents/domain/*data*.md' });
Read({ file_path: '.claude/agents/core/developer.md' });
よくある調査分野
| 分野 | 主な検索クエリ | 信頼できる情報源 |
|---|---|---|
| API 統合 | "REST API design", "GraphQL patterns" | OpenAPI spec, GraphQL spec |
| セキュリティ | "OWASP top 10", "security best practices" | OWASP, NIST |
| データベース | "database design patterns", "SQL optimization" | PostgreSQL docs, MySQL docs |
| フロントエンド | "React patterns", "accessibility WCAG" | React docs, W3C |
| DevOps | "CI/CD best practices", "IaC patterns" | GitLab docs, Terraform docs |
| テスト | "TDD patterns", "test automation" | Testing Library, Jest docs |
| AI/ML | "LLM integration patterns", "prompt engineering" | Anthropic docs, OpenAI docs |
ファイルの配置と規則
出力先の規則
このスキルの出力先:.claude/context/artifacts/research-reports/
必須の参照資料
- ファイルの配置:
.claude/docs/FILE_PLACEMENT_RULES.mdを参照してください - 開発者ワークフロー:
.claude/docs/DEVELOPER_WORKFLOW.mdを参照してください - 成果物の命名:
.claude/docs/ARTIFACT_NAMING.mdを参照してください
適用
ファイルの配置は file-placement-guard.cjs フックによって適用されます。
無効な配置は、本番モードでブロックされます。
メモリプロトコル(必須)
開始前:
cat .claude/context/memory/learnings.md
以下を確認します:
- 類似分野に関する過去の調査
- 既知のパターンと規約
- 文書化された決定事項
完了後:
- 新たな調査結果 ->
.claude/context/memory/learnings.mdに追記します - 重要な決定事項 ->
.claude/context/memory/decisions.mdに追記します - 発見した問題 ->
.claude/context/memory/issues.mdに追記します
中断を想定してください:コンテキストがリセットされる場合があります。メモリに記録されていなければ、実行されていないものとして扱います。
ワークフローとの統合
このスキルは Creator Ecosystem と統合されています:
| Creator | 調査の重点 |
|---|---|
agent-creator | ドメインの専門知識、エージェントのパターン、スキルの依存関係 |
skill-creator | ツール統合、MCP のパターン、検証フック |
workflow-creator | オーケストレーションのパターン、マルチエージェント連携 |
hook-creator | 検証のパターン、セキュリティチェック、安全性のゲート |
schema-creator | JSON Schema のパターン、検証戦略 |
template-creator | コードのスキャフォールディング、プロジェクト構成のパターン |
ライフサイクル全体: .claude/workflows/core/skill-lifecycle.md
厳守事項
- 決して、最初に調査プロトコルを完了せずに成果物を作成してはいけません。十分な情報に基づかない作成は、既存のパターンと矛盾する判断につながり、コストのかかる手戻りを招きます。
- 決して、1 回の調査セッションで 5 件を超えるクエリを実行してはいけません。上限を超えるとメモリが枯渇し、コンテキストウィンドウがオーバーフローして、後半の調査結果が気づかれないまま失われます。
- 決して、10 KB を超える調査レポートを作成してはいけません。サイズの大きすぎるレポートはコンテキストウィンドウをオーバーフローさせ、最も重要なセクションの調査結果が切り捨てられます。
- 必ず、外部調査を統合する前に、既存のコードベースの成果物を少なくとも 2 つ分析してください。外部のベストプラクティスだけではプロジェクト固有の慣習を把握できず、一貫性のない実装につながります。
- 必ず、すべての設計判断について、その根拠となる情報源と理由を記録してください。根拠のない判断は、将来のリファクタリング時に評価、検討、追跡できません。
アンチパターン
| アンチパターン | 問題が起きる理由 | 正しいアプローチ |
|---|---|---|
| 調査プロトコルの実行前に成果物の作成を始める | 十分な情報に基づかない判断を招き、既存のパターンと矛盾して手戻りが発生します | 作成スキルを呼び出す前に、必ず research-synthesis を実行して品質ゲートを通過してください |
| 「徹底するため」に 10 件以上のクエリを実行する | メモリが枯渇してコンテキストがオーバーフローし、後半の調査結果が気づかれないまま失われます | 開始前に対象を絞ったクエリを 3~5 件ちょうど計画してください。複雑なトピックは別々の調査フェーズに分けます |
| 10 KB を超える網羅的な調査レポートを作成する | サイズの大きすぎるレポートはコンテキストウィンドウで切り捨てられ、作成スキルが最も必要とするセクションが隠れてしまいます | 箇条書きを使い、内容をコピーする代わりに URL を参照し、各情報源の要約を 3 文未満にしてください |
| 既存のコードベースを調べずに外部の調査結果を統合する | 外部のベストプラクティスは、確立されたプロジェクトのパターンや命名規則と矛盾する可能性があります | 設計判断を記述する前に、必ず glob を使って類似する既存の成果物を少なくとも 2 つ見つけて読み込んでください |
| 出典を引用せずに設計判断を記録する | 文書化されていない判断は、将来のリファクタリングサイクルで検証、検討、追跡できません | Design Decisions テーブルの各判断行に、情報源の URL または権威ある参照先の名称を必ず含めてください |