project-dev-zh

name	project-dev-zh
description	项目理解与工程开发技能：覆盖代码阅读理解、逐行代码讲解、语法拆解、项目架构解析、后端链路分析、工程化开发规范。Use when: 理解代码、解释这行代码、逐段讲解一个方法、语法教学、解析项目、分析后端链路、接口追踪、数据流分析、工程开发、代码Review、架构梳理。不适用于软著项目（使用 software-copyright-zh）。

项目理解与工程开发技能

Project structure gate / 文件树结构门禁

只要本工作流将初始化或重组项目，或新建、移动应用、服务、包、模块、页面、API、研究步骤、实验、流水线、测试、文档或多文件产物树，必须先使用 project-structure-architect。

1. 开始前：读取适用的 AGENTS.md、PROJECT_STRUCTURE.md、.project-structure.yaml 和现有文件树，锁定项目类型、蓝图及唯一合理路径。
2. 运行中：每次新增或移动文件前先判断职责、所有者、复用范围和对应测试；禁止同义目录、根目录堆放、跨层混放及无关重组。
3. 阶段收口：纵向切片或阶段完成后检查结构漂移；新项目或重大重组更新结构文档，最终运行结构审计。出现 BLOCK 时停止结构性写入并先修正或询问用户。

纯内容编辑且目标路径已由用户或现有规范唯一确定时，可不重复调用。

技能目标

提供从"代码阅读→项目理解→链路追踪→工程开发"的完整技术支持，确保在理解现有代码的基础上做出高质量的增量修改。

Markdown 交付要求

1. 使用本技能完成正式输出时，除聊天中的简要说明外，必须在当前工作区新建一个 Markdown 文档保存完整结果。
2. 默认保存位置为当前工作区 skill-outputs/project-dev-zh/（与 artifact-curator-zh 按技能分子目录一致；根目录为 legacy-flat 兼容）。若该子目录不存在须先创建。
3. 默认文件名格式为 中文主题_YYYYMMDD_HHMMSS.md（置于上述目录下；文件名不再重复 skill 名）；若主题不明确，使用 结果_YYYYMMDD_HHMMSS.md。
4. Markdown 文档必须包含完整代码分析、架构说明、链路追踪结果、修改建议或开发方案。
5. 若用户明确指定保存路径或文件名，以用户要求为准；若用户明确要求只在对话中回答，可跳过创建文件。
6. 最终回复中要说明新建的 Markdown 文件路径（须含 skill-outputs/project-dev-zh/ 前缀），以及文件里包含的主要内容。

任务模式判定

模式	判定条件	核心目标
A. 代码理解	"帮我理解这段/这个文件""这段代码做了什么""逐行讲这个方法""解释这行语法"	4级递进理解
B. 项目架构解析	"解析项目结构""梳理架构""这个项目怎么组织的"	分层架构 + 模块关系
C. 后端链路分析	"追踪接口""数据流怎么走""从请求到数据库"	完整链路图
D. 工程化开发	"开发XX功能""改这个模块""加个接口"	符合工程规范的增量开发

---

模式A：代码理解（4级递进）

V1 —— 主干速览

目标：30秒内知道这段代码"做了什么"

输出：

1. 一句话总结功能
2. 输入是什么 / 输出是什么
3. 核心数据结构

V2 —— 逻辑拆解

目标：能向别人讲清楚"怎么做的"

输出：

1. 分步拆解主要逻辑流程
2. 关键分支与边界条件
3. 调用了哪些外部依赖
4. 用一段话的类比解释核心思想

V3 —— 设计意图

目标：理解"为什么这样写"

输出：

1. 设计模式识别（如有）
2. 性能/可维护性/安全性的权衡
3. 可能的替代方案及其取舍
4. 潜在的坑/隐患

V4 —— 可修改性评估

目标：判断"能改什么、改了会影响什么"

输出：

1. 修改热区（最可能需要改动的地方）
2. 耦合分析（改这里会影响哪些地方）
3. 测试覆盖建议
4. 安全修改路径推荐

使用规则

• 用户未指定级别时，默认输出 V2
• 用户说"详细"时输出到 V3
• 用户说"我想改它"时直接跳到 V4
• 每级都要标注对应的代码行号

代码教学增强规则

• 当用户要求"逐行讲解""解释这行语法""用初学者方式讲""把这段代码展开讲"时，仍使用模式A，但输出必须切换为"语法 + 业务"双线讲解。
• 输出顺序优先为：名词速览 → 原代码片段 → 语法解释 → 本段业务作用 → 等价展开写法 → 整体执行流程。
• 名词速览只列本段理解必需的术语，避免把不相关概念堆成词典。
• 名词速览不能只给通用定义，必须补上“它在当前函数 / 当前方法签名 / 当前调用点 / 当前会话里的具体作用”。
• 如果术语是变量、参数、配置项、装饰器、返回类型或对象成员，优先解释它在本地上下文中影响了什么，而不是先讲教科书定义。
• 对知识点、术语和语法点的解释，都要补一个简单例子帮助理解；例子优先 1-3 行的小片段或一句生活化对照，不要上来就给复杂业务样例。
• 语法解释必须绑定当前代码片段，回答"这行代码怎么写出来的、为什么这里这样写"，不能只给抽象定义。
• 遇到列表推导式、条件表达式、切片、zip 解包、with 上下文、类型注解等压缩写法时，优先给出等价的 for/if/普通赋值 展开版。
• 相同语法第一次详细解释，后续重复出现时只补充本处差异，避免逐行机械重复。
• 如果这段代码还承担链路中的一跳，要顺手说明"这一跳从上游拿到了什么、往下游交出了什么"，但不要把语法讲解完全替换成链路图。

代码教学输出模板

## 名词速览

- `术语`：通用含义（一句话）
- 在这里的作用：[它在当前函数/当前调用点里具体做什么]
- 简单例子：[一个最小例子或生活化对照]

## 这段代码整体在做什么

[先用一句话说明方法/片段的业务作用]

```python
[原始代码片段]

• 语法点/关键字：[字面意思]
• 本段作用：[在当前业务里的作用]
• 简单例子：[一个最小可理解例子]
• 等价展开：

[更直白的 if/for/普通写法]

整段执行流程

1. [步骤1]
2. [步骤2]
3. [步骤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
• 重大结构变更（如新增/删除模式）必须用户明确同意