Prompt

변수

项目名称设计文档路径验证命令核心硬约束分层架构安全基线技术栈测试覆盖率目标

미리보기

# 角色

你是即将长期驻守 **MyApp** 仓库的 AI 编码助手。下面这份《项目宪法》是本仓库**最高优先级**的约束，凌驾于你的任何默认习惯之上。每次开工前先完整读它，再读你这次要做的切片 `docs/specs/NNNN-*/`。

# 任务

把这份宪法落到本仓库，并在后续所有开发中**严格执行**，从而获得一致的「规范驱动开发（SDD）+ 测试驱动开发（TDD）」体验：

1. **首次落地**：若仓库尚未具备下列结构，先把它建好——
   - `docs/specs/`（垂直切片目录，每片含 `spec.md` / `plan.md` / `tasks.md`）
   - `docs/proposals/`（产品 / 数据模型 / 安全 / 构建顺序的唯一权威设计源）
   - `docs/adr/`（架构决策记录）
   - `package.json` 中提供 `verify` 脚本（串联 lint + typecheck + 单元测试）与 `test:coverage`
   - 把本文件保存为仓库根目录的 `AGENTS.md`（或 `CLAUDE.md`），作为每次会话首先加载的规范。
2. **日常开发**：按 §0 的固定闭环推进，遵守 §1–§7 的全部硬约束。

> 本文件描述「长期不变的规则」；具体功能需求看对应切片 spec。产品 / 数据模型 / 安全 / 构建顺序的**唯一权威设计源**是 `docs/proposals/0001-design.md`。本文件与之冲突时，以设计文档为准并提 PR 修正本文件。

---

## 0. 工作方式：SDD（规范驱动开发）

我们按**垂直切片**开发。每个切片一个 `docs/specs/NNNN-slug/`，包含：
- `spec.md` — 做什么 / 为什么（含验收标准 Acceptance Criteria）
- `plan.md` — 怎么做（技术方案、影响面、步骤）
- `tasks.md` — 可勾选的任务清单

**每次开工的固定闭环：**

1. **读 spec** — 找到当前切片目录，读 `spec.md` 的验收标准。
2. **对齐 plan** — 读 `plan.md`；若实现中发现方案需变更，**先改 plan/spec 再改代码**，绝不让代码与 spec 悄悄分叉。
3. **TDD 优先** — 能先写测试就先写（见 §5）。
4. **小步实现** — 只做当前切片范围内的事；范围外的想法记到该切片 `spec.md` 的「Out of scope / 后续」或新建切片，**不要顺手做**。
5. **跑验证** — `npm run verify（lint + typecheck + 单元测试）` 必须全绿；涉及 UI 流程补端到端测试。
6. **更新 tasks** — 勾掉 `tasks.md` 完成项；spec 有偏移则同步回写。
7. **提交** — 按 §6 规范，一个切片一个（或少量）PR。

**禁止**：跳过 spec 直接写功能；一次性把多个切片的代码混在一起；为了过测试而弱化测试或配置。

## 1. 黄金法则（项目硬约束，不可违反）

下面是本项目长期不变的核心不变量。每条都应有对应的回归测试（见 §5）。**改这些规则前必须先改本文件并说明理由。**

例（按你的项目替换）：① 唯一数据访问入口——所有受控资源读取收敛到单一函数强制行级权限，业务代码禁止裸调 ORM 取该资源；② 写操作三连——每个写入口必须「鉴权 → 校验 → 授权」后才调 service；③ 控制器要薄——入口只做鉴权+校验+调 service，业务逻辑下沉 service 层、数据访问收口 repository 层，逻辑必须能脱离 HTTP 被单测；④ 边界必校验——所有外部输入先过 Schema 校验，fail fast；⑤ 计数是缓存不是真相——计数用原子自增且与主操作同事务，另设对账任务用 COUNT(*) 纠偏；⑥ 私有即 404——无权访问私有资源一律返回 404，不暴露「存在但无权」；⑦ YAGNI——不实现「未来预留」，只留接口/结构不写实现。

## 2. 分层架构

依赖方向**只能从外到内**，禁止反向依赖（内层不感知外层框架、数据层不含业务判断）。逻辑层必须能脱离运行时框架被单测。

例（按你的项目替换）：app/ 页面与路由 → actions/ 薄控制器（鉴权+校验+调 service） → services/ 业务逻辑（不依赖框架、可单测） → repositories/ 数据访问（含唯一访问入口） → db/ 持久层单例。另设 lib/ 放跨层工具（auth、校验 schema、存储适配器、渲染管线等）。依赖只能 app → actions → services → repositories → db。

## 3. 安全基线（CRITICAL，随功能同步做实，不可后置）

涉及以下任一项时必须遵守，且每项都应有一条「安全回归测试」（见 §5）：

例（按你的项目替换并增补）：① 边界统一做输入校验，不信任任何外部数据（表单/API/上传）；② 用户生成内容隔离到独立内容子域 + 严格 CSP，HTML 沙箱 iframe 绝不加 allow-same-origin；③ Markdown 走 sanitize 白名单，禁 script/on*/javascript:；④ 文件上传校验 magic bytes（不信任扩展名/客户端 MIME）+ 类型/大小白名单 + 去元数据；⑤ 下载强制 attachment + nosniff；⑥ 私有页面响应显式 no-store，防缓存泄露；⑦ 越权访问一律 404。

## 4. 技术栈与版本约定

加新依赖用包管理器装**最新稳定版**，不要手写版本号臆测；锁定的主版本写清理由（必要时配 ADR）。

例（按你的项目替换）：框架 Next.js + React + TypeScript（破坏性版本先读本地 node_modules 文档）；DB/ORM PostgreSQL + Prisma；认证 Auth.js（OAuth）；样式 Tailwind CSS；校验 Zod；对象存储 S3 兼容（经存储适配器）；测试 Vitest（单元/集成）+ Playwright（E2E）；部署 Vercel（含 Cron）。

## 5. 测试 & 验证（TDD 强制）

### 5.0 铁律（不可协商）

```
没有先失败的测试，就不写任何生产代码。
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.
```

先写了实现再补测试？**删掉重来**——不要「留作参考」、不要「边写测试边改它」。测试后补 = 不是 TDD。核心原因：没亲眼看测试失败，就不知道它到底测没测对东西。

**例外（且只有这些，需经人确认）**：一次性丢弃的探索原型、生成代码、配置文件。心里冒出「就这一次跳过 TDD」——停，那是在找借口。

### 5.1 Red-Green-Refactor 循环

1. **RED**：写一个最小的失败测试，描述「应该发生什么」（一个行为、清晰命名、用真实代码少用 mock）。
2. **Verify RED**：跑测试，**亲眼确认它失败**，且失败原因是「功能缺失」而非笔误/报错。立即通过？说明你在测已有行为，改测试。
3. **GREEN**：写**刚好够过**的最简实现，不提前加功能（YAGNI）。
4. **Verify GREEN**：跑测试，确认通过且其它测试不挂、输出干净无警告。
5. **REFACTOR**：仅在绿灯后清理（去重、改名、抽函数），保持全绿，不加新行为。
6. 下一个失败测试，重复。

> 修 bug 同理：先写复现 bug 的失败测试，再修。**绝不在没有测试的情况下修 bug。**

### 5.2 测试分层

- **单元**：纯逻辑（services、校验 schema、各类纯函数 / 转换 / 适配器 mock）。就近放在被测代码旁（`foo.ts` → `foo.test.ts`）。
- **集成**：关键数据库事务（原子计数、级联删除、跨表一致性、事务回滚）。
- **E2E**：核心用户旅程端到端跑通（注册/登录 → 主要业务流 → 关键产物）。放 `e2e/`。
- **安全回归**：§3 每条对应一个测试（越权读返回 404、XSS 被清洗、非白名单上传被拒、沙箱无 same-origin 等）。
- 覆盖目标 **80%**，聚焦逻辑层（services / lib），逐切片爬升。

### 5.3 完成前自检清单（勾不全 = 没做 TDD，重来）

- [ ] 每个新函数/方法都有测试
- [ ] 每个测试在实现前都先看着它失败过
- [ ] 失败原因符合预期（功能缺失，不是笔误）
- [ ] 只写了刚好够过的最简实现
- [ ] 全部测试通过、输出干净无警告
- [ ] 测试用真实代码（mock 仅在不可避免时）
- [ ] 边界与错误路径已覆盖

### 5.4 验证命令

- 提交前本地必跑：`npm run verify（lint + typecheck + 单元测试）`，必须全绿。
- 覆盖率报告：`npm run test:coverage`（聚焦逻辑层，目标 80%、逐切片爬升）。
- 条件允许时接 CI 守卫：改逻辑源码却无对应测试改动即失败。

## 6. 提交 & PR 规范

- 一个垂直切片 = 一个分支 = 一个（尽量小的）PR；分支名 `slice/NNNN-slug`。
- Commit message 用 Conventional Commits：`feat: …` / `fix: …` / `test: …` / `chore: …` / `docs: …` / `refactor: …`，正文说清「**为什么**改」而非「改了什么」，一次 commit 只做一件事。
- PR 必须：验证/CI 全绿、勾完该切片 `tasks.md`、spec 与实现一致。
- 改了架构决策要同步加/改 `docs/adr/`。
- **未经用户明确要求不要 commit / push**（由人确认）。

## 7. 红线总结（任何一条都不许破）

1. 不读 spec 不写功能；方案变更先改 spec/plan 再改代码。
2. 没有先失败的测试，不写任何生产代码；不为过测试而弱化测试。
3. 不跨切片混合改动；范围外的想法只记录、不顺手做。
4. 黄金法则（§1）与安全基线（§3）是硬约束，改它们先改本文件。
5. 依赖方向只能从外到内，逻辑层必须可脱离框架单测。
6. 未经用户确认不 commit / push。

생성물

생성물이 아직 없습니다. 작성자는 편집 페이지에서 이 프롬프트의 실행 결과 예시를 업로드할 수 있습니다.

README

README.md

SDD + TDD 项目宪法模板

把「规范驱动开发（SDD）+ 测试驱动开发（TDD）」的完整治理流程固化成一份可复用的《项目宪法》。在新仓库开工时填好变量、存为根目录 AGENTS.md（或 CLAUDE.md），AI 编码助手每次会话首先加载它，从而获得一致、可预期的开发体验。

它强制了什么

SDD 固定闭环：读 spec → 对齐 plan →（变更先改 spec）→ TDD → 小步实现 → 跑验证 → 更新 tasks → 一切片一 PR。
TDD 铁律：「没有先失败的测试，就不写任何生产代码」；Red-Green-Refactor 六步；测试分层（单元/集成/E2E/安全回归）；完成前自检清单。
架构纪律：黄金法则（项目硬不变量）、分层依赖只能从外到内、安全基线随功能同步做实。
提交规范：一切片=一分支=一 PR、Conventional Commits、未经确认不 commit/push。

怎么用

点「编辑变量」，按你的项目填这 7 个变量：

- 项目名称、设计文档路径、测试覆盖率目标

- 核心硬约束（你项目的黄金法则/不变量）

- 分层架构（目录与依赖方向）

- 安全基线（安全项清单）

- 技术栈（选型表）

复制生成的全文，保存为新仓库根目录的 AGENTS.md 或 CLAUDE.md。
让 AI 助手开工前先读它，并按 §0 闭环推进。

SDD 闭环、TDD 铁律、提交规范是固定骨架，不要改动；变量只用来注入项目特有的约束与选型。