# 模板

地址: https://nowa.im/cotty/zh/handbook/templates/  
状态: 草稿  
创建: 2026-11-22

本页是每类文档的骨架。开始写一篇文档时，把骨架复制到两种语言各一个新文件里。每个标题下面的那句话说明这里该写什么，写的时候替换掉它。不适用的章节保留，并用一行说明原因。

元数据字段的定义见[文档体系](https://nowa.im/cotty/zh/handbook/documentation/#元数据)。

## 能力页

能力页放在 `product/`。它从用户的角度描述产品做的一件事。

```markdown
---
title: 能力的名称
status: draft
created: YYYY-MM-DD
---

一段话：这个能力是什么，为谁服务。

## 问题与证据

现在哪里有问题，并链接到调研和实地记录。

## 场景

这个能力服务的场景，写编号。

## 行为

写成可以检验的陈述的规则。每条规则配一个例子。

## 状态

对象会经历哪些状态，什么引起每次变化。

## 界面

用户在每种设备上看到什么、做什么。

## 不在范围内

这个能力不做什么。

## 依赖

它依赖的内核能力，并链接到架构和规范。

## 待决问题

还没有决定的事。
```

## 版本设计

版本设计放在 `versions/`。

```markdown
---
title: vX.Y
status: planning
created: YYYY-MM-DD
---

一句话：这个版本的主题。

## 场景

这个版本之后必须成立的场景。它们同时是验收脚本。

## 做与不做

这个版本做什么，以及有意不做什么。

## 对产品设计的改动

逐条列出改动，并链接到被改动的产品页面。

## 技术工作

这个版本需要的 RFC。

## 风险与待决问题

可能出什么问题，以及还没有决定的事。

## 完成标准

怎样算这个版本做完了。

## 回顾

发布之后写：和计划有什么不同，学到了什么。
```

## RFC

RFC 放在 `rfcs/`。流程见 [RFC 流程](https://nowa.im/cotty/zh/handbook/rfc-process/)。

```markdown
---
title: 这个决定的简短名称
rfc: 0
status: draft
created: YYYY-MM-DD
affects:
  - specs/example.md
---

## 摘要

一段话：提议什么。

## 动机

它服务的场景、证据，以及不做会怎样。

## 目标与非目标

这个决定必须达到什么，以及不打算达到什么。

## 已有做法

别人怎么做。链接到调研，不复述。

## 方案

思路、关键的不变量，以及一两个例子。确切的条文在受影响的页面里。

## 考虑过的备选方案

每个备选方案，以及没有选它的原因。

## 兼容性与迁移

哪些已有的行为、数据或文档受影响，它们怎么过渡。

## 安全与隐私

这个决定暴露了什么，保护了什么。

## 缺点与风险

代价是什么，可能出什么问题。

## 验证

怎样知道它是正确的。

## 待决问题

接受之前必须为空，或者每个问题都写明理由后延期。

## 实施

工作的顺序，以及要先读的页面和文件。
```

## 规范页

规范页放在 `specs/`。它是写给在项目之外实现它的人看的。它用"必须"、"应当"、"可以"来表述要求。

```markdown
---
title: 协议、格式或 API 的名称
status: draft
created: YYYY-MM-DD
---

一段话：这里规定的是什么，由谁来实现。

## 稳定性与版本

它是实验性的还是稳定的，以及它的版本。只有稳定的部分有兼容性承诺。

## 现状的问题

现在做不到什么，或者做得不好的地方。

## 快速上手

一个照着就能运行的例子。

## 术语与不变量

本页使用的词，以及始终成立的事。

## 格式与语义

确切的格式，以及每个部分的含义。

## 探测与退化

程序如何得知是否支持它，以及不支持时会怎样。

## 与现有协议的关系

它和终端、agent 已经在用的东西如何配合。

## 安全考虑

攻击者能做什么，什么限制了他。

## 例子与测试向量

输入和它们应有的结果。

## 已知实现

实现了它的程序。
```

## 架构页

架构页放在 `architecture/`。

```markdown
---
title: 组件或机制的名称
status: draft
created: YYYY-MM-DD
---

一段话：这个部分做什么，处在什么位置。

## 兼容性政策

什么必须保持可用，什么可以破坏。

## 目标与非目标

这个部分必须达到什么，以及不打算达到什么。

## 概念与不变量

涉及的对象，以及始终成立的事。

## 执行轨迹

主要路径的逐步轨迹，包括可能崩溃的位置，以及恢复如何进行。

## 接口与实现

这个部分提供的接口，以及它是怎么构成的。

## 待决问题

还没有决定的事。

## 测试策略

如何检验正确性。

## 必读清单

在这个部分上工作之前要读的页面和文件，按顺序列出。
```

## 调研

调研放在 `research/` 的某个目录里。

```markdown
---
title: 要回答的问题，或调研的对象
created: YYYY-MM-DD
as_of: YYYY-MM-DD
---

一段话：问题是什么，简短的答案是什么。

## 发现

事实。每条说法标注可靠性：官方、厂商或第三方。

## 对 cotty 的含义

对产品设计或技术设计的影响。

## 来源

用到的所有资料的链接。

## 没有覆盖

没有看的部分。
```

## 文章

文章放在 `posts/`。

```markdown
---
title: 要论证的观点，或文章的主题
created: YYYY-MM-DD
---

一段话：观点是什么，它为什么对 cotty 重要。

## 论证

每一步一节，用这一节的结论做标题。带日期的事实属于调研笔记，文章链接过去。

## 我们从中得到什么

对 cotty 的推论，并链接到状态文档。

## 参考

文章所依据的所有资料的链接。
```
