Workflow (delivered by phase, evidence-driven)
Goal: turn "reading a repository" from an ad-hoc walkthrough into a reusable, engineered process:Narrow the scope → build a global map → trace entry points and critical paths → deep-dive high-leverage modules → summarize docs and onboarding → scoring and recommendations → generate MD+HTML deliverables for review。
Security and desensitization (must read)
When reading and delivering reports, by default treat repository contents as potentially containing sensitive information:
- Do notpaste into reports/chats: keys, tokens, cookies, private keys,
.envvalues, production connection strings, internal domains/intranet IPs, real user data. - When configuration needs to be referenced: list onlykey namesand purposes (mask values if necessary, e.g.
AKIA…WXYZ）。 - When logs/requests need to be referenced: prefer to showminimal fragments, and remove/replace sensitive fields (e.g.
Authorization、Set-Cookie、password）。 - When source code needs to be referenced: quote only the minimal fragments that support the conclusion; avoid large copies; locate as much as possible by "file path + symbol name + line number/range".
- If the user explicitly asks for sensitive details to be included: first confirm the scope and purpose for which they can be shared, then continue.
0) Clarify inputs and boundaries (ask clearly before starting)
- Confirm the repository path, branch/commit, and target readers (development/architecture/operations/product).
- Clarify the "anchor": from which entry point/function/CLI/HTTP route/task to start tracing (if the user did not provide one, choose the most common entry point and explain the basis).
- Clarify delivery: whether Mermaid diagrams are needed, whether MD+HTML is needed, whether "scoring/improvement recommendations" are needed, and whether runnable examples are needed.
1) Phase 1: Global Map (Architecture Map)
- Build a "directory-level view": responsibilities of top-level directories, core packages/modules, and the locations and purposes of examples/tests/docs/infra.
- Identify "assembly points/entry points": typical examples include
main/CLI, Web entry points, framework initialization, dependency injection, plugin registration, etc. - Produce a module dependency Mermaid diagram (it need not be precise down to the function level; prioritize stable and readable component-level relationships).
- Requirement: every key conclusion must be traceable tofile path + key symbol names (class/function/config key); provide line numbers when possible.
2) Phase 2: Entrypoint and Execution Flow (Entrypoint → Critical Path)
- Start tracing from the anchor symbol: definition → call sites → how key objects are initialized/injected/held.
- Break down "chained/pipeline-style calls" into steps: which fields/state each step modifies, which configurations it depends on, and which external boundaries it triggers (network/DB/queue/LLM/file system).
- Output:Step list (with method names/file paths) + (optional) Mermaid
sequenceDiagram。
3) Phase 3: Deep Dive into Core Modules (High-Leverage Subsystems)
Choose 3–6 modules that "most affect usage/extension/stability" for a deep dive (adjust according to repository type):
- Data models/validation/structured output: schema definitions, validation, retries/error correction, streaming parsing, etc.
- Workflows/orchestration: DSL/state machines/event systems/concurrency control/observability.
- Tools/plugins/extension systems: registration, strategy selection, protocol interfaces, lifecycle, tracing.
- Model/Provider adaptation layer: configuration consumption, request/response normalization, boundaries for switching providers.
- Storage/Cache/Queue: consistency, error handling, replay/retry.
The recommended deep-dive output structure is fixed as:Concept → Code location → Core data structures → Key flows/algorithms → Examples → Extension points。
4) Phase 4: Hands-on Practice and Secondary Development (Getting Started + Extensibility)
- Minimal dependencies: extract key dependencies from the dependency list (e.g.,
pyproject.toml/package.json/go.mod/Cargo.toml) and classify them (runtime/development/optional integration). - Get a minimal example running: list the required configuration (env/key/base_url/port/database), as well as common pitfalls (network, permissions, streaming, timeouts, etc.).
- Secondary development extension points: when adding a new module/node/rule, where should you change things, what patterns should you follow, and how to write minimal tests/examples for verification.
5) Phase 5: In-Repository Documentation Summary (Docs for Dev/Agent)
- Read the in-repository
docs/、CONTRIBUTING、AGENTS.md, as well as the "dedicated documentation directory for AI/developers". - Summarize three types of information: recommended organization approach, core API usage specifications, encouraged/prohibited patterns (including reasons/risks).
6) Phase 6: Scorecard and Improvement Suggestions
- Use a 100-point scale with multi-dimensional (≥8) scoring; each dimension must be supported by "observed facts/evidence points" to avoid vagueness.
- Output: total score + sub-scores + explanation + Top improvement suggestions (sorted by impact/cost).
- See the scoring dimension template in
references/scoring_rubric.md。
7) Deliverable Generation (Markdown + Standalone HTML)
- Create/update in the repository:
docs/repo_review.mdanddocs/repo_review.html(or at a user-specified path). - HTML is readable offline: self-contained CSS, includes a table of contents; Mermaid at least retains code blocks (optional CDN rendering but must not depend on the network).
- You can use a script to render HTML (stdlib-only):
scripts/render_md_to_html.py。
Quality Gates (How to Ensure Delivery Quality)
Before outputting the final report, self-check item by item:
- Traceability: key conclusions can all be traced to specific files/symbols (provide line numbers when necessary); do not speculate without basis.
- Coverage: every question raised by the user has a clear answer (or a clear explanation of the reason why "it was not found in the repository/cannot be confirmed").
- Diagrams: at least 1 Mermaid diagram (module dependencies); for execution paths, it is recommended to provide another sequenceDiagram.
- Actionability: Getting Started provides at least one executable path (command + configuration items), and lists common pitfalls and troubleshooting.
- Extensibility explanation: point out at least 2–4 extension points (plugin/extension/hook/interface), and provide an extension step checklist.
- Scoring credibility: each dimension has evidence and trade-offs; the total score calculation is transparent.
- Deliverable readability: Markdown has a table of contents and clear hierarchy; HTML can be opened and read directly, and code blocks do not break the layout.
Resources (read as needed to avoid occupying context)
scripts/
scripts/render_md_to_html.py: render the report Markdown into offline HTML (stdlib-only).scripts/repo_snapshot.py: Generate a repository snapshot (languages/key files/scale) for reference in the report (optional).
references/
references/report_outline.md: Report outline template (Phase 1–6 + appendix).references/mermaid_templates.md: Mermaid diagram templates (module dependency diagram + sequence diagram).references/scoring_rubric.md: Scoring dimensions and scoring criteria (100-point scale).