Understand Project — Development skill for Claude Code

understand-project

一个面向中文读者的 Agent Skill：帮助完全不了解某个项目的人，从整体架构、运行形态、真实数据链路一路读到源码入口，并产出一份可继续用于二次开发的「看懂 X」Markdown 文档。

它解决什么问题

很多项目解析一上来就罗列类名和目录，读者却仍然不知道：

• 项目到底是 CLI、服务、daemon、库还是插件；
• 一次真实输入由谁触发，经过哪些进程、线程和模块；
• 哪些数据是权威事实，哪些只是派生索引；
• 成功、失败、异步完成和数据可用之间有什么区别；
• 如果要继续读源码，应该从哪条调用链开始。

这个 skill 规定了由浅到深的写作顺序，并要求架构结论能回溯到源码、运行验证或官方资料。

适用场景

当用户要求“帮我读懂/解析/拆解一个项目”“写一份项目解析”“从零讲清楚这个代码库怎么运行”或“我要在这个项目上做二次开发，先建立全局认识”时使用。

不适合只查一个函数、改一处 bug、做一次简单代码搜索，或要求生成架构图图片/PPT 的任务。

安装

Pi

将本目录复制到 Pi 的 skills 目录：

cp -R understand-project ~/.pi/agent/skills/

其他兼容 Skill 宿主

将 `SKILL.md` 作为 skill 入口文件，并保留 `references/` 目录。宿主需要支持读取目录中的 Markdown 资源。

使用方式

直接提出类似请求即可：

帮我读懂这个项目，先讲整体架构、运行形态，再按一条真实请求链路解释到源码入口。

输出应优先讲清：项目定位、运行形态、模块边界、纵向数据流、失败边界和源码阅读顺序；命令、版本号和内部类名等易变细节应标明源码基线。

目录结构

understand-project/
├── SKILL.md                         # Skill 的完整行为与写作规范
└── references/
    ├── exemplars.md                 # 同系列文档的结构样例
    └── method-digest.md             # 写作方法的细粒度摘要

设计原则

1. 先讲全局，再讲局部和细节。
2. 把“代码职责”与“真实进程/运行形态”分开说明。
3. 用一条真实输入链路把模块关系落到运行行为。
4. 把状态、失败、同步/异步和“完成不等于可用”当作一等公民。
5. 以当前源码和官方资料为准，不把二手教程当作实现事实。

许可

本项目采用 [MIT License](LICENSE)。