代码库法条式规范起草

技能文档

---
name: front-depiction-writing-laws
title: 代码库法条式规范起草
description: 用法律条文风格为代码库起草正式「法条/公约/标准」，建立不可违反的架构约束与领域规则。输出含序言、条款、严重度分级与合规清单的规范文档。当用户需要制定强制编码规范、架构红线、领域约束、不可违反的团队约定、把口头规则固化为正式标准时触发。
category: 开发工具
---

# 代码库法条式规范起草

为代码库创建正式的法条（Laws）、公约（Covenants）或标准（Standards）。法条不是建议或指南，而是治理特定领域行为、不可违反的强制要求。

## 核心原则：法条定义事实，而非说服

法条陈述「是什么」与「必须是什么」。法条不做的事情：

- 解释原因（原因放在序言里）
- 描述后果（后果放在严重度分级里）
- 使用条件或对冲语言
- 诉诸偏好或观点

## 技能工作流

### 步骤1：确认立法范围

与用户确认：要约束的领域（如导入模式、状态管理、命名）、适用对象、是否有既有规范文档需要扩展。

### 步骤2：搭建文档结构

完整文档按四部分组织：**序言 → 法条 → 严重度分级 → 合规清单**（结构详见下文「文档结构」）。

### 步骤3：逐条撰写法条

每条法条独立成立，遵守条款编号（§ 记法）、强制性情态动词、定义语言三项规范（详见下文「法律语言」与「法条模板」）。

### 步骤4：分级严重度并生成合规清单

为每条法条确定严重度（CRITICAL / MAJOR / MINOR）并写入分级表，同时在合规清单中添加对应验证项。

### 步骤5：自查并交付

按「优秀法条的特征」（精确、完备、可测试、自包含、命令式）逐条自查，正反代码示例齐备后交付。

## 条款记法

### 章节编号

使用 § 符号的层级编号：

```
§ I      - 罗马数字表示主法条
§ I.1    - 小数表示子条款
§ I.1.a  - 小写字母表示子子条款
```

### 章节命名

每个章节配有方括号名称作为短标识：

```
§ VII [原子后缀约定]
§ VIII [原子的封闭性]
§ XII [服务让渡]
```

### 内部引用

用编号加名称引用其他章节：

```
依据 § III [活跃层的输出]，……
本法条在 …… 时取代 § IV.2。
相关要求见 § IX [动作模式]。
```

## 法律语言

### 强制性情态动词

| 动词 | 含义 | 用法 |
|------|---------|-------|
| SHALL | 绝对要求 | `[主体] SHALL [动作].` |
| SHALL NOT | 绝对禁止 | `[主体] SHALL NOT [动作].` |
| MUST | 等同于 SHALL | `[主体] MUST [提供/包含/满足].` |
| MUST NOT | 等同于 SHALL NOT | `[主体] MUST NOT [动作].` |
| IS REQUIRED TO | SHALL 的替代形式 | `[主体] IS REQUIRED TO [动作].` |
| IS PROHIBITED FROM | SHALL NOT 的替代形式 | `[主体] IS PROHIBITED FROM [动作].` |
| IS HEREBY DECREED | 宣告式确立 | `IT IS HEREBY DECREED that ...` |

### 定义语言

| 短语 | 用途 |
|--------|---------|
| `[术语] means ...` | 定义术语 |
| `[事物] is [分类]` | 归类事物 |
| `Any [X] that [条件]` | 按条件划定范围 |
| `For purposes of this section` | 限定定义适用范围 |
| `includes but is not limited to` | 非穷尽列举 |

### 归类语言

```
任何具备[属性]的[事物]均归入[类别]。
任何满足[判定条件]的[行为]均构成[违规类型]。
```

## 法条模板

### 简单禁止型

```markdown
## § X [名称]

**IT IS HEREBY DECREED** that [主体] SHALL NOT [被禁止的行为].

[主体]存在[被禁止行为]即构成对本法条的违反。
```

### 简单要求型

```markdown
## § X [名称]

**IT IS HEREBY DECREED** that [主体] SHALL [必须执行的动作].

[要素] MUST [满足条件]. [附加要求].
```

### 多条款型

```markdown
## § X [名称]

**IT IS HEREBY DECREED** that [总原则].

### § X.1 [第一个方面]

[主体] SHALL [要求 1].

### § X.2 [第二个方面]

[主体] SHALL NOT [禁止事项].

### § X.3 [例外]

[例外条件]时本法条不适用。
```

### 定义型

```markdown
## § X [定义]

在本公约中：

**"术语 A"** means [定义].

**"术语 B"** includes:
- [项 1]
- [项 2]
- [项 3]

**"术语 C"** does not include [排除项].
```

## 文档结构

### 序言（PREAMBLE）

序言说明法条为何存在，使用 WHEREAS 句式：

```markdown
## PREAMBLE

WHEREAS [基础事实 1];

WHEREAS [基础事实 2];

WHEREAS [要解决的问题];

NOW THEREFORE, the following LAWS are hereby declared and SHALL govern [领域] in perpetuity.
```

### 法条主体

每条法条独立成章，并附正反代码示例：

```markdown
## LAW I: [原则名称]

**IT IS HEREBY DECREED** that [核心要求].

[对要求、条件与约束的展开。]

```[语言]
// 合规示例
```

```[语言]
// FORBIDDEN: 违规示例
```
```

### 严重度分级

```markdown
## SEVERITY CLASSIFICATION

| 严重度 | 法条 | 后果 |
|----------|------|-------------|
| CRITICAL | [法条 X、Y] | [影响描述] |
| MAJOR | [法条 A、B、C] | [影响描述] |
| MINOR | [法条 D、E] | [影响描述] |
```

### 合规清单

```markdown
## COMPLIANCE CHECKLIST

[交付物]完成前逐项核验：

- [ ] **LAW I**: [验证陈述]
- [ ] **LAW II**: [验证陈述]
- [ ] **LAW III**: [验证陈述]
```

## 优秀法条的特征

1. **精确**：要求内容无歧义
2. **完备**：覆盖所有情形
3. **可测试**：合规与否可客观验证
4. **自包含**：无需外部上下文即可理解
5. **命令式**：是命令，不是建议

**正确示例：**

```markdown
## § VII [原子后缀约定]

**IT IS HEREBY DECREED** that all atom properties SHALL bear the `$` suffix.

此约定提供响应式状态的即时视觉识别。

```typescript
export interface SessionVM {
  readonly inputValue$: Atom.Atom<string>;    // $
  readonly history$: Atom.Atom<Prompt>;       // $
  readonly setInputValue: (value: string) => void;  // 无 $ - 不是 atom
}
```

**`$` 后缀是响应式的标志。原子缺失该后缀即构成欺骗。**
```

**错误示例：**

```markdown
## 命名约定

你大概应该给 atom 加 $ 后缀，这样更容易识别。
不用的话其他开发者可能会困惑，那样不好。
记得的时候尽量用。
```

## 应避免的写法

### 对冲语言

| 避免 | 改用 |
|-------|-------------|
| should | SHALL |
| might | 删除（消除不确定性） |
| probably | 删除（直接断言） |
| consider | IS REQUIRED TO |
| try to | SHALL |
| it's better to | SHALL |
| you might want to | IS REQUIRED TO |

### 法条正文中写后果

法条定义要求；后果属于严重度分级，不属于法条本身。

**法条正文中避免：**
```markdown
违反此条会出大问题，代码库会变得无法维护。
```

**严重度章节中可以写：**
```markdown
| CRITICAL | VIII, XII | 必须立即整改。代码不可测试。 |
```

### 观点与偏好

法条不表达偏好，只确立事实。

**避免：**
```markdown
我觉得命名空间导入更干净，用这个比较好。
```

**改用：**
```markdown
[主体] SHALL 以命名空间形式导入。具名导入 IS PROHIBITED。
```

### 条件式要求

确有条件时，把条件写明、要求写绝：

**避免：**
```markdown
如果想要可观测性，可能需要加 span。
```

**改用：**
```markdown
所有异步动作 SHALL 用 `Effect.withSpan()` 包裹。无例外。
```

## 扩展现有规范文档

向既有公约文档追加法条时：

1. **确定下一个法条编号**：审阅现有法条，顺延使用下一个罗马数字
2. **遵循既有模式**：与文档中现有法条的结构、语言、格式保持一致
3. **补充分级**：为新法条确定严重度并加入分级表
4. **更新合规清单**：添加对应验证项
5. **双向交叉引用**：与相关法条互相引用

## 完整迷你公约示例

```markdown
# THE IMPORT COVENANTS

## PREAMBLE

WHEREAS consistent import patterns reduce cognitive load;

WHEREAS namespace imports preserve type and value unity;

WHEREAS scattered named imports cause name collisions;

NOW THEREFORE, the following LAWS are hereby declared and SHALL govern all import statements.

---

## LAW I: The Namespace Requirement

**IT IS HEREBY DECREED** that all Effect module imports SHALL use the namespace pattern.

```typescript
// CORRECT
import * as Effect from "effect/Effect"
import * as Option from "effect/Option"

// FORBIDDEN
import { Effect, pipe } from "effect"
import { Option, none, some } from "effect/Option"
```

---

## LAW II: The Local Module Pattern

**IT IS HEREBY DECREED** that local domain modules SHALL be imported as namespaces.

```typescript
// CORRECT
import * as Task from "@/schemas/Task"
const task = Task.makePending({ ... })

// FORBIDDEN
import { makePending, isPending } from "@/schemas/Task"
```

---

## SEVERITY CLASSIFICATION

| 严重度 | 法条 | 影响 |
|----------|------|--------|
| MINOR | I, II | 风格不一致，随时间累积 |

---

## COMPLIANCE CHECKLIST

- [ ] **LAW I**: 所有 Effect 导入使用命名空间模式
- [ ] **LAW II**: 所有本地领域模块导入使用命名空间模式
```

## 适用场景

- 确立绝不可违反的架构约束
- 把已被证明对可维护性至关重要的模式固化为条文
- 为代码库新领域制定领域标准
- 把非正式的口头规则转化为可执行的公约
- 向既有公约文档追加新法条

## 关键原则速记

1. 法条用 SHALL / SHALL NOT，绝不用建议语气
2. 定义精确无歧义
3. 结构遵循 § 章节记法
4. 序言解释为什么，法条陈述是什么
5. 后果写在严重度表里，不写在法条正文里
6. 每条法条可测试、可验证
7. 代码示例同时给出合规与违规两版
8. 相关法条显式交叉引用
9. 合规清单支持逐项核验
10. 法条定义事实，不做说服

使用说明

# 代码库法条式规范起草

用法律条文风格为代码库起草正式「法条/公约/标准」，建立不可违反的架构约束与领域规则。

## 能做什么

- 产出结构完整的规范文档：序言（WHEREAS）→ 法条（§ 编号）→ 严重度分级 → 合规清单
- 提供条款记法、强制性情态动词（SHALL / MUST NOT 等）、定义语言的起草规范
- 内置禁止型、要求型、多条款型、定义型四类法条模板
- 支持向既有公约文档追加新法条（编号顺延、双向交叉引用）

## 何时使用

- 制定强制编码规范、架构红线
- 把口头约定固化为可执行、可验证的团队标准
- 为代码库新领域确立领域规则

## 快速上手

```text
为我们的前端项目起草一份状态管理公约，要求所有状态更新必须走统一入口
```

```text
把我们的口头规则「禁止直接操作 DOM」写成正式法条，含严重度分级和合规清单
```

## 目录结构

- `SKILL.md`：起草工作流、条款记法、语言规范与模板

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。