---
name: template-contribution-guide
type: governance_rule
asset_kind: governance_rule
owner_mechanism_id: mc-standard-asset-contract
authority: supporting
specificity: 5
lifecycle_status: active
routes: ['*']
scope:
  - '*'
when: '新增模版文件、模版贡献、模版资产维护'
stages: ["*"]
---

# 新增模版文件检查清单

向 `templates/` 目录新增文件时，必须按以下步骤操作。

> **权威规范**：字段合法值、必填/选填矩阵、命名规则详见 `templates/internal/rules/模版Frontmatter规范.md`。

---

## 一、确定目录

| 目录 | `type` | 职责 |
|------|--------|------|
| `patterns/` | `pattern` | 用户编码规范/设计模式 |
| `procedures/` | `procedure` / `pipeline_procedure` | 开发流程/管线工作流 |
| `artifacts/` | `artifact_template` / `acceptance_template` | 产出物模版/验收交付模版 |
| `rules/` | `review_rule` | 审查/校验规则 |
| `internal/rules/` | `governance_rule` | 引擎治理硬规则 |
| `internal/patterns/` | `pattern` | 引擎运行时模式 |
| `domain/` | `domain` | 领域知识 |
| `checklists/` | `checklist` | 验收清单（打勾式） |
| `gates/` | YAML 配置 | 阶段门控（独立格式，不纳入 .md 资产体系） |
| `scaffolds/` | `.hbs` 模版 | 代码脚手架（无 frontmatter，由脚手架引擎直接消费） |
| `profiles/` | `.yaml` 配置 | 产品配置（无 frontmatter，由配置加载器直接消费） |

**验收文件归属**：
- 打勾式清单（消费者是 AI 校验）→ `checklists/`（type: `checklist`）
- 产出物格式模版（消费者是 AI 按模版输出制品）→ `artifacts/`（type: `artifact_template`）

**系统类型分区**：`artifacts/`、`rules/`、`gates/` 内部按 `shared/` + `existing-system/` + `new-system/` 二级分区。其余目录无系统类型差异。

---

## 二、填写 Frontmatter

### 必填字段

```yaml
---
name: "文件中文名（kebab-case 或中文）"
type: "见上表 9 种合法值"
asset_kind: "与 type 兼容的注册侧分类"
routes:
  - "IntentRoute 值或 *"
scope:
  - "backend / frontend / infrastructure / *"
stages:
  - "需求分析 / 现有系统分析 / 架构设计 / 详细设计 / 任务规划 / 编码与单元测试 / 代码审查 / 联调验证"
  - "*"
lifecycle_status: "active / deprecated / draft"
owner_mechanism_id: "mc-xxx-yyy"
---
```

### 选填字段

| 字段 | 合法值 | 说明 |
|------|--------|------|
| `system_scope` | `shared` / `existing-system` / `new-system` | 默认 `shared` |
| `specificity` | 2-5 整数 | 优先级权重，默认 3 |
| `authority` | `canonical` / `supporting` | 仅 `internal/rules/` 和 `rules/shared/` 允许 `canonical` |
| `when` | 自然语言触发描述 | 描述什么场景下注入 |
| `primary_triggers` | 关键词列表 | 用于关键词匹配 |
| `consumes` | mechanism_id 列表 | 此资产依赖哪些机制产出 |
| `consumed_by` | mechanism_id 列表 | 此资产被哪些机制消费 |
| `emits` | 产物标识列表 | 此资产产出什么 |
| `required_evidence` | 证据标识列表 | 执行此资产需要什么证据 |
| `products` | `*` 或产品类型 | 当前全部 `*` |

### 禁止字段

| 字段 | 处理 |
|------|------|
| `status` | 已废弃，统一用 `lifecycle_status` |
| `migration_note` | 已废弃，运行时无意义 |

---

## 三、注册到代码

1. **ASSET_MANIFEST** — `src/engine/templates/asset_manifest.ts`
2. **ExplicitAssetRegistry** — `src/engine/templates/explicit_asset_registry/`
3. **type 配置** — 确认 type 在 `STAGE_TYPE_MAP`（`src/engine/pipeline/intent_expander/knowledge.ts`）和 `EXECUTION_SHAPE_ALLOWED_TYPES`（`src/engine/knowledge/knowledge_injection_boundary.ts`）中至少出现一次

---

## 四、命名规范

1. **用字统一**：文件名和内容中使用 `模版`，不使用 `模板`
2. **procedures/ 后缀**：
   - `流程` — 标准执行流程
   - `工作流` — 管线直接调度的工作流
   - `流水线` — 自动化多步骤流水线
3. **机制 ID**：`mc-` 前缀 + kebab-case。新建机制 ID 需在 `docs/SoloForge-工作流管线设计方案.md` 4.4 节登记

---

## 五、机制簇规则

同主题文件遵循五层纵深模型：

```
规则(governance_rule) → 流程(procedure) → 产出(artifact_template)
规范(pattern) → 审查(review_rule)
```

同 `owner_mechanism_id` 簇内的文件应覆盖不同层次。`consumes`/`consumed_by` 通过 `emits`/`required_evidence` 值匹配自动推断。

---

## 六、运行验证

```bash
# 合规测试（12 条规则，全部通过）
npx vitest run tests/architecture/template_frontmatter_compliance.test.ts

# 完整架构测试
npx vitest run tests/architecture/

# 全量测试
npm test -- --run
```

---

## 跳过任何步骤的后果

| 跳过步骤 | 失败测试 |
|---------|---------|
| frontmatter 字段缺失 | `template_frontmatter_compliance.test.ts` |
| 代码注册缺失 | `template_integrity.test.ts` |
| type 未配置 | `template_consumption_coverage.test.ts` |
| 新文件无法被消费 | `template_consumption_coverage.test.ts` |
