research-codebase（研究代码库）

Research Codebase

You are tasked with conducting comprehensive research across the codebase, spawning parallel sub-agents if necessary and synthesizing their findings.

CRITICAL: YOUR ONLY JOB IS TO DOCUMENT AND EXPLAIN THE CODEBASE AS IT EXISTS TODAY

• DO NOT suggest improvements or changes unless explicitly asked for them
• DO NOT propose future enhancements unless explicitly asked for them
• ONLY describe what exists, where it exists, how it works, and how components interact
• You are creating a technical map/documentation of the existing system

Steps to follow

1. Read any directly mentioned files first:

- If the user mentions specific files, read them FULLY first - CRITICAL: Read these files yourself in the main context before spawning any sub-tasks - This ensures you have full context before decomposing the research

1. Analyze and decompose the goal of the research:

- Think deeply about the research goal and break it down into composable research areas - Take time to ultrathink about the underlying patterns, connections, and architectural implications. - Identify specific components, patterns, or concepts to investigate - Create a research plan using TodoWrite/write_todos to track all subtasks - Consider which directories, files, or architectural patterns are relevant

1. Spawn parallel sub-agent tasks for comprehensive research: The key is to use these agents intelligently:

- Create multiple Task agents to research different aspects concurrently - Start with locator agents to find what exists - Then use analyzer agents on the most promising findings - Run multiple agents in parallel when they're searching for different things

1. Wait for all sub-agents to complete and synthesize findings:

- IMPORTANT: Wait for ALL sub-agent tasks to complete before proceeding - Compile all sub-agent results (both codebase and thoughts findings) - Prioritize live codebase findings as primary source of truth - Use dev/log/ as supplementary historical context - Connect findings across different components - Include specific file paths and line numbers for reference - Highlight patterns, connections, and architectural insights and decisions - Answer the user's specific questions with concrete evidence

1. Gather metadata for the research document:

- Generate all relevant metadata - Filename: dev/research/YYYYMMDD-description.md - Format: YYYYMMDD-description.md where: - YYYYMMDD is today's date - description is a brief kebab-case description of the research topic - Examples: - 20251010-parent-child-tracking.md - 20260114-authentication-flow.md

1. Generate research document:

- Use the metadata gathered in step 4 - Structure the document with YAML frontmatter followed by content: ` --- date: [Current date and time with timezone in ISO format] topic: "[User's Question/Topic]" tags: [research, codebase, relevant-component-names] status: complete last_updated: [Current date in YYYY-MM-DD format] --- # Research: [User's Question/Topic] **Date**: [Current date and time with timezone from step 4] ## Research Question [Original query or research goal] ## Summary [High-level findings] ## Detailed Findings ### [Component/Area 1] - Finding with reference ([file.ext:line](link)) - Connection to other components - Implementation details ### [Component/Area 2]... ## Code References - path/to/file.py:123 - Description of what's there - another/file.ts:45-67 - Description of the code block ## Architecture Insights [Patterns, conventions, and design decisions discovered] ## Historical Context (from dev/log/) [Relevant insights from dev/log/ directory with references] - dev/log/something.md - Historical decision about X - dev/log/notes.md - Past implementation of Y ## Related Research [Links to other research documents in dev/research/] ## Open Questions [Any areas that need further investigation] `

1. Sync and present findings:

- Present a concise summary of findings to the user - Include key file references for easy navigation - Ask if they have follow-up questions or need clarification

1. Handle follow-up questions:

- If the user has follow-up questions, append to the same research document - Update the frontmatter fields last_updated and last_updated_by to reflect the update - Add last_updated_note: "Added follow-up research for [brief description]" to frontmatter - Add a new section: ## Follow-up Research [timestamp] - Spawn new sub-agents as needed for additional investigation - Continue updating the document and syncing

Important notes:

• Always use parallel Task agents to maximize efficiency and minimize context usage
• Always run fresh codebase research - never rely solely on existing research documents
• The dev/log/ directory provides historical context to supplement live findings
• Focus on finding concrete file paths and line numbers for developer reference
• Research documents should be self-contained with all necessary context
• Each sub-agent prompt should be specific and focused on read-only operations
• Consider cross-component connections and architectural patterns
• Include temporal context (when the research was conducted)
• Keep the main agent focused on synthesis, not deep file reading
• Encourage sub-agents to find examples and usage patterns, not just definitions
• Explore all of dev/ directory, not just research subdirectory
• File reading: Always read mentioned files FULLY (no limit/offset) before spawning sub-tasks
• Critical ordering: Follow the numbered steps exactly

- ALWAYS read mentioned files first before spawning sub-tasks (step 1) - ALWAYS wait for all sub-agents to complete before synthesizing (step 4) - ALWAYS gather metadata before writing the document (step 5 before step 6) - NEVER write the research document with placeholder values

• Frontmatter consistency:

- Always include frontmatter at the beginning of research documents - Keep frontmatter fields consistent across all research documents - Update frontmatter when adding follow-up research - Use snake_case for multi-word field names (e.g., last_updated, git_commit) - Tags should be relevant to the research topic and components studied