| name | project-dev-zh |
| description | 项目理解与工程开发技能：覆盖代码阅读理解、逐行代码讲解、语法拆解、项目架构解析、后端链路分析、工程化开发规范。Use when: 理解代码、解释这行代码、逐段讲解一个方法、语法教学、解析项目、分析后端链路、接口追踪、数据流分析、工程开发、代码Review、架构梳理。不适用于软著项目（使用 software-copyright-zh）。 |
项目理解与工程开发技能
Project structure gate / 文件树结构门禁
只要本工作流将初始化或重组项目，或新建、移动应用、服务、包、模块、页面、API、研究步骤、实验、流水线、测试、文档或多文件产物树，必须先使用 project-structure-architect。
- 开始前：读取适用的
AGENTS.md、PROJECT_STRUCTURE.md、.project-structure.yaml 和现有文件树，锁定项目类型、蓝图及唯一合理路径。
- 运行中：每次新增或移动文件前先判断职责、所有者、复用范围和对应测试；禁止同义目录、根目录堆放、跨层混放及无关重组。
- 阶段收口：纵向切片或阶段完成后检查结构漂移；新项目或重大重组更新结构文档，最终运行结构审计。出现
BLOCK 时停止结构性写入并先修正或询问用户。
纯内容编辑且目标路径已由用户或现有规范唯一确定时，可不重复调用。
技能目标
提供从"代码阅读→项目理解→链路追踪→工程开发"的完整技术支持，确保在理解现有代码的基础上做出高质量的增量修改。
Markdown 交付要求
- 使用本技能完成正式输出时，除聊天中的简要说明外，必须在当前工作区新建一个 Markdown 文档保存完整结果。
- 默认保存位置为当前工作区
skill-outputs/project-dev-zh/（与 artifact-curator-zh 按技能分子目录一致；根目录为 legacy-flat 兼容）。若该子目录不存在须先创建。
- 默认文件名格式为
中文主题_YYYYMMDD_HHMMSS.md（置于上述目录下；文件名不再重复 skill 名）；若主题不明确，使用 结果_YYYYMMDD_HHMMSS.md。
- Markdown 文档必须包含完整代码分析、架构说明、链路追踪结果、修改建议或开发方案。
- 若用户明确指定保存路径或文件名，以用户要求为准；若用户明确要求只在对话中回答，可跳过创建文件。
- 最终回复中要说明新建的 Markdown 文件路径（须含
skill-outputs/project-dev-zh/ 前缀），以及文件里包含的主要内容。
任务模式判定
| 模式 | 判定条件 | 核心目标 |
|---|
| A. 代码理解 | "帮我理解这段/这个文件""这段代码做了什么""逐行讲这个方法""解释这行语法" | 4级递进理解 |
| B. 项目架构解析 | "解析项目结构""梳理架构""这个项目怎么组织的" | 分层架构 + 模块关系 |
| C. 后端链路分析 | "追踪接口""数据流怎么走""从请求到数据库" | 完整链路图 |
| D. 工程化开发 | "开发XX功能""改这个模块""加个接口" | 符合工程规范的增量开发 |
模式A：代码理解（4级递进）
V1 —— 主干速览
目标：30秒内知道这段代码"做了什么"
输出：
- 一句话总结功能
- 输入是什么 / 输出是什么
- 核心数据结构
V2 —— 逻辑拆解
目标：能向别人讲清楚"怎么做的"
输出：
- 分步拆解主要逻辑流程
- 关键分支与边界条件
- 调用了哪些外部依赖
- 用一段话的类比解释核心思想
V3 —— 设计意图
目标：理解"为什么这样写"
输出：
- 设计模式识别（如有）
- 性能/可维护性/安全性的权衡
- 可能的替代方案及其取舍
- 潜在的坑/隐患
V4 —— 可修改性评估
目标：判断"能改什么、改了会影响什么"
输出：
- 修改热区（最可能需要改动的地方）
- 耦合分析（改这里会影响哪些地方）
- 测试覆盖建议
- 安全修改路径推荐
使用规则
- 用户未指定级别时，默认输出 V2
- 用户说"详细"时输出到 V3
- 用户说"我想改它"时直接跳到 V4
- 每级都要标注对应的代码行号
代码教学增强规则
- 当用户要求"逐行讲解""解释这行语法""用初学者方式讲""把这段代码展开讲"时，仍使用模式A，但输出必须切换为"语法 + 业务"双线讲解。
- 输出顺序优先为：
名词速览 → 原代码片段 → 语法解释 → 本段业务作用 → 等价展开写法 → 整体执行流程。
- 名词速览只列本段理解必需的术语，避免把不相关概念堆成词典。
- 名词速览不能只给通用定义，必须补上“它在当前函数 / 当前方法签名 / 当前调用点 / 当前会话里的具体作用”。
- 如果术语是变量、参数、配置项、装饰器、返回类型或对象成员，优先解释它在本地上下文中影响了什么，而不是先讲教科书定义。
- 对知识点、术语和语法点的解释，都要补一个简单例子帮助理解；例子优先 1-3 行的小片段或一句生活化对照，不要上来就给复杂业务样例。
- 语法解释必须绑定当前代码片段，回答"这行代码怎么写出来的、为什么这里这样写"，不能只给抽象定义。
- 遇到列表推导式、条件表达式、切片、zip 解包、with 上下文、类型注解等压缩写法时，优先给出等价的
for/if/普通赋值 展开版。
- 相同语法第一次详细解释，后续重复出现时只补充本处差异，避免逐行机械重复。
- 如果这段代码还承担链路中的一跳，要顺手说明"这一跳从上游拿到了什么、往下游交出了什么"，但不要把语法讲解完全替换成链路图。
代码教学输出模板
## 名词速览
- `术语`：通用含义（一句话）
- 在这里的作用：[它在当前函数/当前调用点里具体做什么]
- 简单例子：[一个最小例子或生活化对照]
## 这段代码整体在做什么
[先用一句话说明方法/片段的业务作用]
```python
[原始代码片段]
语法点/关键字：[字面意思]- 本段作用：[在当前业务里的作用]
- 简单例子：[一个最小可理解例子]
- 等价展开：
[更直白的 if/for/普通写法]
整段执行流程
- [步骤1]
- [步骤2]
- [步骤3]
一句话总结
[把"代码做什么"和"用了哪些关键语法"收束成一句话]
---
## 模式B：项目架构解析
### 分析步骤
1. **目录结构扫描**——识别分层（controller/service/dao/model 等）
2. **入口识别**——找到 main / app / 启动文件
3. **模块划分**——按业务域/技术层分组
4. **依赖关系**——模块间调用关系
5. **配置识别**——环境变量、配置文件、数据库连接
6. **链路分级**——按主链 / 辅读链 / 支撑链分类，不要一上来深挖底层
### 输出格式
项目名称：XXX
技术栈：XXX
分层结构：
├── 路由层（controller/router）
├── 业务层（service）
├── 数据层（dao/repository/mapper）
└── 模型层（model/entity）
核心模块：[列表]
模块间依赖：[描述]
启动方式：XXX
---
## 模式C：后端链路分析
### 链路追踪模板
从请求入口追踪到数据库，完整覆盖：
请求 → 路由（route/controller）
→ 中间件（auth/validation）
→ Service（业务逻辑）
→ Repository/DAO（数据操作）
→ 数据库（SQL/ORM）
→ 返回数据组装
→ 响应
### 每一层输出
| 层 | 输出内容 |
|----|----------|
| 路由 | URL + HTTP方法 + 参数校验规则 |
| 中间件 | 鉴权方式 + 异常拦截 |
| Service | 核心业务逻辑 + 事务边界 |
| DAO | SQL/ORM调用 + 表名 + 字段映射 |
| 数据库 | 表结构 + 索引 + 关联关系 |
### 输出格式
- 用「→」符号连接各层
- 每层标注对应文件路径和行号
- 数据变换处标注字段映射
---
## 模式D：工程化开发
### 开发前必做
1. **先读后写**——先理解现有代码结构，再动手
2. **确认影响面**——列出本次修改涉及的文件和模块
3. **确认接口契约**——入参/出参/错误码/状态码
### 编码规范
1. **命名保持一致**——变量名、函数名、文件名风格跟项目已有代码统一
2. **分层职责清晰**——Controller 不写业务逻辑，Service 不写 SQL
3. **增量修改**——不推倒重来，不改不相关的代码
4. **错误处理**——系统边界处做校验，内部逻辑不过度防御
5. **不留 TODO**——要么做完，要么不做
### 增量修改约束
- 先读现有结构，再改代码
- 禁止推倒重来（除非明确要求）
- 保留兼容旧字段，增加增强层新字段
- 不为了改动小而薄封装，导致逻辑层级越叠越高
### 提交规范
- 每次修改说明：改了什么 / 为什么改 / 影响范围
- 保持项目在任何时候都能跑
---
## 通用约束
1. 分析结果中标注文件路径和行号
2. 不确定的地方标注"待确认"
3. 全文中文，英文术语后附中文翻译
4. 不做过度抽象和过度封装
5. 项目解析优先理解链路和字段含义，不要为了炫技深挖无关底层
6. 工程交付时输出改动文件清单、核心改动说明、自测结果和后续建议
## 经验增强资源
- 项目解析与交付规则：`references/codebase-reading-delivery-rules.md`
---
## 自我迭代模式
### 触发条件
当用户在使用本技能后给出反馈（如"这部分不好用""输出格式需要改""多了/少了XX"），或主动说"优化这个skill"时，进入自我迭代模式。
### 迭代工作流
1. **收集反馈**：明确用户不满意的具体环节（哪个模式 / 哪个步骤 / 什么问题）
2. **诊断根因**：是规则缺失、规则冲突、粒度不够、还是场景未覆盖？
3. **提出修改方案**：列出拟修改的条目（原文 → 修改后），说明修改理由
4. **用户确认**：修改方案经用户确认后才执行
5. **写入 SKILL.md**：将修改直接应用到本技能文件
6. **记录迭代日志**：在 `references/iteration-log.md` 追加本次迭代记录
### 迭代日志格式
```markdown
## [日期] 迭代 #N
- **触发反馈**：...
- **根因**：...
- **修改内容**：...
- **影响范围**：模式X / 步骤Y
迭代约束
- 不破坏现有模式结构——增量修改，不推倒重写
- 每次迭代只改一个关注点——不趁机大改
- 修改后 SKILL.md 总行数仍 < 500
- 重大结构变更（如新增/删除模式）必须用户明确同意
