项目级补丁模板

---
name: project-patch-template
description: 【模板·复制后改名】项目级补丁 skill 模板。Praxis 里的用户级 skill（doc-layer-system / lightweight-design / docs-from-code 等）只含通用引擎与"留白挂载点"，不硬编码任何项目特定值。本模板把所有挂载点列成填空区——复制到你项目的 .agents/skills/ 下、改名为 <你的项目>-patch、逐项填上你项目的真实值，引擎即可挂载运行。触发词：由你按需声明。
---

# 项目级补丁模板（填空即用）

> 这是一份**空白模板**。Praxis 的用户级 skill 是"通用引擎"，项目独有的路径、域、死亡线、审查人等不写进引擎，而是由**每个项目自己的补丁 skill**声明。本模板把引擎暴露的所有挂载点收在一处，你照着填即可。

## 怎么用这份模板

1. 把本目录复制到你项目仓库的 `.agents/skills/<你的项目>-patch/`
2. 把 frontmatter 的 `name` 改成 `<你的项目>-patch`，`description` 写清它服务哪些引擎 skill
3. 逐节填下面的「填空区」——**没有的项就显式写「本项目不适用」**，不要留空（留空会让引擎以为你忘了声明）
4. 填完后，引擎 skill（如 doc-layer-system）运行时会读取本补丁，把通用规则叠加上你项目的特例

> 下文每个 `〔填空〕` 都给了一个**中性示例**仅作格式参考，务必替换成你项目的真实值。

---

## 0. 治理模式、授权角色与环境占用策略（全流程通用）

Praxis 不默认“任务发起人 = 业务裁决人 = 环境所有者 = 发布授权人 = 候选验收人”。个人项目可以由一人兼任全部角色；团队或受监管项目应按实际职责拆开，并声明是否要求职责分离。

| 挂载点 | 你的值（示例） |
|--------|--------------|
| 协作模式 | 〔填空〕  示例：单一负责人 / 多角色团队 / 受监管团队 |
| 任务发起人 | 〔填空〕  示例：需求负责人 |
| 业务决策负责人 | 〔填空〕  示例：产品 Owner |
| 环境所有者 | 〔填空〕  示例：测试环境管理员 |
| 发布授权人 | 〔填空〕  示例：值班发布负责人 |
| 候选验收人 | 〔填空〕  示例：未参与施工的技术负责人 |
| 职责分离要求 | 〔填空〕  示例：生产发布人与候选验收人不得是同一人 / 本项目不要求分离 |

未声明角色时，**不得**推定任务发起人自动拥有业务裁决、环境抢占、生产发布或最终验收权限。一个人兼任多角色也必须由项目治理规则明确，而不是由执行体猜测。

如项目存在共享环境、部署账本、租约或占用登记，再填写：

| 环境 | 占用机制 | 有效期 / 失效判据 | 可抢占角色 | 冲突处置 | 登记位置 |
|------|----------|------------------|------------|----------|----------|
| 〔填空〕 | 〔填空〕 | 〔填空〕 | 〔填空〕 | 〔填空〕 | 〔填空〕 |
| 示例：集成测试环境 | 示例：带 TTL 的租约 | 示例：到期或原持有人释放 | 示例：环境所有者 | 示例：等待 / 换隔离环境 / 明确授权后抢占 | 示例：运行资产中的部署账本 |

没有声明失效判据或抢占权限时，执行体不得仅因新任务启动就把现有占用判为过期；应优先使用隔离环境，无法继续则交付可恢复的操作性阻塞断点。环境配置、账号和凭据仍放项目受控配置中，不写进本补丁。

## 1. 项目形态（doc-layer-system）

声明本项目的文档分层形态，引擎据此裁剪可选层（L2 前端交互、L5 端到端流程可省略）。

```
项目形态：〔填空〕    # 示例：纯后端服务（省略 L2、L5）／ 全栈（七层齐全）／ CLI 工具
```

## 2. 业务域 / 功能模块列表（doc-layer-system）

声明本项目的域划分，引擎按域组织文档与拆分。

```
域列表：〔填空〕      # 示例：账户域、订单域、营销域、结算域
```

## 3. 目录路径（doc-layer-system）

引擎不知道你的文档放哪，这里钉死。

| 挂载点 | 你的值（示例） |
|--------|--------------|
| 文档根目录 `docs_root` | 〔填空〕  示例：`docs/` |
| 运行资产归属路径 | 〔填空〕  示例：`docs/06-运行资产/` |
| 任务总控目录 | 〔填空〕  示例：`docs/00-任务总控/` |

## 4. 单文档行数软上限（doc-layer-system / long-doc-governance）

超过即触发 long-doc-governance 拆分流程。

```
单文档行数软上限：〔填空〕    # 示例：800 行（不声明则默认 ≤800）
```

## 5. 死亡线区域清单（doc-layer-system，最高优先级）

> 引擎已内置**通用兜底死亡线**（鉴权 / 支付 / 用户数据删除 / 权限校验等），无需你声明即生效。
> 本节是在兜底之上**叠加**你项目特有的死亡线区域，**只能加不能减**。

| 死亡线区域 | 代码位置（示例） | 审查要点（示例） |
|-----------|----------------|----------------|
| 〔填空〕 | 〔填空〕 | 〔填空〕 |
|  示例：积分计算 | 示例：`score/CalcService` | 示例：倍率与封顶规则不得 AI 自改 |

## 6. 死亡线审查人绑定（doc-layer-system）

死亡线区域的任何变更必须由真人审查，这里把"能力要求"绑定到具体角色/岗位。

| 能力 | 审查人/岗位（示例） | 缺失时的降级方案（示例） |
|------|-------------------|----------------------|
| 〔填空〕 | 〔填空〕 | 〔填空〕 |
|  示例：L4 数据模型主审 | 示例：后端负责人 | 示例：由架构师兼任 |

## 7. 金标准领域清单（doc-layer-system L7）

声明本项目必须有金标准测试用例覆盖的核心领域。

```
金标准领域：〔填空〕    # 示例：核心算法、积分、等级、结算金额
```

## 8. L3 接口规范（doc-layer-system §L3 挂载点）

```
HTTP 方法约束：〔填空〕    # 示例：仅 GET / POST
参数规范：〔填空〕         # 示例：POST 参数放 body
翻页规则：〔填空〕         # 示例：游标分页
响应包装格式：〔填空〕     # 示例：统一 { code, msg, data }
鉴权方案：〔填空〕         # 示例：JWT Bearer
```

## 9. L4 数据规范（doc-layer-system §L4 挂载点）

```
ID 生成策略：〔填空〕      # 示例：Snowflake
必填公共字段：〔填空〕     # 示例：create_time、update_time
ORM 映射规范：〔填空〕     # 示例：下划线转驼峰
跨域引用约束：〔填空〕     # 示例：禁止跨域外键，只存 ID
```

## 10. 测试用例 ID 与命名规范（doc-layer-system L7）

```
测试用例 ID 格式：〔填空〕   # 示例：TC-<域>-<编号>，CI 可解析
测试用例命名规范：〔填空〕   # 示例：<域>_<场景>_<预期>
```

## 11. 协作 skill 名称映射（doc-layer-system §协作表）

引擎只描述"需要哪类协作 skill"，具体 skill 名由你声明。

| 引擎期望的协作类型 | 你项目里的 skill 名（示例） |
|------------------|--------------------------|
| 文档编写指南 | 〔填空〕  示例：`<你的项目名>-docs-guide` |
| 接口/后端构件 | 〔填空〕  示例：`create-api-endpoint` |
| 数据库构件 | 〔填空〕  示例：`create-db-table` |
| 数据库探查 | 〔填空〕  示例：`inspect-db-schema` |
| 测试与金标准 | 〔填空〕  示例：`test-and-goldens` |

## 12. 文档头元数据注入脚本（doc-layer-system，可选）

```
推断脚本：〔填空 / 本项目不适用〕    # 示例：scripts/inject-doc-meta.sh（从 Git 元数据注入文档头）
```

## 13. lightweight-design 挂载点

```
本项目轻量设计需引用的补丁项：〔填空〕      # 示例：复用本补丁 §3 路径、§5 死亡线清单
```

---

## 14. 项目研发流程适配器（总控 / goal-charter / plan-goal）

若本补丁负责研发流程绑定，在 description 或开头明确声明“项目研发流程适配器”。下列八槽均须填实际来源，或写“明确不支持 + 原因 + 受影响义务”；不能留空或用无解释 N/A。三个通用入口发现时只能选唯一完整适配器，不拼接多个候选。适配器只声明能力，不取得环境租约或动作授权。

| 槽位 | 项目值与权威引用 |
|---|---|
| 项目形态与研发阶段 | 〔填空〕 |
| 本地执行面与环境能力 | 〔填空〕 |
| 单环境或 A/B 语义 | 〔填空〕 |
| 生命周期、租约与异常恢复 | 〔填空〕 |
| 候选、测试数据与证据事实源 | 〔填空〕 |
| 测试、部署与文档项目路由 | 〔填空〕 |
| 自动验证器与人工边界 | 〔填空〕 |
| 不支持能力及阻断行为 | 〔填空〕 |

## 填写自检（提交补丁前逐条打勾）

- [ ] 每个 `〔填空〕` 都已替换为真实值，或显式写「本项目不适用」
- [ ] 死亡线清单只在通用兜底之上**叠加**，未删减兜底项
- [ ] 死亡线审查人是**真人角色**，没有写「AI 自审」
- [ ] 治理角色与职责分离要求已声明；未把任务发起人默认当成全部授权角色
- [ ] 共享环境的失效判据、抢占角色和冲突处置已声明；未用“启动任务即自动抢占”作默认规则
- [ ] 协作 skill 名与你项目 `.agents/skills/` 下的真实目录名一致
- [ ] 本补丁不含任何密钥 / 凭证（凭证归项目级配置，不进文档补丁）