analyze-new-repo

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Analyze New Repo

分析新代码仓库

Produce a reliable repository analysis without pretending certainty where the evidence is thin.

The goal is not to generate a lightweight summary. The goal is to produce a compact, evidence-backed analysis that helps the reader understand:

what this project is really trying to do
how it is organized and how it runs
which design decisions define the repository
what constraints, risks, and blind spots matter most
where the architectural center of gravity really is

在证据不足时，不要强行给出确定结论，要产出可靠的仓库分析报告。

我们的目标不是生成浅显的摘要，而是产出一份简洁、有证据支撑的分析报告，帮助读者理解：

该项目的核心目标是什么
项目的组织架构与运行机制
定义该仓库的关键设计决策
最关键的约束条件、风险与盲区
架构的核心重心所在

When To Use

使用场景

Use this skill when the user:

brings in a new repository and wants orientation
asks what the project does or how it is structured
wants build, run, or test commands for an unfamiliar codebase
asks for a repo walkthrough or onboarding summary
wants a high-confidence first-pass architecture analysis before making changes

Do not use this skill for a narrow one-file question or a known bug in an already-understood codebase.

当用户出现以下需求时，可使用此方法：

拿到新仓库并需要快速熟悉
询问项目功能或结构
需要陌生代码库的构建、运行或测试命令
请求仓库漫游讲解或入门总结
在修改代码前需要高可信度的初步架构分析

请勿将此方法用于单一文件的窄幅问题，或已熟悉代码库中的已知Bug排查。

Working Style

工作风格

Move from surface evidence to high-leverage internals.

Start with repository instructions and top-level docs before reading implementation files.
Prefer concrete evidence over guesswork.
Mark inference as inference.
Compress unimportant details.
Explain not just what exists, but why it matters.
Write like a senior engineer or code analyst: technically opinionated, calm, and precise.
Avoid sounding like an onboarding checklist or a generic repo summary.

从表层证据逐步深入到核心内部逻辑。

先阅读仓库说明与顶层文档，再查看实现文件。
优先依据具体证据，而非主观猜测。
明确标记推断内容。
压缩无关紧要的细节。
不仅说明现有内容，还要解释其重要性。
以资深工程师或代码分析师的口吻撰写：专业严谨、客观冷静、表述精准。
避免写成入门检查清单或通用仓库摘要。

Investigation Workflow

调研流程

1. Establish Repository Context

1. 明确仓库上下文

Read the highest-value orientation sources first:

```
AGENTS.md
```
```
README*
```

top-level docs such as

docs/

CONTRIBUTING*

ARCHITECTURE*

CHANGELOG*

recent git history if it exists

Capture:

stated purpose
runtime and platform assumptions
documented build, run, and test commands
any local rules that affect future changes
what kind of repository this is: application, library, internal tool, template, skill pack, research repo, infrastructure repo, etc.

优先阅读最具价值的入门资料：

```
AGENTS.md
```
```
README*
```

顶层文档，如

docs/

、

CONTRIBUTING*

、

ARCHITECTURE*

、

CHANGELOG*

若存在，查看近期Git历史

需记录：

项目声明的目标
运行时与平台假设
文档中记录的构建、运行与测试命令
影响未来修改的本地规则
仓库类型：应用程序、库、内部工具、模板、技能包、研究仓库、基础设施仓库等

2. Inspect Repository Conventions and Workflow Signals

2. 检查仓库规范与工作流信号

Look for contribution and workflow artifacts that reveal how the project is maintained:

```
.github/ISSUE_TEMPLATE/
```
```
.github/PULL_REQUEST_TEMPLATE*
```
```
CONTRIBUTING*
```
```
CODEOWNERS
```
```
CODE_OF_CONDUCT*
```

Capture only what changes how the repo should be read:

issue and PR expectations
testing or release expectations
ownership clues
screenshots, migration notes, or eval evidence required in changes

If these files do not exist, say so briefly and move on.

寻找能体现项目维护方式的贡献与工作流相关文件：

```
.github/ISSUE_TEMPLATE/
```
```
.github/PULL_REQUEST_TEMPLATE*
```
```
CONTRIBUTING*
```
```
CODEOWNERS
```
```
CODE_OF_CONDUCT*
```

仅记录会影响仓库解读方式的内容：

Issue与PR的要求
测试或发布的预期
所有权线索
变更所需的截图、迁移说明或评估证据

若这些文件不存在，简要说明后继续下一步。

3. Map the Surface

3. 梳理表层结构

Inspect the top-level structure before diving into source.

Identify:

main application directories
tests, scripts, docs, assets, config, and CI folders
dependency manifests
likely entrypoints
directories that appear central versus peripheral

If the repository is large, sample representative directories and say that you are sampling.

在深入源码前，先检查顶层结构。

识别：

主应用目录
测试、脚本、文档、资源、配置与CI文件夹
依赖清单
可能的入口点
核心目录与次要目录

若仓库较大，可选取代表性目录进行抽样检查，并明确说明抽样情况。

4. Identify Execution Flow

4. 梳理执行流程

Use docs first, then verify against config files.

Find:

how the project starts
how it is built
how it is tested
deployment or release hints
environment assumptions and external services

If commands disagree across files, call that out explicitly.

先参考文档，再通过配置文件验证。

找出：

项目启动方式
构建方式
测试方式
部署或发布线索
环境假设与外部服务依赖

若不同文件中的命令存在冲突，需明确指出。

5. Read the Critical Path

5. 阅读关键路径

Open the central entrypoint and the main modules on the execution path.

For each important module, summarize:

role
key inputs and outputs
main collaborators
why it matters architecturally

Favor a small number of high-value modules over broad shallow coverage.

打开核心入口点与执行路径上的主要模块。

对每个重要模块，总结：

角色定位
关键输入与输出
主要协作模块
其在架构上的重要性

优先覆盖少量高价值模块，而非广泛浅尝辄止。

6. Assess Quality Signals

6. 评估质量信号

Look for:

test organization and obvious coverage shape
CI or automation
release flow
dependency hygiene
documentation completeness
maintenance hotspots or tight coupling

Report only what you can actually see.

检查以下内容：

测试组织与覆盖范围
CI或自动化流程
发布流程
依赖管理情况
文档完整性
维护热点或紧耦合模块

仅报告实际观察到的内容。

7. Call Out Risks and Unknowns

7. 指出风险与未知项

Be explicit about:

missing documentation
unclear runtime assumptions
fragile setup steps
test blind spots
surprising dependencies
parts that need deeper validation before changes

明确说明：

缺失的文档
模糊的运行时假设
脆弱的设置步骤
测试盲区
意外的依赖
修改前需要进一步验证的部分

Scale Strategy

规模适配策略

Adjust depth to repository size instead of pretending every repo deserves the same treatment.

Small repos: read the main files directly and go deeper on the true control path.
Medium repos: inspect the full surface, then choose the 3-5 modules that define execution and architecture.
Large repos or monorepos: explicitly say you are sampling. Start from manifests, workspace config, root docs, CI, and top-level app/package directories before diving into internals.
If the repo is too large for full coverage, prefer breadth-first orientation plus one or two representative deep reads.

根据仓库大小调整分析深度，而非对所有仓库采用相同方式。

小型仓库： 直接阅读主文件，深入分析核心控制路径。
中型仓库： 检查完整表层结构，再选择3-5个定义执行与架构的核心模块。
大型仓库或Monorepo： 明确说明抽样分析。从清单、工作区配置、根文档、CI与顶层应用/包目录入手，再深入内部。
若仓库过大无法全面覆盖，优先进行广度入门，再选取1-2个代表性模块深入分析。

Monorepo Strategy

Monorepo策略

If the repository is a monorepo, do not describe it as if it were one application.

First identify the repository shape:

deployable applications
shared packages or libraries
infrastructure or devops directories
docs, examples, or auxiliary tooling

Then follow these rules:

Start with root-level manifests, workspace configuration, root README/docs, and CI workflows.
Use workspace manifests and CI to cross-check what is actually built, tested, and deployed.
Separate the repository into boundaries before summarizing behavior.
Identify which subprojects are primary and which are supporting.
After mapping the full shape, choose only the 1-2 most important subprojects for deeper analysis unless the user explicitly asks for exhaustive coverage.
Treat deployable apps, shared packages, and infrastructure as different architectural roles, not as peers in a flat list.
Call out when tests, CI, or deployment operate at different layers than the main application code.

When unsure, prefer a report structure like:

```
Repository Thesis
```
```
Repository Shape
```
```
Execution Model
```
```
Architectural Center of Gravity
```
```
Quality Signals and Risks
```

Use

references/monorepo-checklist.md

when the repo clearly has multiple packages, apps, or ownership boundaries.

若为Monorepo，不要将其当作单个应用描述。

首先识别仓库结构：

可部署应用
共享包或库
基础设施或DevOps目录
文档、示例或辅助工具

然后遵循以下规则：

从根目录清单、工作区配置、根README/文档与CI工作流入手。
通过工作区清单与CI交叉验证实际构建、测试与部署的内容。
在总结行为前，先划分仓库边界。
识别主项目与支撑项目。
梳理完整体结构后，除非用户明确要求全面覆盖，否则仅选择1-2个最重要的子项目进行深入分析。
将可部署应用、共享包与基础设施视为不同的架构角色，而非扁平列表中的同级项。
若测试、CI或部署与主应用代码处于不同层级，需明确指出。

若不确定，可采用以下报告结构：

```
仓库核心定位
```
```
仓库结构
```
```
执行模型
```
```
架构核心重心
```
```
质量信号与风险
```

当仓库明显包含多个包、应用或所有权边界时，参考

references/monorepo-checklist.md

。

Stack-Aware Hints

技术栈适配提示

Let dependency manifests influence where you look first.

```
package.json
```
, workspace files,
```
turbo.json
```
,
```
pnpm-workspace.yaml
```
: check scripts, workspaces, app/package split, and likely frontend/backend entrypoints.
```
pyproject.toml
```
,
```
requirements*.txt
```
,
```
uv.lock
```
: check CLI entrypoints, package metadata, tool config, and Python runtime assumptions.
```
Cargo.toml
```
: identify binaries vs libraries, workspace members, and feature flags.
```
go.mod
```
: check module boundaries,
```
cmd/
```
directories, and internal package layout.
```
docker-compose*
```
,
```
Dockerfile*
```
, Terraform, Helm, or deployment config: use these as evidence for operational shape, not just packaging.

If the stack is not covered above, use manifest filenames, workspace config, source layout, and CI workflows to infer the same things: entrypoints, package boundaries, build paths, and deployment shape.

These are hints, not a rigid language-specific playbook. Use them to improve reading order and entrypoint detection.

根据依赖清单调整优先检查的内容。

```
package.json
```
、工作区文件、
```
turbo.json
```
、
```
pnpm-workspace.yaml
```
：检查脚本、工作区、应用/包拆分，以及可能的前端/后端入口点。
```
pyproject.toml
```
、
```
requirements*.txt
```
、
```
uv.lock
```
：检查CLI入口点、包元数据、工具配置与Python运行时假设。
```
Cargo.toml
```
：识别二进制文件与库、工作区成员与功能标志。
```
go.mod
```
：检查模块边界、
```
cmd/
```
目录与内部包结构。
```
docker-compose*
```
、
```
Dockerfile*
```
、Terraform、Helm或部署配置：将其作为运维结构的证据，而非仅打包配置。

若技术栈未涵盖上述内容，可通过清单文件名、工作区配置、源码结构与CI工作流推断相同信息：入口点、包边界、构建路径与部署结构。

这些是提示，而非严格的语言特定指南。用它们优化阅读顺序与入口点识别。

Output Format

输出格式

Use the report template in

references/report-template.md

as the structure guide. Use

references/checklist.md

when you need a compact execution checklist before writing. Use

references/monorepo-checklist.md

when the repository is a clear monorepo.

Your output must:

open with a short section called
```
Repository Thesis
```
include 4-6 sections total, chosen to fit the repository
use concrete headings instead of a fixed universal set when the repo warrants it
always cover: purpose, execution path, key architecture, and risks or quality signals
prefer flat bullets, but use short paragraphs when a section needs stronger synthesis
make each bullet do at least two jobs: state a fact and explain its implication

Good section names include:

```
Repository Thesis
```
```
Repository Shape
```
```
Execution Model
```
```
Architectural Center of Gravity
```
```
Project Conventions
```
```
Quality Signals and Risks
```
```
Distinctive Design Decisions
```
```
Unknowns Worth Verifying
```

Avoid mechanically reusing the same section titles for every repository if the result feels generic.

以

references/report-template.md

作为结构指南。撰写前，可使用

references/checklist.md

作为简洁的执行清单。若为明确的Monorepo，使用

references/monorepo-checklist.md

。

输出必须：

以简短的
```
仓库核心定位
```
部分开头
总共包含4-6个章节，根据仓库情况选择
若仓库需要，使用具体标题而非固定通用标题
必须涵盖：目标、执行路径、核心架构、风险或质量信号
优先使用扁平列表，但当章节需要更强的综合分析时，可使用短段落
每个列表项需至少包含事实陈述与影响解释

合适的章节名称包括：

```
仓库核心定位
```
```
仓库结构
```
```
执行模型
```
```
架构核心重心
```
```
项目规范
```
```
质量信号与风险
```
独特设计决策
```
需验证的未知项
```

若结果会显得过于通用，避免机械重复相同的章节标题。

Evidence Rules

证据规则

Cite concrete file paths for important claims.
Distinguish clearly between confirmed facts, informed inference, and unknowns.
Prefer statements tied to a specific file over unsupported summaries.
Do not invent architecture details that were not verified.
If you cannot verify something, say so directly.
Prefer observations that connect evidence to architectural or maintenance consequences.

重要结论需引用具体文件路径。
明确区分已确认事实、合理推断与未知项。
优先采用与特定文件相关的陈述，而非无依据的总结。
不要编造未验证的架构细节。
若无法验证某内容，直接说明。
优先选择能将证据与架构或维护影响关联的观察结果。

Writing Quality Bar

写作质量要求

The result should read like a short analyst report, not a lightweight orientation blurb.

Specifically:

Do not merely restate README prose.
Do not flatten every repository into the same summary shape.
Surface the design decisions that make this repository distinctive.
Highlight what a technically strong reader would actually need to know before changing the code.
Keep it readable, but do not optimize for brevity so hard that the analysis loses weight.
Prefer bullets that combine fact + interpretation + implication.
Keep sentences compact, but allow a little density when the repo deserves it.
Avoid a mechanically symmetrical report if the repository has one dominant idea.

结果应读起来像一份简短的分析师报告，而非浅显的入门简介。

具体要求：

不要仅复述README内容。
不要将所有仓库都套入相同的总结框架。
突出该仓库独特的设计决策。
强调技术水平较高的读者在修改代码前真正需要了解的内容。
保持可读性，但不要为了简洁而牺牲分析深度。
优先采用“事实+解读+影响”的列表项。
保持句子简洁，但当仓库需要时，可适当增加密度。
若仓库有一个核心重点，避免撰写机械对称的报告。