analyze-new-repo

分析新仓库

在证据不足时，不要假装确定，给出可靠的仓库分析。

目标不是生成一份轻量摘要，而是提供简洁且有证据支撑的分析，帮助读者了解：

• 这个项目真正要解决什么问题
• 项目的组织方式和运行方式
• 哪些设计决策定义了这个仓库
• 哪些约束、风险和盲点最重要
• 架构的重心究竟在哪里

适用场景

在用户遇到以下情况时使用此技能：

• 引入一个新仓库，希望快速了解情况
• 询问项目的用途或结构
• 想获取陌生代码库的构建、运行或测试命令
• 要求逐步讲解仓库，或提供入门摘要
• 希望在修改代码前，获得可信度较高的初步架构分析

对于范围狭窄的单文件问题，或已熟悉代码库中的已知 Bug，不要使用此技能。

工作方式

从表层证据逐步深入到影响最大的内部实现。

• 先阅读仓库说明和顶层文档，再查看实现文件。
• 优先使用具体证据，避免猜测。
• 将推断明确标注为推断。
• 省略不重要的细节。
• 不仅说明有哪些内容，还要解释其重要性。
• 以资深工程师或代码分析师的风格撰写：技术观点鲜明、沉稳而准确。
• 避免写成入门检查清单或泛泛的仓库摘要。

调查流程

1. 确认仓库背景

先阅读最有价值的概览资料：

1. AGENTS.md
2. README*
3. 顶层文档，例如 docs/、CONTRIBUTING*、ARCHITECTURE*、CHANGELOG*
4. 如果存在，查看近期 git 历史

记录：

• 项目声明的用途
• 运行时和平台假设
• 文档中说明的构建、运行和测试命令
• 可能影响后续修改的本地规则
• 仓库类型：应用、库、内部工具、模板、技能包、研究仓库、基础设施仓库等

2. 检查仓库规范和工作流线索

查找能够反映项目维护方式的贡献和工作流文件：

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

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

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

如果这些文件不存在，简要说明后继续。

3. 梳理表层结构

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

识别：

• 主要应用目录
• 测试、脚本、文档、资源、配置和 CI 目录
• 依赖清单文件
• 可能的入口点
• 看起来处于核心位置或边缘位置的目录

如果仓库很大，请抽样查看有代表性的目录，并说明你采用了抽样方式。

4. 确认执行流程

先查阅文档，再根据配置文件进行验证。

查明：

• 项目如何启动
• 如何构建
• 如何测试
• 部署或发布线索
• 环境假设和外部服务

如果不同文件中的命令不一致，请明确指出。

5. 阅读关键路径

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

对每个重要模块，总结：

• 职责
• 主要输入和输出
• 主要协作模块
• 其在架构上的重要性

优先深入少数高价值模块，而不是浅尝辄止地广泛浏览。

6. 评估质量信号

检查：

• 测试组织方式和大致覆盖情况
• CI 或自动化
• 发布流程
• 依赖管理状况
• 文档完整性
• 维护热点或紧密耦合

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

7. 指出风险和未知项

明确说明：

• 缺失的文档
• 不清楚的运行时假设
• 脆弱的设置步骤
• 测试盲点
• 令人意外的依赖
• 修改前需要进一步验证的部分

规模策略

根据仓库规模调整分析深度，不要假设每个仓库都值得同等深入的分析。

• 小型仓库： 直接阅读主要文件，并深入分析真正的控制路径。
• 中型仓库： 检查完整的代码范围，然后选出定义执行流程和架构的 3-5 个模块。
• 大型仓库或单体仓库： 明确说明你采用了抽样分析。先查看清单文件、工作区配置、根目录文档、CI，以及顶层应用/软件包目录，再深入分析内部实现。
• 如果仓库太大而无法全面覆盖，优先从全局入手，再深入阅读一两个有代表性的部分。

单体仓库策略

如果仓库是单体仓库，不要把它描述成一个应用。

首先识别仓库的结构：

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

然后遵循以下规则：

• 从根目录清单文件、工作区配置、根目录 README/文档和 CI 工作流入手。
• 使用工作区清单文件和 CI 交叉核对实际构建、测试和部署的内容。
• 在总结行为之前，先按边界划分仓库。
• 识别哪些子项目是主要项目，哪些是辅助项目。
• 绘制完整结构后，除非用户明确要求详尽覆盖，否则只选择最重要的 1-2 个子项目进行深入分析。
• 将可部署应用、共享软件包和基础设施视为不同的架构角色，而不是扁平列表中的同类项。
• 指出测试、CI 或部署的作用层级与主要应用代码不同的情况。

不确定时，优先采用类似以下的报告结构：

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

当仓库明显包含多个软件包、应用或归属边界时，请使用 references/monorepo-checklist.md。

结合技术栈的提示

根据依赖清单文件决定优先查看哪些内容。

• 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 工作流，推断相同信息：入口点、软件包边界、构建路径和部署形态。

这些只是提示，并非僵化的语言专属操作手册。请利用它们改进阅读顺序并识别入口点。

输出格式

将 references/report-template.md 中的报告模板用作结构指南。需要在撰写前快速列出执行检查清单时，使用 references/checklist.md。如果仓库明显采用 monorepo 结构，则使用 references/monorepo-checklist.md。

输出必须：

• 以名为 Repository Thesis 的简短章节开篇
• 总共包含 4-6 个章节，并根据仓库情况选择
• 仓库适合使用具体标题时，应使用具体标题，而非固定的通用标题
• 始终涵盖：用途、执行路径、关键架构，以及风险或质量信号
• 优先使用扁平项目符号列表；如果某个章节需要更充分的综合分析，则使用简短段落
• 每条项目符号至少发挥两种作用：陈述事实，并解释其影响

可用的章节名称包括：

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

避免在每个仓库中机械复用相同的章节标题，以免结果显得千篇一律。

证据规则

• 重要论断须引用具体文件路径。
• 明确区分已确认事实、有依据的推断和未知信息。
• 优先陈述有具体文件佐证的内容，避免缺乏依据的概括。
• 不要臆造未经核实的架构细节。
• 如果无法核实某项信息，请明确说明。
• 优先选择能将证据与架构或维护影响联系起来的观察。

写作质量标准

结果应读起来像一份简短的分析报告，而不是简略的入门介绍。

具体来说：

• 不要只是复述 README 中的内容。
• 不要把所有仓库都套进相同的总结框架。
• 突出使该仓库与众不同的设计决策。
• 指出技术能力较强的读者在修改代码前真正需要了解的信息。
• 保持可读性，但不要过分追求简短，以致分析失去分量。
• 优先使用兼具事实、解读和影响的项目符号。
• 句子应简洁；如果仓库值得深入分析，也可以适当增加信息密度。
• 如果仓库有一个主导理念，不要为了机械对称而让报告显得刻板。