القائمة
项目理解与工程开发技能：覆盖代码阅读理解、逐行代码讲解、语法拆解、项目架构解析、后端链路分析、工程化开发规范。Use when: 理解代码、解释这行代码、逐段讲解一个方法、语法教学、解析项目、分析后端链路、接口追踪、数据流分析、工程开发、代码Review、架构梳理。不适用于软著项目（使用 software-copyright-zh）。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Guides stable API and interface design. Use when designing APIs, module boundaries, or any public interface. Use when creating REST or GraphQL endpoints, defining type contracts between modules, or establishing boundaries between frontend and backend.
Tests in real browsers. Use when building or debugging anything that runs in a browser. Use when you need to inspect the DOM, capture console errors, analyze network requests, profile performance, or verify visual output with real runtime data via Chrome DevTools MCP.
Automates CI/CD pipeline setup. Use when setting up or modifying build and deployment pipelines. Use when you need to automate quality gates, configure test runners in CI, or establish deployment strategies.
Simplifies code for clarity. Use when refactoring code for clarity without changing behavior. Use when code works but is harder to read, maintain, or extend than it should be. Use when reviewing code that has accumulated unnecessary complexity.
Optimizes agent context setup. Use when starting a new session, when agent output quality degrades, when switching between tasks, or when you need to configure rules files and context for a project.
Guides systematic root-cause debugging. Use when tests fail, builds break, behavior doesn't match expectations, or you encounter any unexpected error. Use when you need a systematic approach to finding and fixing the root cause rather than guessing.
| name | project-dev-zh |
| description | 项目理解与工程开发技能：覆盖代码阅读理解、逐行代码讲解、语法拆解、项目架构解析、后端链路分析、工程化开发规范。Use when: 理解代码、解释这行代码、逐段讲解一个方法、语法教学、解析项目、分析后端链路、接口追踪、数据流分析、工程开发、代码Review、架构梳理。不适用于软著项目（使用 software-copyright-zh）。 |
只要本工作流将初始化或重组项目，或新建、移动应用、服务、包、模块、页面、API、研究步骤、实验、流水线、测试、文档或多文件产物树，必须先使用 project-structure-architect。
AGENTS.md、PROJECT_STRUCTURE.md、.project-structure.yaml 和现有文件树，锁定项目类型、蓝图及唯一合理路径。BLOCK 时停止结构性写入并先修正或询问用户。纯内容编辑且目标路径已由用户或现有规范唯一确定时，可不重复调用。
提供从"代码阅读→项目理解→链路追踪→工程开发"的完整技术支持，确保在理解现有代码的基础上做出高质量的增量修改。
skill-outputs/project-dev-zh/（与 artifact-curator-zh 按技能分子目录一致；根目录为 legacy-flat 兼容）。若该子目录不存在须先创建。中文主题_YYYYMMDD_HHMMSS.md（置于上述目录下；文件名不再重复 skill 名）；若主题不明确，使用 结果_YYYYMMDD_HHMMSS.md。skill-outputs/project-dev-zh/ 前缀），以及文件里包含的主要内容。| 模式 | 判定条件 | 核心目标 |
|---|---|---|
| A. 代码理解 | "帮我理解这段/这个文件""这段代码做了什么""逐行讲这个方法""解释这行语法" | 4级递进理解 |
| B. 项目架构解析 | "解析项目结构""梳理架构""这个项目怎么组织的" | 分层架构 + 模块关系 |
| C. 后端链路分析 | "追踪接口""数据流怎么走""从请求到数据库" | 完整链路图 |
| D. 工程化开发 | "开发XX功能""改这个模块""加个接口" | 符合工程规范的增量开发 |
目标：30秒内知道这段代码"做了什么"
输出：
目标：能向别人讲清楚"怎么做的"
输出：
目标：理解"为什么这样写"
输出：
目标：判断"能改什么、改了会影响什么"
输出：
名词速览 → 原代码片段 → 语法解释 → 本段业务作用 → 等价展开写法 → 整体执行流程。for/if/普通赋值 展开版。## 名词速览
- `术语`：通用含义（一句话）
- 在这里的作用：[它在当前函数/当前调用点里具体做什么]
- 简单例子：[一个最小例子或生活化对照]
## 这段代码整体在做什么
[先用一句话说明方法/片段的业务作用]
```python
[原始代码片段]
语法点/关键字：[字面意思][更直白的 if/for/普通写法]
[把"代码做什么"和"用了哪些关键语法"收束成一句话]
---
## 模式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