# Yy Read Project > 阅读独立项目或 monorepo 项目，快速梳理项目用途、结构分层、模块职责、技术栈边界、本地化方案与通信关系。 用于接手陌生代码库、需要先建立整体认知，或用户明确要求“先看看这个项目整体是怎么组织的”时。 不用于刷新对已读代码的最新改动、审核代码质量，也不用于针对单个文件或函数做精读。 - Skill: `bulls-cows/yy-read-project` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add bulls-cows/yy-read-project` - Raw SKILL.md: https://api.skillmd.com/api/skills/bulls-cows/yy-read-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-read-project --- # yy-read-project ## 描述 帮助 AI 用统一方法阅读两类项目：独立项目与 monorepo 项目。目标不是机械罗列文件，而是先识别项目形态和阅读范围，再基于整体把控回答项目做什么、核心模块分别负责什么、它们如何协作。 默认聚焦 7 个维度：项目形态、阅读范围、项目定位、结构分层、模块或子项目职责、技术栈边界与本地化方案、通信与依赖关系。 ## 使用场景 - 用户说“先帮我看看这个项目是干嘛的” - 用户说“帮我快速阅读这个项目” - 用户要了解“项目整体怎么组织的” - 用户要梳理“各个模块 / 子项目都是干嘛的” - 用户要确认“项目里用了哪些编程语言，分别负责什么” - 用户要确认“i18n 怎么做”“文案和语言包在哪里” - 用户要确认“模块之间怎么通信”“子项目之间怎么协作” - 用户接手存量项目，需要一份入项级别的整体概览 不应触发： - 用户只想解释某一个函数、某一个文件或某一段代码 - 用户已经明确要求直接修改代码、修 bug 或实现功能 - 用户只想执行 lint、测试、构建或发布 - 用户要求输出 README、设计文档或交接文档正文（应使用对应技能） ## 指令 ### 步骤 1. 识别项目形态与阅读范围 - 先提炼用户最关心的范围：整个项目、某一层目录、某个模块、某个子项目，或某个主题（如 i18n、通信、构建）。 - 从根目录和根配置判断当前属于以下哪一类： - 独立项目 - monorepo 项目 - 根据用户意图把阅读模式归为以下三类之一： - 整体阅读：用户要理解整个项目或整个 monorepo - 局部阅读：用户只关心某个目录、模块、子项目或链路 - 主题阅读：用户只关心 i18n、通信、构建、协议、依赖等主题 - 若用户未指定范围，默认按“整体项目概览”执行，并覆盖项目定位、结构分层、模块或子项目职责、技术栈边界、本地化方案、通信关系 6 个核心主题。 - 仅在以下情况主动追问： - 用户同时提出多个互相冲突的目标，无法判断优先级 - monorepo 体量极大且用户额外要求对每个子项目展开到实现细节，需要确认输出深度 **决策分支**： - **用户明确指定主题**：优先深挖该主题，同时保留最小整体概览 - **用户只说“看看项目”**：输出标准整体概览 - **用户只指定某个子目录、模块或子项目**：围绕该范围分析，并补一段它在整体架构中的位置 - **局部阅读或主题阅读**：只扫描目标对象、直接上下游、根级组织文件，以及理解该范围所必需的共享契约或公共模块 - **识别为独立项目**：走独立项目分析分支 - **识别为 monorepo 项目**：走 monorepo 全局分析分支 ### 步骤 2. 判断组织方式与技术栈边界 - 从项目根目录识别组织工具与语言栈，优先读取： - JavaScript/TypeScript：`package.json`、`pnpm-workspace.yaml`、`turbo.json`、`nx.json`、`lerna.json` - Rust：根 `Cargo.toml` 中的 `[workspace]` - Go：`go.work`、多模块 `go.mod` - Python：`pyproject.toml`、`requirements.txt` - 其他：`Makefile`、`Taskfile.yml`、`justfile`、根 README、架构文档 - 判断项目是单语言、混合语言，还是多运行时协作结构，并记录不同技术栈承担的职责边界。 - 把“技术栈语言”与“产品多语言 / i18n”明确分开： - 技术栈语言：TypeScript、Rust、Go、Python 等编程语言及其职责分工 - 产品多语言：界面文案、翻译资源、语言切换、地区化格式等本地化能力 - 不要一开始就全量遍历源码；先靠根配置和目录骨架建立地图。 **决策分支**： - **检测到 monorepo 配置或明显多子项目结构**：记录子项目组织规则、扫描入口和分层方式 - **未检测到 monorepo 特征**：按独立项目处理，重点识别核心目录和主入口 - **检测到 Rust / Go / Python 等非前端子工程**：把它们视为正式模块或正式子项目，不要只盯前端代码 - **用户问“多语言怎么做”但语义不清**：先根据上下文判断是在问编程语言协作还是 i18n；若两种理解都成立，主动点明这两个方向并分别给最小结论 ### 步骤 3. 盘点结构单元 - 盘点时优先基于 manifest、根配置和就近 README，而不是先深读业务代码。 - 若是独立项目，整体阅读时至少提取以下结构单元： - 核心目录或核心模块 - 所属语言/框架 - 职责定位 - 运行形态：应用、库、服务、脚本、协议层、生成产物或工具 - 若是独立项目，局部阅读时至少提取以下结构单元： - 目标目录或目标模块 - 它在整体中的上一级分层位置 - 与它直接交互的关键模块 - 为理解它必须读取的入口文件、配置文件或文档 - 若是 monorepo 项目，整体阅读时必须遍历全部子项目；每个子项目至少提取以下信息： - 名称或目录名 - 所属语言/框架 - 职责定位 - 运行形态：应用、库、服务、脚本、协议包、生成产物或工具 - 与其他子项目的主要依赖关系 - 若是 monorepo 项目，局部阅读时至少提取以下信息： - 目标子项目或目标目录 - 它所属的分组或层级，如 `apps/`、`packages/`、`services/` - 与它直接相关的上游、下游和共享契约层 - 用于解释其定位的最小全局信息，如工作区组织方式、主链路位置 - 发现 `generated`、`dist`、`vendor`、`target`、`node_modules` 等派生目录时，默认跳过，不把它们误判为正式模块或业务子项目。 **决策分支**： - **独立项目**：输出核心模块/目录职责，不强行虚构“子项目” - **monorepo 整体阅读且子项目数量较少**：逐个说明全部子项目职责 - **monorepo 整体阅读且子项目数量较多**：仍需覆盖全部子项目，但可按 `apps/packages/services/libs/tools` 等分组呈现，避免无差别堆叠 - **monorepo 局部阅读**：不要求展开全部子项目，但必须说明目标对象在全局中的位置，并覆盖直接上下游 ### 步骤 4. 判断项目定位与运行拓扑 - 结合根 README、`docs/`、`AGENTS.md`、ADR、启动入口和主配置文件，回答“项目是干什么的”。 - 梳理关键运行拓扑，例如： - 单体前端应用 - 单体后端服务 - 前端 + 后端服务 - 桌面壳 + 本地核心 + 驱动适配层 - 应用层 + 共享协议层 + 代码生成层 - 控制面 + 数据面 + SDK / CLI / 管理台 - 当文档描述与代码组织不一致时，必须明确指出冲突，不能默认相信任一方。 ### 步骤 5. 分析本地化方案与文案归属 - 搜索并识别 i18n 入口与资源形态，例如： - `locales/`、`i18n/`、`messages/` - `vue-i18n`、`react-intl`、`i18next`、`lingui` - 自定义语言包、后端翻译表、客户端枚举标签映射 - 说明以下信息： - 文案资源放在哪 - 由谁加载与切换语言 - Key 命名方式和语言文件组织方式 - 是否有回退策略、默认语言和格式化逻辑 - 哪一层负责把枚举值或状态码转成用户可读文案 - 若用户问题中的“多语言”实际指编程语言协作，先在步骤 2 交代技术栈职责边界，再在本步骤单独交代 i18n 是否存在，避免混写。 **决策分支**： - **检测到成熟 i18n 框架**：说明框架、入口文件、资源目录和调用方式 - **检测到自定义实现**：说明自定义词典、映射层和使用边界 - **未检测到明显 i18n 机制**：明确写“暂未发现系统化多语言方案”，并给出你检查过的证据位置 ### 步骤 6. 分析依赖关系、共享契约与通信链路 - 把“源码级依赖/共享代码”和“运行时通信”分开分析，避免混为一谈。 - 独立项目重点检查： - 模块之间的 import / 调用关系 - 内部事件、状态管理、服务层、数据访问层的边界 - 是否存在本地协议层、适配层或插件桥 - monorepo 项目重点检查： - 子项目之间的本地依赖，如 `workspace:*`、路径依赖、Cargo workspace members - 共享协议、类型、SDK、生成代码目录 - 跨进程、跨端、跨服务、跨壳层通信链路 - 运行时通信重点检查： - HTTP / RPC / WebSocket / gRPC / 消息队列 / 事件总线 - 桌面桥接、WebView bridge、插件桥、进程间通信 - 配置驱动或文件交换 - 对每条关键关系，尽量说明调用方向、边界层和关键文件位置。 **决策分支**： - **存在 `proto` / `contracts` / `openapi` / `schema` / `generated`**：优先把这些识别为契约层，说明谁生产、谁消费 - **存在前后端、多进程或多服务边界**：明确请求入口、路由层、业务层、适配层分别在哪里 - **只发现源码级 import，没有明显运行时调用**：说明当前主要是代码复用型关系，而非强运行时通信 ### 步骤 7. 从整体视角归纳项目 - 基于前 6 步，不只罗列事实，还要给出整体判断： - 项目的核心目标是什么 - 架构是如何分层的 - 独立项目内部模块如何分工 - monorepo 中各子项目如何协同完成完整能力 - 若是 monorepo，必须单独总结： - 全部子项目大致分为哪些类别 - 哪些子项目处在主链路上 - 哪些子项目承担共享契约、工具、协议或基础设施职责 ### 步骤 8. 形成最小阅读路径 - 基于前 7 步，给出一个从根到局部的阅读顺序，帮助用户继续深入。 - 阅读路径至少包含： - 根目录优先文件 - 独立项目下最关键的 2-5 个模块，或 monorepo 下最关键的 2-5 个子项目 - 每个关键结构单元建议先看的入口文件或文档 - 若用户后续要接着看某一主题，优先把路径指向该主题的权威文件，而不是泛泛给目录。 - 若当前是局部阅读，阅读路径优先围绕目标对象、直接上下游和权威入口，不强行补齐全项目游览路径。 ### 步骤 9. 输出结果 - 使用 `templates/project-overview-template.md` 的结构输出结果。 - 输出时必须区分“事实”“推断”“未确认项”，并尽量标注“依据位置”： - **事实**：能从代码、配置或文档直接定位到 - **推断**：基于目录、命名或调用关系推出来的结论 - **未确认项**：证据不足但对架构理解重要的部分 - 对整体阅读的 monorepo，必须覆盖全部子项目；可用分组、表格或分段组织，避免遗漏。 - 对局部阅读的 monorepo，不要求逐个展开全部子项目，但必须交代目标对象的全局定位、直接上下游和必要共享层。 - 对每个关键判断尽量附文件或目录依据，方便用户继续追读。 ## 输出约定 - 先给一句话项目定位，再给结构化概览。 - 必须先写清当前项目形态：独立项目或 monorepo。 - 必须单独写明当前阅读范围：整体阅读、局部阅读或主题阅读，以及目标对象是什么。 - 独立项目场景下，优先按“核心模块 / 目录职责”组织。 - monorepo 整体阅读场景下，必须覆盖全部子项目，并单独说明全局关系。 - monorepo 局部阅读场景下，优先按“目标子项目 / 直接上下游 / 所在分层位置”组织。 - 技术栈边界、本地化方案与通信必须单独成节，不能埋在其他段落里。 - 如果没有找到 i18n 或清晰通信链路，要明确写“未发现”或“待确认”，不要臆造结论。 - 如果项目明显是混合语言结构，要明确指出不同语言模块或子项目各自承担什么角色。 ## 安全边界 - 默认只做阅读、归纳和定位，不主动修改代码。 - 默认不运行构建、测试、安装依赖、启动服务；仅当用户明确要求，或缺少生成文件导致无法理解结构时才考虑执行。 - 默认跳过 `node_modules/`、`dist/`、`build/`、`coverage/`、`target/`、`.git/` 等派生目录，除非它们本身就是用户要分析的对象。 - 不把生成文件或缓存目录误当成架构主入口；若项目严重依赖代码生成，需回到生成配置和源契约分析。 ## 相关资源 - `templates/project-overview-template.md`：项目整体概览输出模板 - `examples/standalone-input.md`：独立项目局部阅读输入示例 - `examples/standalone-output.md`：独立项目局部阅读输出示例 - `examples/monorepo-input.md`：monorepo 局部阅读输入示例 - `examples/monorepo-output.md`：monorepo 局部阅读输出示例