Skip to content

zzusp/doc-first-dev / skills/spec-first

spec-first

Verified

管理项目模块的完整开发周期:需求分析→更新技术方案→spec确认→开发→验收→收尾。适用于功能新增、Bug修复、需求变更、接口调整、重构、字段增删等涉及代码变更的任务;项目下有或无 spec 文档均可触发,无需用户明确指定流程。

FileKindSize
SKILL.mdskill md3.9 KB
assets/api-blank.mdmarkdown2.7 KB
assets/claude-md-snippet.mdmarkdown1.8 KB
assets/project-index.mdmarkdown1.7 KB
assets/tech-spec-blank.mdmarkdown4.8 KB
error-handling.mdmarkdown1.4 KB
evals/eval-01-new-feature.mdmarkdown1.8 KB
evals/eval-02-spec-code-mismatch.mdmarkdown1.3 KB
evals/eval-03-init-flow.mdmarkdown1.2 KB
init.mdmarkdown1.2 KB
phase-a.mdmarkdown10.5 KB
phase-b.mdmarkdown4.9 KB
phase-c.mdmarkdown6.8 KB
phase-d.mdmarkdown5.3 KB
step0.mdmarkdown3.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` | <含义> |
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: 197kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall