Project Learning

---
name: project-learning
description: 帮助用户快速吃透一个陌生的代码库/新项目（项目 onboarding）。当用户说“帮我快速了解/上手/接手这个项目”、“我要熟悉这个代码库”、“怎么快速吃透一个新项目”、“帮我摸底这个仓库”、“项目 onboarding”、“新项目怎么快速熟悉”等场景时触发。技能会自动识别项目架构类型并适配侦察策略，先读 README 获取目录与功能模块，再向用户索取设计/开发文档深入理解，与用户交互确认要深挖的模块后深入探索，生成/增量更新 ONBOARDING_NOTES.md（可选 CONTEXT.md 术语表），提议创建 AGENTS.md/CLAUDE.md；与 document-learning 组成技能集合体：项目以文档/知识库为主时切换给 document-learning。全程交互式、不臆断、省 token。输出默认为中文。
---

# Project Learning：用 AI 快速吃透一个新项目

> 目标：让新入职/接手的工程师在最短时间内建立对一个陌生代码库的完整方位感，并把理解沉淀成可维护的文档。整个过程**交互式推进，不自己想当然**。与 document-learning（知识库/文档库深度理解）组成技能集合体，互相引用、互相调用。

## 触发场景

- 用户说“帮我快速了解/上手/接手这个项目”、“我要吃透这个代码库”、“帮我做项目摸底/onboarding”、“第一次接触这个代码库”等
- 用户新入职、换团队、接手新模块，需要项目级理解
- 用户希望把项目摸底结果整理成文档

## 核心原则

1. **只讲真实内容，绝不编造**：结论必须来自 README、文档、代码、配置、git 历史；不确定就写“需要向团队确认”
2. **README 优先**：先读 README 拿目录结构、功能模块、技术栈，再往下走
3. **文档驱动**：设计/开发文档（ADR、CONTEXT.md、设计文档、wiki、API 文档）比代码推断更高效；文档与代码矛盾时向用户指出
4. **交互式，不臆断**：每一步关键决策先和用户确认——理解对不对、深挖哪些模块、是否写文件
5. **多架构适配**：先识别项目类型，再选对应的侦察与解读策略，不套用单一模板
6. **省 token**：只读高信号文件、批量采样、先整体后聚焦、输出精炼；用户确认理解够了就停
7. **输出中文**（除非用户明确要求英文）
8. **可调用相关已装技能**：需要时参考 grill-with-docs、domain-modeling、research 的方法论；遇到以文档/知识库为主的项目，切换到 document-learning（技能集合体联动）

## 工作流程

### 第 0 步：识别项目架构类型（多项目适配）

轻量检测（只看文件名/依赖/顶层目录，不深读代码），先判断项目属于哪类形态，再选侦察与解读策略。表内 19 种常见形态；判定吃不准时，用“内部架构风格”第二维度补一轮判断：

| 类型 | 特征信号 | 侦察重点 | 深入重点 |
|---|---|---|---|
| 业务后端/Web 应用（如智能选配模块） | package.json / requirements.txt / pom.xml / go.mod + routes·controllers·services·models | API 分层、入口 | 业务规则、状态机、数据模型 |
| 前端应用（SPA/SSR） | package.json + src/components·pages + vite/webpack/next.config | 组件树、路由、状态管理 | 路由与数据流、UI 组件库 |
| 全栈 | 前后端同仓（client/ + server/ 或 apps/web + apps/api） | 前后端边界 | 端到端数据流 |
| Monorepo | pnpm-workspace.yaml / apps·packages / lerna.json / turborepo | 子项目边界 | 先让用户确认聚焦哪个子项目 |
| 微服务 | 多服务目录 + docker-compose / k8s / API 网关 | 服务拓扑与通信 | 服务间契约、网关、可观测性 |
| 事件驱动/消息系统 | kafka/rabbitmq/pulsar 依赖 + consumers/ producers/ events/ | 消息拓扑、事件定义 | 事件契约、消费幂等、死信处理 |
| 移动端 | ios/ android/ / pubspec.yaml(Flutter) / React Native | 平台目录与入口 | 页面导航、网络层、本地存储 |
| 桌面端 | electron / tauri | main/renderer | IPC 通信 |
| 浏览器插件/扩展 | manifest.json / chrome-extension | 权限声明、注入脚本 | 权限模型、消息传递、存储 |
| CLI 工具 | package.json bin / cli.py / cmd/* + cobra | 命令注册 | 参数解析、退出码、插件 |
| 库/SDK | lib/ 或 src/index + pyproject/setup.py/package.json main | 公共 API 面 | 导出面、版本兼容、示例 |
| 数据管道/ETL | airflow/ dbt/ scripts/ + 数据仓库配置 | DAG/任务定义 | 血缘、调度、幂等 |
| 数据平台/数仓 | warehouse/ datasets/ + OLAP 引擎配置 | 分层模型（ODS/DWD/DWS） | 指标口径、血缘、数据质量 |
| AI/ML | train/ inference/ notebooks/ models/ + 依赖 | 数据/训练/推理拆分 | 特征、模型版本、评估 |
| AI/Agent 平台（如智能体应用平台） | LLM SDK 依赖 + agents/ tools/ prompts/ | 智能体编排、工具注册、消息队列 | agent 生命周期、工具协议、上下文管理 |
| 平台/调度（如智能算力调度平台） | go.mod/java + scheduler/ worker/ queue/ | 调度算法、任务队列、资源分配 | 并发、幂等、分布式一致性 |
| Serverless | serverless.yml / template.yaml / functions/ | 函数列表与触发 | 冷启动、权限、事件源 |
| 部署/IaC（如 OpenClaw 部署） | docker-compose*/Dockerfile/k8s/helm/*.tf/CI 工作流 | 服务拓扑、配置、CI/CD | 部署链路、配置注入、升级回滚 |
| 文档/知识库站点 | docusaurus/mkdocs/vitepress + docs/ | 判断是否以文档为主 | 以文档为主 → 交接 document-learning |
| 游戏/嵌入式/脚本/其他 | unity/unreal/arduino/*.sh | 入口与资产 | 按领域定制 |

**内部架构风格（第二维度）**：同为“业务后端”，分层 / 模块化单体 / 六边形（端口-适配器）/ 事件驱动等内部风格会决定深入重点，用 1-2 个特征信号补判（如 `internal/` 分层目录、`domain/` + `infra/` 包、事件处理目录）；吃不准就并列说明。

把“项目类型 + 一句判断依据”先告诉用户，让用户纠正或确认（比如“这是部署类还是业务应用类”）。无法唯一判定的混合类型（如 调度平台+部署清单）就并列说明。

### 第 1 步：README 优先

- 读 README：超长只读前 80-120 行 + 目录/功能模块相关小节；不整读大文件
- 提取：项目做什么、功能模块清单、目录结构说明、技术栈、快速开始
- 输出 3-5 行摘要 + 目录/功能模块草图，**请用户确认理解是否正确**，错了就改，不硬撑

### 第 2 步：文档驱动（向用户索取设计/开发文档）

主动问用户项目里的设计/开发文档入口，按优先级读：

1. `CONTEXT.md`（术语表/领域语言）、`docs/adr/*`（架构决策记录）
2. 架构设计文档、模块设计文档、数据库设计
3. README 里引用或链接的文档、wiki 页面、API/接口文档

用文档建立理解：术语、架构决策、模块职责、数据流。**文档与代码矛盾时指出并问用户**（借鉴 domain-modeling 的对照检查）。没有文档就如实说明，转用代码推断。

### 第 3 步：交互确认要深挖的模块

- 从 README + 文档 + 目录得到模块清单（控制在 5-8 项，省 token）
- 问用户：这次想重点理解哪些模块？为什么（当前任务是什么）？
- 用户确定 1-3 个模块后再深入；不一次性全铺开

### 第 4 步：深入探索目标模块（访谈式 + 省 token）

**访谈式提问**（借鉴 grill-with-docs / domain-modeling）：
- 澄清术语：挑出歧义词问用户准确含义（“你说的‘账号’是指 User 还是 Customer？”）
- 挑战模糊概念：用户描述模糊时，给出更精确的候选说法让其确认
- 具体场景压测：用边界场景验证理解（“组织删除后，子部门下的任务怎么办？”）
- 对照代码：用户/文档的说法与代码不符时，指出来问哪个是对的

**省 token 阅读策略**：
- 先看模块入口/接口定义，再看核心实现
- 大文件只看函数签名、注释、关键分支（用 grep/采样，不整读）
- 只读必要文件，理解到位就停
- 需要联网查一手资料时，按 research 技能的方式：查官方文档/源码，不靠二手解读

输出：目标模块的职责、关键设计、数据流、风险点，保持精炼。

### 第 5 步：产出文档（确认后写）

- **主文档**：`ONBOARDING_NOTES.md`，增量更新（不存在则创建；已存在先读再做增量，保留用户内容；“待确认事项”单独维护）
  结构：项目概述 / 架构类型 / 技术栈 / 目录地图 / 关键入口 / 近期动态 / 风险点 / 待确认事项 / 更新日志
- **可选**：`CONTEXT.md` 术语表——访谈中确有实质术语澄清时，问用户是否创建（不强制）
- **可选**：提议创建 `AGENTS.md` / `CLAUDE.md`，给精简模板草稿，用户同意后创建
- 写前给用户看结构/变更点，确认后写

### 第 6 步：持续使用建议

结合项目实际情况给几条建议：
- 改代码前先问“这块代码怎么工作、改动影响哪里”
- 涉及账号/权限/支付等敏感模块，改完自查安全边界与绕过风险
- 反复做同一类操作时，考虑封装成 skill

## 联动：与 document-learning 组成技能集合体

- **判定规则**：项目以代码为主 → 本技能；以文档/知识库为主 → document-learning；混合 → 先确认主次，两部分由两个技能接力完成
- **交接协议**：本技能发现文档量远超代码（如庞大的 docs/、文档站点、Wiki）→ 明确告诉用户“文档部分建议交给 document-learning”，并附上已获得的上文摘要；反之 document-learning 发现需读代码 → 交接给本技能
- **共享产物**：`ONBOARDING_NOTES.md`（同一文件，各技能增量更新各自章节）、`CONTEXT.md` 术语表（共用）
- **触发互补**：两个技能的 description 互相提及对方，避免同类触发词漏配


## 可引用技能（refs：更广阔的知识库）

学习项目时可按需引用已装技能扩展能力，清单见 `references/skill-ecosystem.md`（只加载需要的 1-2 个，不一次性全加载）：
- **技能搜索/发现**：`skillsmp-find-install`、`skill-grep`、`skill-installer`（.system）——遇到需要专业/领域知识时，先搜技能再学习
- **代码库理解补充**：`acquire-codebase-knowledge`（结构化产出模板）、`project-understanding`（token 预算视图）、`codebase-knowledge-builder`（知识产物沉淀）
- **知识沉淀**：`llm-wiki`（把项目理解编译成交叉引用知识库，长期复用）
- **方法论**：`research`（一手资料）、`domain-modeling`（术语）、`grill-with-docs`（访谈）

## 省 token 规则（硬性）

- 读 README 前 120 行；配置文件整读（通常很小）；代码只读关键部分
- 侦察命令合并执行、失败跳过
- 输出摘要化，不贴大段代码、不列冗长文件清单
- 用户说“够了”就停，不追求面面俱到
- 每轮尽量只问 1-3 个必要问题，避免连环轰炸

## 边界与兜底

- 命令失败：跳过并说明，不硬猜
- 无 README / 无文档 / 无 git 历史：如实标注“文档缺失”，改用代码推断
- 超大仓库：先全景后聚焦，主动询问优先深入哪块
- monorepo：说明子项目边界，让用户确认以哪个为准
- 无网络：不联网搜索，基于本地内容分析

## 测试用例（验证用）

1. “我是新来的实习生，帮我快速了解这个项目”（Node 业务应用 → 完整流程）
2. “帮我摸一下这个仓库，重点看调度器相关代码”（Go 调度平台 → 类型识别 + 聚焦）
3. “这个项目的部署是怎么做的？”（部署/基础设施类 → 类型识别 + 部署链路）
4. “重点理解智能体平台的编排逻辑”（AI/Agent 平台 → 类型识别 + 聚焦）
5. “这个项目的 ONBOARDING_NOTES.md 我想更新一下”（增量更新流程）
6. “帮我梳理一下这套消息系统的消费链路”（事件驱动 → 类型识别 + 消息拓扑）
7. “这个仓库代码不多但文档特别多，帮我整体摸底”（混合 → 判定主次并联动 document-learning）