repo-analyzer

Files (1)

• SKILL.md

SKILL.md (first lines)

# In-depth Git project analysis skills

We provide in-depth analysis of open-source projects and generate professional architecture reports. These reports offer profound technical insights, enabling readers to understand business problems, master architectural design, and develop their own critical thinking.

## When to Use

- Analyze the architecture and design of open source projects
- Compare the design differences between two similar projects
- In-depth study of the implementation ideas of a framework or library

## When NOT to Use

- Simple code issues or debugging
- Single file analysis or code review
- No code modifications required at the architectural level

## Output Language

The default language is Chinese. If the user asks a question in another language, the language used will be the same.

## Core Principles

### 1. Prioritize Business Perspective

Start with "What problem does this project solve?", not "What functions are in this file?"

| Don't | Yes |
| ----- | --- |

The `handleRequest(ctx)` function accepts a Context parameter... After a request comes in, the system will go through three stages: authentication, rate limiting, and route distribution...
| `interface MessageQueue { push(); pop() }` | Modules are decoupled through message queues; producers only need to post messages, and consumers pull messages according to priority.

### 2. Controlling the level of abstraction: Talking about design, not code.

By default, descriptions are presented at the design pattern and architecture level; **raw code is not shown unless absolutely necessary**. The focus is on the process, logic, and design principles, expressed using architecture diagrams (Mermaid), flowcharts, and tables, rather than code snippets. Code is only shown when the design is exceptionally ingenious, the project has a unique original concept, or the implementation is a core selling point, and in such cases, it must first be explained in natural language.

### 3. Global Associations

Every local analysis must be connected to the overall project design philosophy—this is the key difference between "code specifications" and "architectural analysis." See the global connections section in [analysis-guide.md](references/analysis-guide.md) for details.

### 4. Inspirational Writing

The goal is to **learn something and stimulate thinking**, not just provide a code manual. It's like a senior engineer explaining something on a whiteboard—with viewpoints, reasoning, and comparisons. See the inspirational writing section of [analysis-guide.md](references/analysis-guide.md) for details.

### 5. In-depth Insight: Why > What (Mandatory)

Every design decision must be explained in terms of motivation, trade-offs, and the costs of alternatives. Describing "what" is just the starting point; explaining "why" is where the value of the analysis lies. Every core module and the overall architecture must answer:
Why design it this way? It's not just about "what pattern was used," but rather "why it's suitable for this scenario."
What would happen if we didn't do it this way? The cost of the alternative.

- **Gap with industry best practices?** Areas of leadership and room for improvement.
- **If you were to redesign it?** Demonstrate a deeper understanding.
- **A systematic design philosophy?** A style that runs throughout the project (e.g., "convention over configuration," "zero-cost abstraction")

Example:

> ❌ The routing system uses a middleware pattern and supports chained calls.
>
> ✅ The routing system opted for an onion model instead of a linear pipeline. While linear pipelines are simpler to implement, the onion model allows each middleware to handle both request and response phases simultaneously—crucial for logging, timing, and error recovery. Express initially chose a linear model but later had to resort to various hacks to handle post-response logic; Koa learned from this experience and switched to the onion model. If I were to redesign it, I would consider adding middleware dependency declarations so the framework can automatically sort them—this is what Fastify does, avoiding hidden bugs caused by order.

### Supplementary Requirements

- **Code as the Standard** — All conclusions are supported by code, clearly marked with `file path` or `file path:line number range`. Vague descriptions are prohibited.
- **Human Touch** — Like a senior engineer giving an onboarding session to a new colleague, incorporate subjective evaluations and suggestions, avoiding AI-sounding clichés.
- **Focus on Key Points, Briefly Cover Secondary Aspects** — In-depth analysis of core innovations, with general utility functions briefly mentioned.
- **Critical Thinking** — Compare with industry practices, point out real problems, and do not shy away from shortcomings. See [analysis-guide.md](references/analysis-guide.md)
- **Fluent and Easy-to-Understand Writing** — The overall writing style should be fluent and natural, allowing even novice engineers to understand and learn from it. Avoid overly academic language or piling up jargon.
- **Avoid a rambling, disjointed account** — Each module should demonstrate in-depth detail, avoiding brief mentions or superficial discussions. If appropriate, each module should be accompanied by a corresponding Mermaid architecture diagram, ensuring readers are inspired and grasp the essence of the design.

## Analyzing Workflow

**Flexibility Principle:** All stages and sections below are advisory guidelines, not a checklist that must be strictly followed. The agent should make dynamic decisions based on the characteristics of the project being analyzed—if a stage or step is not relevant to the current project, it can be skipped or simplified. The quality of the final report is paramount.

### Phase 1: Project Acquisition and Initialization

1. Parse user input (supports `owner/repo`, GitHub/GitLab/Gitee URL, local path, project name)
2. Create a workspace: Create a directory `repo-analyses/${REPO_NAME}-{YYYYMMDD}` in the user's home directory as `$WORK_DIR` (cross-platform: macOS/Linux use `$HOME`, Windows use `$USERPROFILE` or `$HOME`).
3. If the user provides a local path, skip the clone step; otherwise, clone the repository using `git clone --depth=1`.
4. Obtain basic metadata (Star, Fork, Contributors, Code Statistics)

### Phase 2: Project Scale Assessment and Analysis Model Selection

1. **Count the number of valid lines of code** (excluding skippable code), and list the distribution by module.
   - Code definitions can be skipped: test code, build/deployment configuration (Dockerfile, CI yaml, etc.), automatically generated code (protobuf generation, lock files, etc.), and sample/documentation code.
   - Use tools like `find` + `wc -l` or `cloc` to perform statistics, grouping by top-level directory.
2. **Report code size to users**, using AskUserQuestion to allow users to select analytics modes:

| Pattern                         | Core Module Coverage | Secondary Module Coverage | Applicable Scenarios                           |
| ------------------------------- | -------------------- | ------------------------- | ---------------------------------------------- |
| Quick Analysis                  | ≥30%                 | ≥10%                      | Quickly understand the overall project picture |
| Standard Analysis (Recommended) | ≥60%                 | ≥30%                      | Conventional Architecture Analysis             |
| In-depth analysis               | ≥90%                 | ≥60%                      | Thoroughly examine each design decision        |

3. Write the code size statistics and user-selected analysis mode into `drafts/03-plan.md`, and use this to control the analysis depth in subsequent stages.

**Coverage Calculation Rules**:

- Coverage = Union of line ranges actually requested by the Read tool / Total number of lines in the file
- For large files (>500 lines), they must be read in segments to ensure that the following critical sections are covered:
  - Type definitions and imports in the file header (first 100 lines)
  - Core business logic functions (located by directory structure or function name)
  - Test code at the end of the file (if any)
- Reading only a small portion of a file (<30%) is not counted in the coverage rate and is considered "unread".
- Automatic code generation (proto files, lock files, etc.) can reduce coverage requirements: scanning the structure is sufficient, eliminating the need for line-by-line reading.

### Phase 3: External Research + Project Document Study (Search First, Then Read)

1. Use WebSearch to search for project evaluations, comparisons, and architecture discussions (at least 3-5 searches).
2. **Traverse the project's official website** (if it exists):
   - Extract the official website URL from the README or GitHub page
   - Use WebFetch/tavily_crawl to traverse key pages on the official website (Homepage, Features, Use Cases, Comparison, Blog, etc.).
   - Key takeaways: Product positioning tagline, typical use cases, official competitor comparison, user case studies/testimonials
     Official website content is often the best source for understanding "why this product is needed," as it's more direct than code and technical documentation.
3. **Read through the project's built-in documentation:**
   - Architecture documentation (directories such as `architecture/`, `docs/`, `design/`, etc.)
   - Developer guidelines such as CONTRIBUTING.md and AGENTS.md
   - RFC, ADR (Architecture Decision Records), design proposals, etc.
     These documents often contain the developer's design thinking, trade-offs, and historical decision-making background, making them invaluable primary sources for understanding "why it was designed this way."
   - Extract key design decisions and ideas from the document into your research notes.

From ntk148v/skills, MIT.

More from ntk148v/skills