# Yy Learn Project

> 阅读陌生代码库，围绕项目整体或指定功能链路生成带核心代码、文件路径和准确行号的学习文档。 用于接手新项目、理解模块协作或追踪功能实现；不用于代码审核、功能修改、README、交接文档或脱离源码的通用技术文章。

- Skill: `bulls-cows/yy-learn-project` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add bulls-cows/yy-learn-project`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bulls-cows/yy-learn-project/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: bulls-cows (https://skillmd.com/u/bulls-cows)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bulls-cows/yy-learn-project

---


# yy-learn-project

## 描述

从当前代码、配置、测试和权威文档中建立可核验的证据链，生成便于开发者学习陌生项目的 Markdown 文档。支持项目整体概览和单一功能专题两种模式，重点解释真实调用链、数据流、核心代码、实现边界与文档冲突。

## 使用场景

- 用户接手陌生项目，需要生成可持续阅读的项目学习文档
- 用户指定某个功能主题，要求解释实现流程、核心代码及文件行号
- 用户希望把连续分析结果保存到项目的学习目录

不应触发：

- 用户只要求解释单个函数或一小段代码，不需要生成学习文件
- 用户要求审核、修改、重构或测试代码
- 用户要求创建项目首页说明、任务交接材料或脱离当前源码的技术教程

## 指令

### 步骤 1. 确定学习目标与输出模式

提取目标项目、学习主题、输出目录、文件名和期望深度。用户没有指定输出目录时，默认使用项目根目录下的 `learning/`；没有指定文件名时，根据主题生成简短的中文 Markdown 文件名。

**决策分支**：

- **整体概览**：覆盖项目定位、结构、技术栈、模块职责、主流程、配置、运行方式和推荐阅读路径
- **功能专题**：围绕一个可描述的行为追踪入口、调度、核心实现、数据转换、输出和下游消费
- **目标同时包含多个独立主题**：拆成多份文档；先生成总索引，再逐个完成专题
- **目标文件已存在且用户要求更新**：读取现有内容后增量修订，保留仍然正确的结论
- **目标文件已存在但用户未授权覆盖**：停止写入并询问是更新现有文件还是更换文件名

### 步骤 2. 读取项目规约与权威入口

先查找并读取目标范围内适用的 `AGENTS.md`、本地覆盖规则及其按需引用。再读取项目声明的文档索引、架构说明、模块说明、契约和根级配置，确认哪些资料是权威来源。

只读取理解目标所必需的内容。跳过依赖、构建产物、缓存、生成文件和大体积数据目录，除非它们正是用户指定的研究对象。

**决策分支**：

- **仓库声明文档单一真源**：按声明顺序读取，并用源码核对当前实现
- **没有项目规约或文档入口**：从根级 manifest、启动入口、源码目录和测试目录建立最小项目地图
- **文档与源码不一致**：分别记录“约定行为”和“当前实现”，不静默选择其中一方

### 步骤 3. 识别技术栈并路由源码入口

读取 [resources/language-routing.md](resources/language-routing.md)，根据 manifest、扩展名和运行入口选择对应技术栈的定位方式。

通用规则始终生效；命中特定技术栈时，特定规则优先于通用规则。未列出的语言或框架使用资源中的通用兜底流程。混合语言项目分别定位各运行时边界，再追踪跨进程或跨服务通信点。

### 步骤 4. 建立证据地图

先列出待回答的问题，再为每个问题记录代码、配置、测试或文档证据。不要在证据不足时开始撰写正文。

**整体概览至少核对**：

1. 项目服务对象和核心目标
2. 独立项目或 monorepo 的组织方式
3. 主要语言、框架和运行时职责
4. 核心模块、入口和主数据流
5. 配置、持久化、外部通信和输出
6. 本地运行、测试及主要限制

**功能专题至少核对**：

1. 用户操作、命令、API 或内部事件入口
2. 参数解析、校验和配置来源
3. 调度层及其直接上游
4. 核心算法或业务实现
5. 中间数据结构及转换规则
6. 输出、落盘、响应或下游消费者
7. 失败处理、资源清理、并发或性能保护
8. 能证明关键行为的测试

只追踪目标的直接上下游和必要共享层。发现替代后端、兼容分支或历史实现时，先确认它是否能在当前配置下进入主链路，再决定是否写入正文。

### 步骤 5. 提取调用链、核心代码和行号

优先使用精确文本搜索定位符号、调用方、配置键和输出字段，再读取完整函数上下文。所有行号必须来自当前工作区文件，禁止凭记忆填写。

对每个关键阶段记录：

- 相对项目根目录的文件路径
- 符号名称或配置键
- 当前起止行号
- 上游调用者和下游消费者
- 输入、输出和副作用
- 能说明关键行为的最小源码片段

核心代码必须摘自当前源码，可省略无关分支，但不得改变变量含义、执行顺序或异常语义。省略内容时使用与目标语言匹配的注释标记。所有围栏代码块必须声明语言。

文档引用使用以下格式：

```markdown
[文件名](../相对路径/文件名.ext#L123) 第 123-156 行
```

如果目标平台不支持行号锚点，仍保留 `文件路径:行号` 文本。引用目录、二进制文件或无法稳定编号的生成内容时，不伪造行号，并说明限制。

### 步骤 6. 区分事实、推断和冲突

对结论进行证据分级：

- **当前行为**：由可执行源码、配置或测试直接证明
- **约定行为**：由项目声明的契约、架构或权威文档定义
- **推断**：由命名、依赖或调用关系推导，但没有直接断言
- **未确认项**：缺少必要环境、生成文件、运行数据或外部服务证据

用户询问“当前如何实现”时，以当前可执行源码为行为依据；用户询问“应该如何工作”时，以项目声明的权威契约为依据。两者冲突时必须并列说明文件位置、具体差异和可能影响。

不得编造运行结果、性能数据、默认值或测试结论。没有实际运行验证时，明确写“未运行验证”。

### 步骤 7. 生成学习文档

使用 [templates/topic-learning-doc-template.md](templates/topic-learning-doc-template.md) 生成文档。整体概览可删除不适用的专题章节，但必须保留阅读范围、关键文件、证据状态和推荐阅读顺序。

写作要求：

- 面向刚接手项目的开发者，首次出现的项目术语要解释
- 先给整体调用链，再按执行顺序展开
- 代码示例之后紧跟用途、输入输出和关键判断说明
- 配置值同时说明来源、覆盖方式和当前默认值
- 坐标、单位、状态、并发和失败策略必须明确口径
- 重复路径集中到关键文件表，正文只在需要定位时再次引用
- 不使用故事化开头、宣传性表达或无信息量的过渡句

### 步骤 8. 校验文档

写入完成后执行以下检查，发现问题先修正文档再交付：

1. 以 UTF-8 读取文件，确认标题、首段和末段完整
2. 检查所有相对文件链接对应的目标存在
3. 重新核对每个关键引用的符号和当前行号
4. 抽查核心代码片段与源码一致
5. 检查调用链中的每条边都有调用、导入、契约或数据字段证据
6. 检查事实、推断、冲突和未确认项没有混写
7. 检查所有代码块包含语言标识，Markdown 结构符合目标仓库规范
8. 检查文档没有泄露密钥、令牌、本地敏感配置或业务隐私数据

如果项目已经提供 Markdown 检查命令，且仓库规约要求执行，则运行与本次文档相关的检查。不要为了生成学习文档安装新依赖或启动生产服务。

### 步骤 9. 输出结果

向用户说明：

1. 已创建或更新的文档路径
2. 文档覆盖的调用链和关键主题
3. 已完成的链接、行号、编码或 Markdown 校验
4. 未运行的测试、无法核实的外部行为和已发现的文档冲突

最终回复只总结结果，不重复粘贴整篇文档。

## 安全边界

- 默认只读取源码并写入用户授权的学习文档目录，不修改业务代码、配置、测试或权威项目文档
- 不运行部署、发布、数据库迁移、外部写入或真实业务请求
- 不把 `.env`、本地覆盖配置、日志中的凭证或用户数据写入学习文档
- 需要修改授权目录外的索引或导航文件时，先说明文件、原因和影响并获得授权

## 相关资源

- `templates/topic-learning-doc-template.md`：整体概览和功能专题共用的学习文档结构
- `resources/language-routing.md`：不同技术栈的源码入口、契约和测试定位规则