• Analyze the architecture and design of open source projects
• Compare design differences between two similar projects
• Deeply research the implementation ideas of a framework or library

• Simple code problems or debugging
• Single file analysis or code review
• Code modifications that do not involve the architecture level

• Why is it designed this way? Not just "what pattern is used", but "why it is suitable for this scenario"
• What if it's not designed this way? The cost of alternative solutions
• What is the gap with industry best practices? Advantages and room for improvement
• If you redesign it? Show deeper understanding
• What is the systematic design philosophy? The style throughout the project (such as "Convention over Configuration", "Zero-cost Abstraction")

❌ The routing system adopts the middleware pattern and supports chained calls.

✅ The routing system chooses the onion model instead of the linear pipeline. The linear pipeline is simpler to implement, but the onion model allows each middleware to handle both request and response stages at the same time - which is crucial for logging, timing, and error recovery. Express chose the linear model back then, and later had to use various hacks to handle post-response logic. Koa learned the lesson and switched to the onion model. If I were to redesign it, I would consider adding middleware dependency declarations to let the framework automatically sort them - this is the approach of Fastify, which can avoid hidden bugs caused by order.

• Code as the sole basis - All conclusions have code basis, mark

  file path

  or

  file path:line number range

  , prohibit vague expressions
• Approachable tone - Like a senior engineer doing onboarding for new colleagues, add subjective evaluations and suggestions, avoid AI-style clichés
• Deep dive on key points, brief on secondary content - Conduct in-depth analysis of core innovation points, and mention general utility functions in one sentence
• Critical thinking - Compare with industry practices, point out real problems, do not avoid defects. Refer to analysis-guide.md
• Fluent and easy to understand writing - The overall writing should be fluent and natural, so that entry-level engineers can also understand and learn. Avoid being too academic or piling up terms
• Avoid chronological listing without depth - Each module should reflect deep details, cannot be mentioned in one sentence or generalized. Add corresponding Mermaid architecture diagrams to each module if appropriate, so that readers can get inspiration and learn the essence of design after reading

1. Parse user input (supports

   owner/repo

   , GitHub/GitLab/Gitee URL, local path, project name)
2. Create workspace: Create

   repo-analyses/${REPO_NAME}-{YYYYMMDD}

   directory under the user's home directory as

   $WORK_DIR

   (cross-platform: use

   $HOME

   for macOS/Linux, use

   $USERPROFILE

   or

   $HOME

   for Windows)
3. Skip clone if the user provides a local path, otherwise run

   git clone --depth=1

   to clone the repository
4. Obtain basic metadata (Star, Fork, contributors, code statistics)

1. Count effective lines of code (exclude skippable code), list the distribution by module
   • Definition of skippable code: test code, build/deployment configuration (Dockerfile, CI yaml, etc.), automatically generated code (protobuf generated, lock files, etc.), example/documentation code
   • Use tools such as

     find

     +

     wc -l

     or

     cloc

     for statistics, grouped by top-level directory
2. Report code scale to the user, use AskUserQuestion to let the user choose the analysis mode:

1. Write the code scale statistics and the analysis mode selected by the user into

   drafts/03-plan.md

   , and control the analysis depth according to this in subsequent stages

• Coverage = Union of line ranges actually requested through the Read tool / Total lines of the file
• For large files (>500 lines), they must be read in segments to ensure that the following key paragraphs are covered:
  • Type definitions and imports at the head of the file (first 100 lines)
  • Core business logic functions (located through directory structure or function names)
  • Test code at the end of the file (if any)
• If only a small part of the file (<30%) is read, it will not be included in the coverage and will be regarded as "unread"
• Automatically generated code (proto generated, lock files, etc.) can reduce coverage requirements: just scan the structure, no need to read line by line

1. Use WebSearch to search for project evaluations, comparisons, and architecture discussions (at least 3-5 searches)
2. Traverse the project official website (if exists):
   • Extract the official website URL from README or GitHub page
   • Use WebFetch/tavily_crawl to traverse key pages of the official website (homepage, Features, Use Cases, Comparison, Blog, etc.)
   • Focus on extracting: product positioning (tagline), typical usage scenarios, official competitor comparisons, user cases/testimonials
   • The official website content is often the best source to understand "why this product is needed", which is more direct than code and technical documents
3. Read through the project's own documents:
   • Architecture documents (directories such as

     architecture/

     ,

     docs/

     ,

     design/

     , etc.)
   • Developer guidelines such as CONTRIBUTING.md, AGENTS.md
   • RFC, ADR (Architecture Decision Records), design proposals, etc.
   • These documents often contain the developer's design ideas, trade-offs, and historical decision background, which are first-hand information to understand "why it is designed this way"
   • Extract key design decisions and ideas from the documents into research notes
4. Organize research findings and write them into

   drafts/03-research.md

   , which must include the following structured paragraphs (mark "not found" if information is insufficient):
   • Core problems solved by the project: Describe pain points with 1-3 specific scenarios (who, under what circumstances, what problems encountered, why existing solutions are not sufficient)
   • Competitor/similar project comparison: List 3-5 most relevant competitors, explain their respective positioning differences and technical route differences
   • Why this project needs to be built separately: Can't it be solved by combining existing solutions? What is the unique value proposition of this project?
   • Organizational motivation behind the project (if applicable): Strategic considerations of commercial companies, ecological positioning of open source communities
5. Generate analysis plan and write it into

   drafts/03-plan.md

1. Quick scan: Scan entry files, directory structure, dependency declarations, project documents, README
2. Identify core project characteristics:
   • Project type and positioning (library/framework/application/tool)
   • Scale and maturity
   • Design style signals (type gymnastics, minimalist API, configuration-driven, etc.)
   • Technology stack characteristics (emerging technologies, multi-language, specific runtime)
   • Community positioning (core infrastructure, application layer tools, teaching projects, etc.)
3. Extract questions from characteristics: Generate targeted questions based on observed project characteristics. Questions should help focus the analysis direction, not just follow the process
   Thinking process - each observation may imply a question worth asking the user:
   • Observed technology selection → Ask about motivation (uncommon technology combination? Self-implemented functions that are usually solved by third-party libraries?)
   • Observed architecture characteristics → Ask about priority (performance optimization traces? Complex plugin/extension system?)
   • Observed design tension → Ask about trade-offs (simplicity vs flexibility? Burden of backward compatibility?)
   • Observed project positioning → Ask about audience (who is the target user? Is it an alternative or a gap filler in the ecosystem?)
   Dimension inspiration - what project characteristics imply what analysis angles:
   • Small and sophisticated library → API design philosophy, boundary delineation; Large framework → Modular strategy, backward compatibility, ecological governance
   • Use of emerging technologies → Why choose it, migration cost; Multi-language/multi-paradigm → Language boundary design
   • A large number of generics/type gymnastics → Type safety vs complexity trade-off; Minimalist API → How simplicity is achieved, what is sacrificed
   Characteristics of good questions: Specific (based on phenomena observed in the code), valuable for analysis (answers will affect the analysis direction), answerable by users (ask about concerns and preferences, do not ask technical details that require in-depth code to answer), non-repetitive (do not ask questions that can be answered through code)
4. Ask the user: Use AskUserQuestion tool to ask the user questions, no more than 3 questions at a time
   • One of the questions should confirm the level of detail at the beginning of the report: For well-known projects, users may not need lengthy product introductions and competitor comparisons, and just want to go directly to code analysis. Ask the user whether they need scenario-based introduction and competitor positioning chapters, or directly start with project overview and code analysis
5. Unlimited rounds: Multiple rounds of questions can be asked until the direction is clear, and new key分歧 points found during the analysis can be further asked

1. Synthesize information: Combine the research of Phase 3, project characteristics of Phase 4 and user answers
2. Design chapter structure: Do not use fixed templates, but must meet the skeleton constraints (see below)
3. Output report outline: Output the designed report outline to the user for confirmation before continuing
4. Identify modules: Track core data flow, identify N logical modules (divided by business function), divided into core modules and secondary modules
5. Design module narrative line: Determine the presentation order and transition logic of modules in the report, not arranged by directory structure, but organized according to the best path for readers to understand:
   • Choose the main narrative line: data flow driven (which modules the request goes through from entry to exit), layer driven (from bottom to top), or problem driven (expand layer by layer from core problems to solutions)
   • Write the transition logic between every two adjacent modules: the output/problem/limitation of the previous module → leads to the necessity of the next module
   • Write the narrative line into

     drafts/05-modules-plan.md

     , format example: Module A →[Output of A needs to be consumed by B]→ Module B →[B solves X but leads to Y problem]→ Module C
6. Write into plan: Output module list and report outline and write into

   drafts/05-modules-plan.md

• There is scenario-based problem introduction (use specific scenarios to clearly explain what problems the project solves, the shortcomings of existing solutions, why this project is needed - materials come from Phase 3 research notes). Note: If the user indicates in Phase 4 that lengthy introduction is not needed (e.g. the project is already very well-known), this chapter can be simplified or skipped, and start directly with the project overview
• There is competitor positioning (key differences from similar projects, not a feature list comparison, but differences in design philosophy and technical route). Note: Same as above, users can choose to skip
• There is project overview (let readers quickly understand what the project is and what problems it solves)
• There is in-depth analysis (Why of core design, trade-offs, comparison with the industry)
• There is evaluation and inspiration (honest advantages and disadvantages, what readers can learn from it)
• There is architecture visualization (Mermaid charts)
• All conclusions have code basis

• After completing the analysis of each subsystem/submodule, immediately write this part to the draft file
• The first subsystem uses Write to create the file, and subsequent subsystems use Edit to append
• Do not wait until all files are read before writing at one time
• Append the coverage detail table at the end

• After the subagent is started, the main agent shall not read the source code files responsible for the subagent
• The main agent should focus on during the waiting period: reading project documents (architecture/, docs/), external research, designing report skeleton, preparing the fusion framework for Phase 8
• The standard for judging whether a subagent is stuck: no new lines are added to the output file for more than 5 minutes. Only after confirming that it is stuck, the main agent can take over the analysis of this module
• No early merging is strictly prohibited: Must wait for all subagents to complete before starting the merging work of Phase 7 and Phase 8. Do not start writing the final report while some subagents are still running

1. Read the coverage detail table at the end of each

   drafts/06-module-*.md

2. Quick check: Whether there is a coverage table at the end of each draft, whether the total line is marked as meeting the standard (✅/❌)
3. Only modules marked ❌ or missing coverage tables need in-depth inspection
4. Non-compliant modules → The main agent automatically supplements reading of uncovered key files, and appends supplementary findings to the corresponding draft
5. Still not compliant after supplementation → Report to the user which modules are not compliant and the reasons (e.g. too large files, binary files, etc.)

1. Select 2-3 key conclusions from each core module draft
2. Go back to the source code to verify the accuracy of the conclusions line by line
3. Correct the corresponding content in the draft if deviations are found

1. Cross-verify cross-module conclusions marked [To be verified by main agent]
2. Comprehensively answer exploration questions, identify cross-module design patterns
3. Verify global correlation: Whether the analysis of each module is connected to the overall design philosophy of the project
4. Write into

   drafts/07-cross-validation.md

1. Refine architecture insights and systematic design philosophy
2. Deepen competitor comparison based on Phase 3 research results (supplement search only when Phase 3 information is insufficient)
3. Propose "if redesign" improvement suggestions
4. Write into

   drafts/08-insights.md

5. Multi-source fusion: Take the report chapter structure designed in Phase 5 as the skeleton, extract content from each draft to fill. When the same concept appears in multiple drafts, take the most detailed version and supplement the unique information of other versions. Eliminate all jump instructions such as "see draft X", "see appendix" after fusion
   • Narrative coherence: Organize module chapters according to the narrative line designed in Phase 5. The beginning of each module chapter must have 1-2 transitional sentences connecting the conclusions or questions of the previous module. Avoid abrupt transitions such as "Next we analyze X module", use natural transitions instead (e.g. "Gateway completes the authentication and routing of requests, but it is only responsible for 'who can come in', not 'what can be done after coming in'. This behavior control responsibility is undertaken by the policy engine.")
6. Write in segments: The final report is usually more than 500 lines, first Write the first few chapters (200-300 lines), then append with Edit later, Read to confirm the end position before each append
7. Coverage summary: Summarize the coverage data and write into

   drafts/08-coverage.md

   (not included in the final report)
   • Data is directly extracted from the coverage detail table at the end of each subagent draft, no need for the main agent to recalculate
   • If the main agent supplemented reading in Phase 7, add the supplemented lines to the "read lines" of the corresponding module
   • Summary table format:

1. Summarize and generate the final report (excluding coverage chapters)

• Extra large projects (>50000 lines): Prioritize analysis of core modules, use Agent to analyze in parallel
• Comparative analysis mode: Complete Phase 1-4 for the two projects respectively, then design a comparative report structure in Phase 5, add "design decision comparison" and "selection suggestion" to the skeleton constraints

1. The final report is a single markdown file:

   $WORK_DIR/ANALYSIS_REPORT.md

2. Use a large number of Mermaid charts to show architecture, processes, and data flows
3. Targeted at developers who need to understand business architecture
4. The evaluation thinking framework for highlights and problems refers to analysis-guide.md
5. The analysis philosophy and depth standards refer to analysis-guide.md