zzusp/doc-first-dev / skills/spec-first
spec-first
Verified管理项目模块的完整开发周期:需求分析→更新技术方案→spec确认→开发→验收→收尾。适用于功能新增、Bug修复、需求变更、接口调整、重构、字段增删等涉及代码变更的任务;项目下有或无 spec 文档均可触发,无需用户明确指定流程。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.9 KB |
| assets/api-blank.md | markdown | 2.7 KB |
| assets/claude-md-snippet.md | markdown | 1.8 KB |
| assets/project-index.md | markdown | 1.7 KB |
| assets/tech-spec-blank.md | markdown | 4.8 KB |
| error-handling.md | markdown | 1.4 KB |
| evals/eval-01-new-feature.md | markdown | 1.8 KB |
| evals/eval-02-spec-code-mismatch.md | markdown | 1.3 KB |
| evals/eval-03-init-flow.md | markdown | 1.2 KB |
| init.md | markdown | 1.2 KB |
| phase-a.md | markdown | 10.5 KB |
| phase-b.md | markdown | 4.9 KB |
| phase-c.md | markdown | 6.8 KB |
| phase-d.md | markdown | 5.3 KB |
| step0.md | markdown | 3.9 KB |
assets/tech-spec-blank.md
View on GitHub# <模块名> 技术方案
> **文档目的**:记录 <模块名> 的需求、架构方案、代码结构、任务进度与验收情况。
> 本文档始终反映**当前状态**,不记录变更历史。
>
> **关联文档**:
> - `docs/decisions/log.md` — 开发决策记录(via `/whylog-record`)
---
## 一、需求边界
### 1.1 业务背景
<!-- 简述该模块解决什么问题、服务于哪类用户或业务场景 -->
### 1.2 核心需求
<!-- 用编号列表列出本期需要实现的功能,每条明确输入、输出和预期行为 -->
1. **功能 A**:...
2. **功能 B**:...
### 1.3 明确排除范围
<!-- 本期明确不做的功能,防止范围蔓延 -->
- ...
---
## 二、数据库设计
<!-- 说明涉及哪些数据源/Schema -->
### 2.1 表清单
| 表名 | 用途 | 关键字段 |
|---|---|---|
| `<table_name>` | ... | `id`, `...` |
### 2.2 `<table_name>` 字段说明
```
id, uuid — 主键
<field_name> — <语义说明>
<field_name> — <语义说明>(枚举:0=xxx, 1=xxx)
is_deleted — 软删标记
审计字段 — create_time/create_id/update_time/update_id
```
<!-- 如有 JSONB 字段,在此补充其内部结构;如有唯一键、外键等约束,在字段说明下方注明 -->
---
## 三、接口规范
<!-- 如有独立 API 文档,在此注明路径;本节按接口列出关键行为规则 -->
**<功能组 A>**
- `POST /xxx/list` — <关键行为规则,如分页逻辑、权限要求、过滤条件>
- `POST /xxx/save` — <关键行为规则,如字段写入约束、幂等性>
- `DELETE /xxx/{id}` — <关键行为规则,如软删还是物理删>
**<功能组 B>**
- `GET /xxx/detail` — <关键行为规则>
---
## 四、架构与设计规则
### 4.1 模块关系
<!-- 当前模块与其他模块的依赖、调用、数据流向 -->
### 4.2 数据流
```
请求 → Controller(参数校验)→ Service(业务逻辑)→ Mapper/Repository(数据访问)→ DB
```
### 4.3 复用模式
<!-- 可选节:记录本模块复用了哪些已有实现,便于开发时对齐 -->
| 复用点 | 参考文件 | 复用内容 |
|---|---|---|
| <复用点> | `XxxServiceImpl` | <复用的逻辑描述> |
### 4.4 设计规则
| 规则 | 说明 |
|---|---|
| <规则名> | <说明,以"结论"形式表达,不记录推导过程> |
---
## 五、代码地图
### 5.1 代码结构
**控制器层**
- `XxxController` — <负责的接口列表>
**服务层**
- `XxxService` / `XxxServiceImpl` — <职责>
**实体与 Mapper**
- `XxxEntity`、`XxxMapper` + `XxxMapper.xml`
**DTO/VO**
- `XxxQueryDto`、`XxxListItemVo`
**枚举**
- `XxxStatusEnum` — <枚举值列表>
**辅助工具**
- `XxxUtils` — <用途>
### 5.2 关键方法清单
| 文件 | 方法 | 职责 |
|---|---|---|
| `XxxServiceImpl` | `methodA()` | <做什么,维持哪些行为> |
---
## 六、任务状态
- T-01 · P0 · 待开始 — 在 `XxxMapper.xml` `selectPageList` 追加 xxx 条件;更新 `XxxMapper.java` 方法签名
> 格式:`- T-xx · P0/P1/P2 · 状态 — 内容(文件 + 方法)`。P0 = 阻塞,P1 = 重要,P2 = 可选。取消时保留行并注明原因。
---
## 七、验收项
### 7.1 验收方式
1. **编译验证**:运行构建命令通过(参考项目根目录 `CLAUDE.md` 中的"构建命令"章节)
2. **启动验证**:应用正常启动
3. **接口验证**:按「7.2 功能验收」逐接口断言
4. **数据库验证**:关键写入后核验数据
### 7.2 功能验收
#### Phase 0:准备
> 参考项目根目录 `CLAUDE.md` 中的"启动与认证"章节。
1. 启动应用
2. 获取认证信息,保存请求头
3. 确认测试数据:
- 测试账号:`<account>`
- 测试数据 ID:`<id>`
#### Phase 1:功能验收
- A-01 · `POST /xxx/list` · 待验证 — 传 `field=value`,返回 `total>0`,所有结果满足条件
<!-- 格式:`- A-xx · 接口 · 状态 — 具体断言(请求参数 + 预期响应)` -->
### 7.3 非功能验收
- 编译零错误
- 应用启动正常,无启动异常日志
- 所有接口返回规范响应格式
- 接口响应时间在合理范围内
### 7.4 文档验收
<!-- 列出需要与代码保持一致的外部文档,验收时逐项核对 -->
- `<docs/api-reference/xxx.md>` 与代码完全一致
- 本文档(`<docs/plans/xx/xxx-tech-spec.md>`)作为最终归档技术方案
---
## 八、附录
### 8.1 关键文件路径索引
```
src/.../
controller/
XxxController.<ext>
service/impl/
XxxServiceImpl.<ext>
mapper/
XxxMapper.<ext>
resources/mapper/
XxxMapper.xml
```
### 8.2 枚举值参考
| 枚举名 | 值 | 含义 |
|---|---|---|
| `XxxEnum.A` | `1` | <含义> |
| `XxxEnum.B` | `0` | <含义> |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |