agent-notes-kit 0.0.0-stage → 1.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +190 -2
- package/install.mjs +254 -0
- package/package.json +23 -4
- package/scripts/agent-note-tree.mjs +77 -0
- package/scripts/archived-agent-notes.mjs +143 -0
- package/scripts/verify-agent-note-classification.mjs +17 -0
- package/scripts/verify-agent-note-format.mjs +79 -0
- package/scripts/verify-archived-agent-notes.mjs +126 -0
- package/template/.agents/agents/README.md +40 -0
- package/template/.agents/agents/_main.md +46 -0
- package/template/.agents/agents/_template.md +18 -0
- package/template/.agents/agents/architect.md +18 -0
- package/template/.agents/agents/archivist.md +18 -0
- package/template/.agents/agents/doc-writer.md +18 -0
- package/template/.agents/agents/implementer.md +18 -0
- package/template/.agents/agents/reviewer.md +18 -0
- package/template/.agents/agents/test-engineer.md +18 -0
- package/template/.agents/agents/ui-reviewer.md +18 -0
- package/template/.agents/notes/AGENTS.md +7 -0
- package/template/.agents/notes/README.md +123 -0
- package/template/.agents/notes/archived/AGENTS.md +7 -0
- package/template/.agents/notes/archived/architecture/.gitkeep +0 -0
- package/template/.agents/notes/archived/bug-fix/.gitkeep +0 -0
- package/template/.agents/notes/archived/feature/.gitkeep +0 -0
- package/template/.agents/notes/archived/manifest.json +4 -0
- package/template/.agents/notes/archived/process/.gitkeep +0 -0
- package/template/.agents/notes/archived/simplification/.gitkeep +0 -0
- package/template/.agents/notes/archived/testing/.gitkeep +0 -0
- package/template/.agents/notes/implemented/AGENTS.md +13 -0
- package/template/.agents/notes/implemented/architecture/.gitkeep +0 -0
- package/template/.agents/notes/implemented/bug-fix/.gitkeep +0 -0
- package/template/.agents/notes/implemented/feature/.gitkeep +0 -0
- package/template/.agents/notes/implemented/process/.gitkeep +0 -0
- package/template/.agents/notes/implemented/simplification/.gitkeep +0 -0
- package/template/.agents/notes/implemented/testing/.gitkeep +0 -0
- package/template/.agents/notes/proposed/architecture/.gitkeep +0 -0
- package/template/.agents/notes/proposed/bug-fix/.gitkeep +0 -0
- package/template/.agents/notes/proposed/feature/.gitkeep +0 -0
- package/template/.agents/notes/proposed/process/.gitkeep +0 -0
- package/template/.agents/notes/proposed/simplification/.gitkeep +0 -0
- package/template/.agents/notes/proposed/testing/.gitkeep +0 -0
- package/template/.agents/notes/rejected/architecture/.gitkeep +0 -0
- package/template/.agents/notes/rejected/bug-fix/.gitkeep +0 -0
- package/template/.agents/notes/rejected/feature/.gitkeep +0 -0
- package/template/.agents/notes/rejected/process/.gitkeep +0 -0
- package/template/.agents/notes/rejected/simplification/.gitkeep +0 -0
- package/template/.agents/notes/rejected/testing/.gitkeep +0 -0
- package/template/.agents/skills/agent-experience/SKILL.md +25 -0
- package/template/.agents/skills/archive-agent-notes/SKILL.md +68 -0
- package/template/.agents/skills/code-review/SKILL.md +40 -0
- package/template/.agents/skills/doc-writing/SKILL.md +48 -0
- package/template/.agents/skills/error-handling/SKILL.md +35 -0
- package/template/.agents/skills/find-simplifications/SKILL.md +43 -0
- package/template/.agents/skills/init-architecture/SKILL.md +41 -0
- package/template/.agents/skills/pr-description/SKILL.md +51 -0
- package/template/.agents/skills/pre-push-checks/SKILL.md +42 -0
- package/template/.agents/skills/prose-standard/SKILL.md +49 -0
- package/template/.agents/skills/ui-ux/SKILL.md +107 -0
- package/template/.agents/skills/ui-ux/references/alignment.md +24 -0
- package/template/.agents/skills/ui-ux/references/icons.md +54 -0
- package/template/.agents/skills/ui-ux/references/responsive.md +52 -0
- package/template/.agents/skills/ui-ux/references/spacing.md +17 -0
- package/template/docs/AGENTS.md +36 -0
- package/template/docs/architecture.md +33 -0
- package/template/docs/contracts.md +22 -0
- package/template/docs/design/README.md +7 -0
- package/template/docs/design.md +30 -0
- package/template/docs/glossary.md +11 -0
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# 决策记录(Agent Notes)
|
|
2
|
+
|
|
3
|
+
这里存放一类设计文档。**决策记录**记录影响本代码库的决策或提案——代码和普通文档承载不了的「为什么」和「放弃了什么」。本文档定义决策记录存放在哪里、何时写一篇,以及[文件内格式](#文件格式)。普通文档(README、架构、设计、术语等)的写作遵循[文档规范](../../docs/AGENTS.md)。
|
|
4
|
+
|
|
5
|
+
## 布局与命名
|
|
6
|
+
|
|
7
|
+
每篇决策记录有两个维度,都编码在它的**路径**里——`{生命周期}/{分类}/yyyy-mm-dd-主题.md`:
|
|
8
|
+
|
|
9
|
+
- **生命周期**(顶层目录)是决策记录的状态,记录会随状态变化在不同目录间移动:
|
|
10
|
+
- **`proposed/`** —— 实施前评审的提案;尚未实现(或只实现了一部分)。
|
|
11
|
+
- **`implemented/`** —— 已落地的决策。文件记录「决定了什么」和「否决了什么」,并**与实际交付保持一致**:当代码后来移动文件、重命名包、或改变某个键/默认值时,决策记录要在同一次改动里同步更新(只更新事实——路径、名称、结构——而非决策本身)。见 [implemented/AGENTS.md](implemented/AGENTS.md)。
|
|
12
|
+
- **`rejected/`** —— 提案被考虑后否决。仅当它的理由能阻止一个诱人的、有意义的错误时才保留;否则删除。
|
|
13
|
+
- **分类**(嵌套目录)是决策的*类型*——见下方[分类](#分类)。
|
|
14
|
+
|
|
15
|
+
文件名中的日期是该主题**首次提出**的日期(以 git 历史为准)。决策记录之间的交叉引用使用相对 markdown 链接(`[主题](../../implemented/architecture/2026-…-….md)`)——绝不使用裸文字或编号——这样它们在目录间移动后仍然有效(若仓库配置了 markdown 链接检查,也便于机械校验)。
|
|
16
|
+
|
|
17
|
+
活跃生命周期树就是工作清单:浏览它的生命周期/分类目录,或搜索仓库。不要添加集中的 `INDEX.md`:它会重复路径元数据,并让互不相关的记录改动在同一个生成文件上发生冲突。具有历史决策价值、但对未来几乎没有指导意义的已实施记录,移到下文描述的独立冻结 [`archived/`](archived/AGENTS.md) 树。
|
|
18
|
+
|
|
19
|
+
## 分类
|
|
20
|
+
|
|
21
|
+
每篇决策记录归属于 agent-notes-kit 包内 `agent-note-tree.mjs` 的封闭集合里的一个路径编码分类;分类门禁会拒绝其他目录。新增分类需要同时更新这个规范集合和本小节。
|
|
22
|
+
|
|
23
|
+
| 分类 | 覆盖内容 |
|
|
24
|
+
|---|---|
|
|
25
|
+
| `feature` | 新的面向用户或面向模型的能力。 |
|
|
26
|
+
| `bug-fix` | 修复缺陷,或补上事后复盘暴露出的缺口。 |
|
|
27
|
+
| `simplification` | 在不新增能力的前提下删除代码、行为或表面积。 |
|
|
28
|
+
| `architecture` | 关于**交付源码**的结构性决策——包之间如何关联、运行时词汇是什么。 |
|
|
29
|
+
| `process` | 围绕代码的**工具、策略或流程**——门禁、包管理器、vendor——而非运行时行为。 |
|
|
30
|
+
| `testing` | 测试基础设施与策略。 |
|
|
31
|
+
|
|
32
|
+
`architecture` / `process` 的分界线:**architecture** 关乎我们交付的源码;**process** 是围绕它的工具与流程。(`refactor` 被刻意排除——它与 `simplification` 重叠,后者「可观察行为是否变化?」的判别标准已经覆盖了它。)
|
|
33
|
+
|
|
34
|
+
架构类记录与 `docs/architecture.md`(架构现状总览)配套:前者回答「为什么」,后者回答「是什么」。
|
|
35
|
+
|
|
36
|
+
## 归档与删除
|
|
37
|
+
|
|
38
|
+
删除只描述小的 UI 调整或纯机械改动的已实施记录,并修复或移除指向它的入链。本地 bug 修复、性能改进、新能力、或实质性的行为决策,不因其实现很小就够格删除。其他已实施记录,只有在交付决策已完成、其理由不太可能指导未来工作、且该记录仍有历史决策价值时,才归档。当它的备选方案、所有权边界、负面保证、持久化或线上语义、安全规则、或重新引入条件仍然有用时,应保持活跃。绝不归档 proposed 记录:过时的提案应否决。仅在记录能阻止一个似是而非的错误时保留 rejected 记录;否则删除。使用经过校准的 [`archive-agent-notes`](../skills/archive-agent-notes/SKILL.md) 工作流,而不是字数、年龄或目标配额。
|
|
39
|
+
|
|
40
|
+
归档的路径编码为 `archived/{分类}/yyyy-mm-dd-主题.md`;`implemented` 被刻意省略,因为只有已实施记录才能进入归档。一次归档改动应:移动记录、保留 `状态:已实施`、在该状态正下方插入一行 `归档:YYYY-MM-DD`、并修复或删除入链。这是归档期间唯一允许的内容改动。现有的标题标点和空行布局不妨碍归档;连同正文一起保留。
|
|
41
|
+
|
|
42
|
+
一旦封存,每篇归档记录就永久冻结。不得编辑、重新格式化、更新、移动或删除它,也不得把它当作当前行为的权威。绝不检查或修复归档记录中的出链;活跃文档在有意引用历史时仍可链接到归档记录。`verify-archived-agent-notes`(agent-notes-kit 提供)强制封闭的分类树、归档元数据和只追加的冻结内容清单。[归档说明](archived/AGENTS.md) 规定归档流程。
|
|
43
|
+
|
|
44
|
+
## 何时写一篇
|
|
45
|
+
|
|
46
|
+
只应为「代码、测试和现有文档都解释不了的、持久的决策理由」在同一 PR 里新增或更新决策记录。面向未来实质性工作的提案放在 `proposed/`;已经做出的决策放在 `implemented/`。选择与决策匹配的分类目录(见[分类](#分类))。
|
|
47
|
+
|
|
48
|
+
更新已经拥有该决策的记录即可满足规则;不要创建重复记录。机械或本地改动(包括本地 UI 呈现与交互改动)可豁免。决策记录绝不被改写成*另一个决策*:用新记录取代它,并保持两篇交叉链接,除非旧记录后来按下面的规则被完全合并。编辑 `implemented/` 记录以跟踪其既有决策的现状位置是必须的,而非禁止;见 [implemented/AGENTS.md](implemented/AGENTS.md)。
|
|
49
|
+
|
|
50
|
+
完全被取代的已实施记录,可合并进当前拥有该决策的记录后删除。删除前,拥有者必须保留所有独有理由、备选方案、后果、必需验证和已命名的覆盖缺口,并在同一次改动里修复所有入链。部分取代不适用:保留两篇并交叉链接,更新仍为现状的所有事实。合并不得把旧文件改写成其反面,也不得只靠 git 历史作为理由的唯一副本。
|
|
51
|
+
|
|
52
|
+
只有在以下情况,功能新增记录才能合并进后来的移除记录:该功能已不在生产代码、配置、schema、持久化或线上格式、迁移、兼容行为中;没有任何现行文档把它呈现为可用;也没有测试把它当作受支持行为来演练。移除理由和验证「不存在」的测试可以保留。移除方应保留最初的动机、它为何不再证明该功能合理、完全移除之外的备选方案、放弃的能力、重新引入的条件、以及对完全缺失的验证。过时的实现清单和只验证已删除行为的测试,不是当前的验证证据。移除一种传输、默认值、实现或呈现方式属于部分取代,任何存续的持久化数据或兼容处理也是如此。
|
|
53
|
+
|
|
54
|
+
## 文件格式
|
|
55
|
+
|
|
56
|
+
每篇活跃决策记录遵循一种文件内格式,由 `npm run verify-agent-note-format`(agent-notes-kit 包内门禁)强制检查。归档记录以封存时的格式冻结,外加 `归档:` 行;格式门禁不扫描它们。
|
|
57
|
+
|
|
58
|
+
### 头部块
|
|
59
|
+
|
|
60
|
+
每篇决策记录的前三行严格是:
|
|
61
|
+
|
|
62
|
+
```markdown
|
|
63
|
+
# 决策记录:<标题>
|
|
64
|
+
|
|
65
|
+
状态:<状态>
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
后跟一个空行。`状态:` 的值是三种之一,且必须与文件所在的生命周期目录一致——门禁会交叉检查:
|
|
69
|
+
|
|
70
|
+
- `状态:提案`
|
|
71
|
+
- `状态:已实施`
|
|
72
|
+
- `状态:已否决 — <原因,一行>`
|
|
73
|
+
|
|
74
|
+
> 冒号兼容全角 `:` 与半角 `:`;`已否决` 后的分隔符兼容 `—`、`–` 或 `-`(左右空格可有可无)。头部 `# 决策记录:` 与归档 `归档:` 同样兼容两种冒号。
|
|
75
|
+
|
|
76
|
+
状态不带日期、不带括号说明:文件名持有首次提出日期,git 持有其余一切,「以修订形式采纳」的说明是正文内容(在陈述决策处陈述修订)。否决原因是唯一带内容的状态,因为被否决记录的结论正是读者想了解的事实。
|
|
77
|
+
|
|
78
|
+
### 正文骨架
|
|
79
|
+
|
|
80
|
+
每篇决策记录以 `## 问题` 开头——动机,写成即使脱离解决方案也能成立。之后的内容取决于生命周期;常规章节使用这些规范名称,除此之外,真正自定义的技术章节(包拓扑、线上契约、schema)在必需章节之间保持自由形式。
|
|
81
|
+
|
|
82
|
+
#### `proposed/`
|
|
83
|
+
|
|
84
|
+
```markdown
|
|
85
|
+
## 问题
|
|
86
|
+
## 提案
|
|
87
|
+
……自定义章节……
|
|
88
|
+
## 备选方案
|
|
89
|
+
## 验收标准
|
|
90
|
+
## 风险
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
`## 提案` 是预期变更,可以合理地使用将来时——计划、迁移步骤和开放问题在工作尚未实现时都属于这里。`## 验收标准` 说明什么可观察状态意味着完成。`## 风险` 既涵盖可能出错之处,也涵盖该变更明知放弃的东西。
|
|
94
|
+
|
|
95
|
+
#### `implemented/`
|
|
96
|
+
|
|
97
|
+
```markdown
|
|
98
|
+
## 问题
|
|
99
|
+
## 决策
|
|
100
|
+
……自定义章节……
|
|
101
|
+
## 备选方案
|
|
102
|
+
## 后果
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
`## 决策` 以现在时描述交付现实,整个文件按 [implemented/AGENTS.md](implemented/AGENTS.md) 与其保持一致。`## 后果` 记录这个权衡**付出**了什么、又**换来了**什么。提案期标题在这里属于规范用语,门禁会拒绝它们:`## 提案`、`## 计划`、`## 迁移计划` 和 `## 验收标准` 不得出现在已实施记录中。`## 测试`、`## 延后` 或 `## 相关` 章节在陈述现在时事实时是允许的。
|
|
106
|
+
|
|
107
|
+
#### `rejected/`
|
|
108
|
+
|
|
109
|
+
被否决的决策记录就是被冻结的提案:它保留提案期拥有的任何章节(包括 `## 验收标准` 或 `## 计划`),结论放在 `状态:` 行。只有头部块、`## 问题` 开头、`## 提案` 章节,以及下文的备选方案要求适用。
|
|
110
|
+
|
|
111
|
+
### 备选方案 —— 必填
|
|
112
|
+
|
|
113
|
+
每篇决策记录都带一个 `## 备选方案` 章节:每个真实备选方案及其失败原因,每个备选方案一个加粗引导的段落,或对每个有争议的备选方案一个 `### 为什么不选 <X>?` 子节。没有记录「击败了什么」的决策会招致重新争论——这正是决策记录要防止的失败。
|
|
114
|
+
|
|
115
|
+
备选方案是记录下来的,而非杜撰的。
|
|
116
|
+
|
|
117
|
+
### 生命周期之间的移动
|
|
118
|
+
|
|
119
|
+
在生命周期目录之间移动文件,意味着更新 `状态:` 行并在同一次改动里重新满足该目录的骨架——否则门禁会使这次移动失败。具体而言,`proposed/` → `implemented/` 要把 `## 提案` 改写成现在时的 `## 决策`,把 `## 验收标准` 和 `## 风险` 折叠进 `## 后果`(或用现在时的 `## 测试`/`## 验证` 章节记录现在如何钉住该行为),并放弃计划、改用实际交付——这是 [implemented/AGENTS.md](implemented/AGENTS.md) 所要求的、被机械化的改写。`proposed/` → `rejected/` 只需在 `状态:` 行加上原因并冻结文件。
|
|
120
|
+
|
|
121
|
+
### 语言
|
|
122
|
+
|
|
123
|
+
每篇记录一个文件、一种语言。**全部内容都用中文书写**:`# 决策记录:` 前缀、`状态:`/`归档:` 行、规范化的 `##` 章节名以及正文。机器校验的记号就是上面列出的中文形式,必须逐字一致;正文内容可自由组织。自由形式的章节标题可自行命名,但必需的规范章节必须保持上述确切的中文名称。
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
# AGENTS.md — 归档决策记录
|
|
2
|
+
|
|
3
|
+
分类目录下的归档决策记录是冻结的历史快照,不是当前权威。绝不编辑、重新格式化、修复、删除或移动已封存的产物;新决策和新事实用活跃决策记录或现行文档。
|
|
4
|
+
|
|
5
|
+
归档改动只能:把记录从 `implemented/{分类}/` 移到 `archived/{分类}/`、在 `状态:已实施` 正下方插入一行 `归档:YYYY-MM-DD`、并修复或删除入链。不得检查、验证或修复归档记录中的出链。
|
|
6
|
+
|
|
7
|
+
按 [`archive-agent-notes`](../../skills/archive-agent-notes/SKILL.md) 工作流操作,并用 `npm run verify-archived-agent-notes -- --write` 追加新产物哈希。常规校验器会拒绝已改动或缺失的封存产物、未知分类目录和无效的归档元数据。
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# AGENTS.md — 已实施决策记录
|
|
2
|
+
|
|
3
|
+
这些决策记录描述已交付的决策。遵循[决策记录格式](../README.md#文件格式);`verify-agent-note-format` 强制各生命周期的结构。
|
|
4
|
+
|
|
5
|
+
## 让已实施记录与实际交付保持一致
|
|
6
|
+
|
|
7
|
+
在同一次改动里,让路径、符号、默认值和机制保持现状。就地改写陈旧事实;不要追加变更历史。
|
|
8
|
+
|
|
9
|
+
当一篇已交付记录不太可能指导未来工作时,通过 [`archive-agent-notes`](../../skills/archive-agent-notes/SKILL.md) 归档它,而不是继续维护它。
|
|
10
|
+
|
|
11
|
+
### 这不是改写*决策*的许可
|
|
12
|
+
|
|
13
|
+
就地更新事实层面的实现。逆转决策或其理由需要一篇新的决策记录并交叉链接;完全被取代的旧记录只能通过[决策记录规则](../README.md)里的合并规则删除。
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: agent-experience
|
|
3
|
+
description: 写/改面向模型的工具定义(name/description/schema/系统提示)或设计技能、上下文加载、多步工作流时使用;让信息可发现、高效用上下文。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 工具与技能设计
|
|
7
|
+
|
|
8
|
+
让模型高效发现信息、省上下文,同时不因省上下文而引发更多搜索/重读/错误。
|
|
9
|
+
|
|
10
|
+
## 上下文经济
|
|
11
|
+
|
|
12
|
+
- **最小上下文起步**:先暴露目的、可用操作、约束;详细指令按需加载。
|
|
13
|
+
- **显式可发现**:每个被延迟的资源都要有清晰描述和可靠的取回方式。
|
|
14
|
+
- **关键约束可见**:权限、破坏性副作用、必需校验要出现在相关操作之前。
|
|
15
|
+
- **偏好有界输出**:返回简洁结果 + 标识/路径取细节;不整篇倾倒日志/文档。
|
|
16
|
+
- **利用局部性**:随操作结果带少量很可能需要的相邻上下文(如回帖带前几条消息);显式标注省略与截断,并提供取更多的方式。
|
|
17
|
+
- **评估总代价**:省上下文只有在不引发更多搜索、重复读、或错误时才有用。
|
|
18
|
+
|
|
19
|
+
## 工具定义
|
|
20
|
+
|
|
21
|
+
- **删明显约束**:省略模型能从调用结果学到的规则(如读不存在的文件会失败)。
|
|
22
|
+
- **描述行为,不描述实现**:说工具做什么、返回什么;省略内部机制、结果里能看到的标记、强制细节。
|
|
23
|
+
- **参数规则放参数上**:默认值、范围、配对、何时设置放在该参数的 description/schema;随配置变化的描述通常意味着变化部分属于某个参数。
|
|
24
|
+
- **每件事只说一次**:不在系统提示段重复工具定义、不在工具描述重复参数描述、不在一个工具重复另一个工具的规则。
|
|
25
|
+
- **量化改动**:工具定义改动前后对比首轮 prompt token。
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: archive-agent-notes
|
|
3
|
+
description: 在新增、审计、修剪、归档、恢复或评审决策记录时使用;检查每篇新记录是否有被取代的活跃记录,删除小 UI 与纯机械记录,按未来决策价值给其他已实施记录分类,删除不再阻止诱人谬误的已否决记录,并应用冻结的 archived/{分类} 与清单规则。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 归档决策记录
|
|
7
|
+
|
|
8
|
+
在不抹除仍能指导工作的历史的前提下,削减活跃决策语料。逐篇语义判断;字数和年龄只是发现线索,绝非归档标准。
|
|
9
|
+
|
|
10
|
+
## 阅读契约
|
|
11
|
+
|
|
12
|
+
分类前先读[决策记录规则](../../notes/README.md)、[归档说明](../../notes/archived/AGENTS.md)和[已实施记录说明](../../notes/implemented/AGENTS.md)。用当前代码、配置、包文档、更新的决策记录和入链来确定某条理由是否仍拥有或约束任何东西。
|
|
13
|
+
|
|
14
|
+
## 新增记录时做取代检查
|
|
15
|
+
|
|
16
|
+
起草前先应用[创建标准](../../notes/README.md#何时写一篇)。每篇新决策记录都会触发对覆盖同一决策、机制或被否决备选方案的活跃记录的限定审计。写新记录时就给每个完全或部分取代分类:在同一次改动里归档够格的已实施记录,保留并交叉链接部分取代或仍有独立价值的理由,否决过时提案,删除不再阻止似是而非错误的已否决记录。当新拥有者吸收了每一个独有论点时应用决策记录合并规则;不要把已知匹配推迟到以后的语料审计。
|
|
17
|
+
|
|
18
|
+
## 按未来价值分类
|
|
19
|
+
|
|
20
|
+
应用这些生命周期专属结论:
|
|
21
|
+
|
|
22
|
+
- **已实施——删除:** 删除只描述小 UI 调整或纯机械改动的记录,并修复或移除入链。本地 bug 修复、性能改进、新能力、以及实质性的行为或所有权决策,不因其已实施就够格删除。在做保留/归档分类之前先应用此标准。
|
|
23
|
+
- **已实施——保持活跃:** 当记录的理由、备选方案、负面保证、持久化/线上语义、所有权边界、安全规则或重新引入条件可能指导未来改动时,保留它。分类对象是决策,不是其实现机制:一次机械重命名或类型抽取仍可能记录持久的命名、兼容性或所有权规则。长度无关紧要。
|
|
24
|
+
- **已实施——归档:** 当实质性历史决策已完成、不太可能指导未来工作、但其历史理由仍值得保存时归档。不要归档符合直接删除标准的记录。
|
|
25
|
+
- **proposed——绝不归档:** 让活跃提案保持活跃;若不再值得推进,就用诚实的理由否决它,并满足否决生命周期格式。
|
|
26
|
+
- **已否决——仅作护栏保留:** 仅当失败的提案仍是一个诱人且有意义、且该记录解释了它为何失败时,才保留否决。
|
|
27
|
+
- **已否决——删除:** 当被否决的想法已过时、被取代、不再可信、或不太可能阻止重新争论时,删除该记录。修复或删除入链。
|
|
28
|
+
|
|
29
|
+
不要为了配额而归档。检查范围内的每一篇记录,用同一原则对同类分组归类,对临界情况用最佳判断,并把手头真正两难的决策记录下来。
|
|
30
|
+
|
|
31
|
+
## 校准示例
|
|
32
|
+
|
|
33
|
+
这些示例划定标准;字数说明大小不是标准。
|
|
34
|
+
|
|
35
|
+
删除此类已实施记录:
|
|
36
|
+
|
|
37
|
+
- 一篇 533 字的次要侧栏 UI 调整记录——已关闭、纯本地呈现;
|
|
38
|
+
- 一篇模块搬迁和导入重写已完成、行为不变的记录。
|
|
39
|
+
|
|
40
|
+
保留此类已实施记录:
|
|
41
|
+
|
|
42
|
+
- 一篇 248 字的事件溯源设计记录——基础性权威与持久化边界;
|
|
43
|
+
- 一篇 596 字的跨组件所有权规则;
|
|
44
|
+
- 一篇 628 字的持久化存储与身份策略;
|
|
45
|
+
- 一篇 400 字的门禁调度决策——临界,但仍指导调度与资源调优;
|
|
46
|
+
- 一篇 334 字的已放弃能力记录——在它陈述的协调性重新引入条件兑现前保留。
|
|
47
|
+
|
|
48
|
+
对于已否决记录:
|
|
49
|
+
|
|
50
|
+
- 保留一篇 426 字的包拆分否决,只要合并这些包的诱惑仍有意义;
|
|
51
|
+
- 删除一篇 972 字、前提已过时的否决;
|
|
52
|
+
- 删除一篇 362 字、后来的决策已解答该问题的否决。
|
|
53
|
+
|
|
54
|
+
## 归档一篇已实施记录
|
|
55
|
+
|
|
56
|
+
1. 把 `foo.md` 从 `implemented/<分类>/` 移到 `archived/<分类>/`;归档路径中刻意不含 `implemented`。
|
|
57
|
+
2. 不改动正文。只在 `状态:已实施` 正下方插入 `归档:YYYY-MM-DD`,使用归档当天日期。
|
|
58
|
+
3. 不要在记录内重新格式化、更新事实或修复链接。现有的标题标点和空行布局予以保留,并非归档的前提。
|
|
59
|
+
4. 搜索活跃文档中的入链。把它们重定向到当前权威;只有当历史快照是被有意引用时,才把入链改指向归档路径;否则删除。绝不验证或修复归档记录中的出链。
|
|
60
|
+
5. 运行 `npm run verify-archived-agent-notes -- --write`。其只追加模式先证明每条既有封存仍匹配,然后只添加新产物哈希。之后再跑常规校验器。
|
|
61
|
+
|
|
62
|
+
记录封存后,绝不编辑、移动、重新格式化或删除它。归档记录仍是有效的入链目标,但只是历史快照,不是当前行为的权威。
|
|
63
|
+
|
|
64
|
+
## 校验与报告
|
|
65
|
+
|
|
66
|
+
运行 `npm run verify-agent-note-classification`、`npm run verify-agent-note-format`、`npm run verify-archived-agent-notes`、`git diff --check`,以及仓库在推送前要求的任何检查。
|
|
67
|
+
|
|
68
|
+
报告保留的活跃已实施记录、删除或归档的已实施记录、保留/删除的已否决记录、被否决的提案(若有),以及每个真正两难的临界案例及其字数和所选结论。不要声称归档出链有效:归档校验器有意从不检查它们。
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: code-review
|
|
3
|
+
description: 评审 PR 时使用;先读项目规则/文档/决策记录再判断 diff,按正确性、安全、生命周期、风格排序,报告缺陷与证据。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 代码评审
|
|
7
|
+
|
|
8
|
+
**这是指导,不是完整清单。** 先确认 diff 的真实 base 与 head,读改动涉及的契约与规则,再对照 diff 评审;凭记忆评审规则正是漏检的根源。
|
|
9
|
+
|
|
10
|
+
## 评审顺序
|
|
11
|
+
|
|
12
|
+
正确性 > 安全 > 生命周期/并发 > 破坏必需行为 > 风格。一条有证据的 blocker 胜过一堆 nit。
|
|
13
|
+
|
|
14
|
+
## 先读的契约
|
|
15
|
+
|
|
16
|
+
- 根 `AGENTS.md` 与相关子树的 `AGENTS.md`:常驻规则
|
|
17
|
+
- `docs/`(架构/设计/契约):改动必须满足的结构与行为
|
|
18
|
+
- `.agents/notes/implemented/`:决策理由;与决策记录不一致时当作设计讨论,不自动否决
|
|
19
|
+
- 相关技能(error-handling、ui-ux 等)
|
|
20
|
+
|
|
21
|
+
## 阻断项
|
|
22
|
+
|
|
23
|
+
1. **新文案要语义评审**:每条新增/改动的 Markdown、JSDoc、注释、提示、诊断、可见字符串都过 prose-standard;自动检查不能证明覆盖/准确/位置正确。
|
|
24
|
+
2. **文档与代码一致**:配置、默认值、错误、字段、事件、公开行为要在同一 diff 里更新文档与 JSDoc。
|
|
25
|
+
3. **错误处理**:改动涉及的失败路径要有明确 owner、状态保证与可操作报错;拒绝 catch-and-continue(除非状态 owner 证明后续前置仍成立)。
|
|
26
|
+
4. **生命周期与并发**:异步初始化/回调/进程/清理要有竞态检查、取消处理、独立报错、完整 detach 清理。
|
|
27
|
+
5. **范围与必要性**:每个新字段/适配器/状态机/选项都要有背后的必需行为;区分「删除概念」与「搬迁声明」;挑战无关功能与投机泛化。
|
|
28
|
+
6. **测试强度**:断言要在目标回归上失败、验证外部状态/日志/事件/清理,而不是复述实现。
|
|
29
|
+
|
|
30
|
+
## 手工检查
|
|
31
|
+
|
|
32
|
+
- 追踪每个改动接口的两侧;确认实现与 PR/决策记录一致,含错误、取消、所有权、清理。
|
|
33
|
+
- 追踪拒绝路径到实际执行它的操作;找能绕过 schema/提示/facade 的调用者。
|
|
34
|
+
- 测试走真实入口,不是手工挂载的桩。
|
|
35
|
+
- 负向对照:每个改动的验收规则都要有一个故意非法用例在真实 runner 上失败。
|
|
36
|
+
- implemented 决策记录要与交付现实一致。
|
|
37
|
+
|
|
38
|
+
## 报告
|
|
39
|
+
|
|
40
|
+
写清缺陷、位置、影响、证据。局部缺陷放最贴近的 diff 行;跨模块的架构/范围问题放 PR 级评论。区分 blocker 与建议,略过已被门禁拦住的项。
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: doc-writing
|
|
3
|
+
description: 新建、重构、评审、审计文档或包 README 时使用;受众优先的分层、一个事实一个家、事实核对、可控技术语言。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 文档写作
|
|
7
|
+
|
|
8
|
+
让每页可搜索、新读者可读、对 agent 与维护者足够精确。先应用根/子树 `AGENTS.md` 与门禁,再按本流程:分层、事实核对、审计。
|
|
9
|
+
|
|
10
|
+
> 归属:本技能管文档结构与事实核对;句子级契约与删冗余见 [prose-standard](../prose-standard/SKILL.md),常驻文档规则见 [docs/AGENTS.md](../../../docs/AGENTS.md)。
|
|
11
|
+
|
|
12
|
+
## 流程
|
|
13
|
+
|
|
14
|
+
1. 读根与更具体的 `AGENTS.md`、文档规范、目标页、其源码/测试。
|
|
15
|
+
2. 给页面定一个主要职责与读者(快速上手 / 任务指南 / 教程 / 架构总览 / 包参考 / 生成参考 / 决策记录)。
|
|
16
|
+
3. 放在最近的 owner:包契约随包代码,`docs/` 放跨包内容。
|
|
17
|
+
4. 写前定义读者起点、可观察结果、可能的失败、恢复路径、下一步深度。
|
|
18
|
+
5. 先 Summary → 目录 → 用户向内容 → 开发者向内容,按文档类型允许的顺序。
|
|
19
|
+
6. 用「事实核对」验证每句断言。
|
|
20
|
+
7. 跑相关检查 + `git diff --check`,重读 diff 先看正确再看简洁。
|
|
21
|
+
|
|
22
|
+
## 事实核对:跑,别假设
|
|
23
|
+
|
|
24
|
+
文档描述的是今天的行为;操作声明的唯一可接受证据是「真的跑过」。
|
|
25
|
+
|
|
26
|
+
1. 先按事实读(package.json / 入口文件),别按文件夹名分类。
|
|
27
|
+
2. 每个声称的命令/配置/默认值/错误都在当前 checkout 上跑一遍,只写观察到的。
|
|
28
|
+
3. 复现不了的删掉——从不从记忆、类比或隔壁包抄。
|
|
29
|
+
4. 改旧页前先对最新主分支,陈旧声明照样是错的,按代码纠正。
|
|
30
|
+
5. 每次编辑后重新核对受影响的断言。
|
|
31
|
+
|
|
32
|
+
## Voice 规则
|
|
33
|
+
|
|
34
|
+
- **Summary 说它做什么**(用户能做什么、收益、何时选、主要代价),不是说它是什么/内部身份。
|
|
35
|
+
- **开发者段解释,不枚举**:讲设计思路与数据流,链代码取细节,不堆 API 目录。
|
|
36
|
+
- **只写现状**:普通文档写当前代码,历史只进决策记录/复盘等专门位置。
|
|
37
|
+
- **可控技术语言**:每句一个显式施动者 + 一个主要动作;一词一概念;保留情态与例外。
|
|
38
|
+
|
|
39
|
+
## 质量标准(评审用)
|
|
40
|
+
|
|
41
|
+
- **Brief**:常用路径只含达成结果所需的事实,穷尽真理在一层链接外。
|
|
42
|
+
- **Intuitive**:前置先于依赖概念,下一步明显,标题用读者会搜的词。
|
|
43
|
+
- **Friendly**:读者能识别成功、行动前懂风险、能从可能失败恢复。
|
|
44
|
+
- **Accurate**:每个持久断言有一个 owner 和与风险相称的验证路径。
|
|
45
|
+
- **Agent-readable**:元数据、稳定标题、锚点、术语、所有权、状态支持定向检索。
|
|
46
|
+
- **Newcomer-complete**:无上下文的新工程师能靠 3–5 页链接重建相关架构/特性。
|
|
47
|
+
|
|
48
|
+
对穷尽式参考不套通用字数上限;测入口路径长度、一次查找要扫的不相关材料、最大段、标题数、页面大小。
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: error-handling
|
|
3
|
+
description: 设计或评审失败、错误类与码、工具失败、恢复、重试、后台任务、用户可见报错时使用。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 错误处理
|
|
7
|
+
|
|
8
|
+
定义失败、它的 owner,以及失败后什么仍然安全。
|
|
9
|
+
|
|
10
|
+
## 类型化、结构化失败
|
|
11
|
+
|
|
12
|
+
- 预期失败要有声明的类型、稳定判别码、处理所需细节;机器身份与显示文案分离;绝不靠 parse 消息路由。
|
|
13
|
+
- 复用项目错误基类(一个领域/包一个类优于每个失败一个类);`name` 是类名,`code` 是稳定的 `UPPER_SNAKE_CASE`,按域加前缀。code 命名的是消费方要处理的失败类别,不是调用点。
|
|
14
|
+
- 转换外部失败:在拥有该依赖的边界把 errno/协议/跨 realm 错误转成项目错误,原错误作 `cause`;跨层不丢 `name`/`code`,进程/worker 边界显式传输并重建。
|
|
15
|
+
|
|
16
|
+
## 捕获、恢复或停止
|
|
17
|
+
|
|
18
|
+
每个失败都要定义处理与上报 owner、遏制、状态保证:合法不变量、缺失/部分/已提交/未知效果、清理责任。后台任务同样。
|
|
19
|
+
|
|
20
|
+
捕获只限制异常传播,不限制副作用;只有状态 owner 能决定「能安全继续」。否则停掉依赖工作、丢弃无效状态、或升级上报。光 log 不是恢复。重试需要可安全重复、可取消、有明确 owner。
|
|
21
|
+
|
|
22
|
+
### 空 catch 规则
|
|
23
|
+
|
|
24
|
+
空 `catch` 只吞掉 try 里的所有失败。仅当这些失败都不破坏 owner 状态、且没有调用方能据此行动时才用(例如删一个没人读的临时文件失败)。
|
|
25
|
+
|
|
26
|
+
- **try 只放一条语句**(一个语法语句,不是一行)。
|
|
27
|
+
- **绑定命名失败**:`catch (_cleanupFailed)`,不是 `catch {}`。
|
|
28
|
+
- **注释说明为何安全**:放在 catch 块内或闭括号同行;`// ignore` 不说明任何东西。
|
|
29
|
+
- **只接受部分失败要测试**:非空 catch 里测 `code`/`name` 并 rethrow 其余。
|
|
30
|
+
|
|
31
|
+
## 本地化、可操作、可见报错
|
|
32
|
+
|
|
33
|
+
最终报错要有:可读摘要、受影响操作、安全下一步。敏感内部细节不进用户可见文案。不可信状态/未知结果要通过 UI 或默认开启的可访问日志可见:报影响、不确定性、系统处置、安全下一步。没有保证就别声称成功/回滚/可重试。
|
|
34
|
+
|
|
35
|
+
验证最终状态与可见结果,而不是「异常被捕获了」。
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: find-simplifications
|
|
3
|
+
description: 找证据支撑的简化(代码/API/配置/测试/文案)时使用;删死代码、重复、投机、不必要维护的行为与基础设施,或评估来自别的分支的简化。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 找简化
|
|
7
|
+
|
|
8
|
+
找能「删掉维护义务」的改动:API、表示、生命周期状态、配置路径、依赖、测试、文档。宁要几个有充分支撑的候选,不要一堆删减计数。这是指导不是清单;区分「调查」与「授权实施其提案」。
|
|
9
|
+
|
|
10
|
+
## 建立范围与约束
|
|
11
|
+
|
|
12
|
+
先读根 `AGENTS.md`、架构文档、防御模式、测试策略,再判断;查相关活跃决策记录确认是否故意。归档记录是历史例子,不是现状权威。
|
|
13
|
+
|
|
14
|
+
## 找可删的维护义务(用这些问题引导)
|
|
15
|
+
|
|
16
|
+
- **声明过的特性有完整效果路径吗?** 追 producer → 变换 → provider/端点支持 → 可观察结果。到处复制的字段可能没有 setter、没有 reader、或实现都拒绝它。CLI/配置透传要追权威读取与优先级,找被遮蔽的转发值。
|
|
17
|
+
- **哪些区分改变了消费方的动作?** 先问这个区分/字段/适配器到底需不需要。追源字段与判别符经过发射器与鉴权/能力检查,再加传输特定标记。保留必需的鉴权、驻留、持久化、所有权;删只会招来不可用选择的公开区分。
|
|
18
|
+
- **更小的显式行为能否删掉子系统?** 固定间隔、调用方给的时区、或显式激活失败,能消除泛化日历、持久化默认、自动回滚。说出放弃的能力与删掉的机制。
|
|
19
|
+
- **消费方能否在需要时读到权威值?** 找复制历史、提升账本、失效事件、共享投影流旁的特性缓存。派生/复用能一起删掉订阅、保留数据、陈旧响应处理、恢复路径。
|
|
20
|
+
- **组合被误当成策略?** 可选服务存在、provider 方法、兄弟工具能表达可用性,不必决定部署行为;显式配置或调用方意图操作能删注册表与依赖检查。
|
|
21
|
+
- **谁承担完整维护成本?** 追重复的应用树、产品在用的 demo 启动器、自带升级生命周期的安装助手。比较「被删的整套系统」与「替代品」,含残留胶水;把无必要概念挪近 owner、或加门禁保持重复定义相等,都不减少维护成本。
|
|
22
|
+
|
|
23
|
+
## 证明可达性与权衡
|
|
24
|
+
|
|
25
|
+
先用 `rg` 再读匹配。搜精确符号、属性读写、判别符、事件与线上字符串、配置键、包名、两种方法调用形式。测试与声明能证明契约,但不证明有已发布的生产者/消费者。
|
|
26
|
+
|
|
27
|
+
对每个候选记录:当前 owner、有效生产者/消费者路径、什么消失、什么保留、能力与兼容影响、保留它的最强理由。区分:删不可达/不读行为;收窄公开行为(有明确损失);受保护义务或证据不足。候选破坏保留义务、只是搬迁同样复杂度、或没有实质减少就拒绝。
|
|
28
|
+
|
|
29
|
+
## 保留所有权与失败语义
|
|
30
|
+
|
|
31
|
+
对复制/冻结/校验/回调捕获:命名值的来源、下一 owner、信任边界。类型化同进程调用通常借用只读值;解析器/配置加载器/队列/模型工具 JSON/持久化文件/worker/进程/线上解码器拥有或校验输入。
|
|
32
|
+
|
|
33
|
+
对异步机制:把每个 promise/标志/取消路径/disposer/预留映射到 owner 与转换;只有表达同一事实才合并机制。保留同步发布与回滚、回调遏制、首个终结结果仲裁、worker/进程所有权、dispose 到静止。
|
|
34
|
+
|
|
35
|
+
## 只为净减少替换基础设施
|
|
36
|
+
|
|
37
|
+
先搜现有依赖与引擎下限的内置,再考虑加包。指出替代品删掉的确切实现与专属测试、维护与传递成本、胶水必须保留的每个残留行为。演练最可能击败替代品的不匹配:协议截断、取消与 teardown、配置边界、确定性测试时钟、平台打包、源码 vs 构建入口。
|
|
38
|
+
|
|
39
|
+
## 记录、合并、校验
|
|
40
|
+
|
|
41
|
+
文案在范围内时用 prose-standard。随所属改动更新 README/JSDoc/模型可见目录/配置/快照/生成文件。
|
|
42
|
+
|
|
43
|
+
实质性提案用提案骨架(问题/提案/备选/验收/风险),含消费者证据、删掉的维护成本、放弃的能力、可观察验收条件。已实施决策用 implemented 格式。同一决策更新现有 owner,别建重复记录。新记录触发取代检查,用归档技能。最后跑相关检查并汇报:调查过的区域、有支撑的候选、有意义的拒绝/推迟、记录的新增/合并/保留/删除、实际跑的命令。
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: init-architecture
|
|
3
|
+
description: 为新项目或现有项目初始化架构文档时使用;扫描代码库结构与依赖,生成 docs/architecture.md 的仓库布局、分层、运行时词汇、模块与依赖、扩展点、边界与不变量、关键决策索引七个小节,并把已定型的结构性决策写入决策记录。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 初始化项目架构
|
|
7
|
+
|
|
8
|
+
把 [docs/architecture.md](../../../docs/architecture.md) 从空白模板变成如实反映当前代码的初稿。产出的是「现状是什么」,不是凭空设计。
|
|
9
|
+
|
|
10
|
+
## 第一步:摸清现状
|
|
11
|
+
|
|
12
|
+
只记录能从代码里验证的事实,读这些来源:
|
|
13
|
+
|
|
14
|
+
- 顶层目录结构与模块/包布局(目录树、包管理器清单:package.json / pyproject.toml / go.mod / Cargo.toml…)
|
|
15
|
+
- 现有 README、根 AGENTS.md / CLAUDE.md(若已有约定)
|
|
16
|
+
- import / 依赖方向:谁依赖谁、依赖声明里的内部依赖关系
|
|
17
|
+
- 反复出现的核心概念:类型名、术语、配置键、领域实体
|
|
18
|
+
|
|
19
|
+
## 第二步:逐节填充 docs/architecture.md
|
|
20
|
+
|
|
21
|
+
| 小节 | 从哪来 | 填什么 |
|
|
22
|
+
|---|---|---|
|
|
23
|
+
| 仓库布局 | 目录树 | 一句话一个模块/目录的职责 |
|
|
24
|
+
| 分层 | import 方向、目录命名 | 各层职责与依赖方向(上层可依赖下层、反之禁止等) |
|
|
25
|
+
| 运行时词汇 | 反复出现的类型/术语 | 核心概念的准确定义,消除同名异义 |
|
|
26
|
+
| 模块与依赖 | 依赖声明、import | 主要模块及依赖关系、边界与禁止方向 |
|
|
27
|
+
| 扩展点 | 接口/插件/配置钩子/注册机制 | 哪里可扩展、如何扩展、谁负责注册 |
|
|
28
|
+
| 边界与不变量 | 校验、错误处理、断言 | 硬边界、不可破坏的不变量、失败如何体现 |
|
|
29
|
+
| 关键决策索引 | 见第三步 | 链接到 `.agents/notes/` 里对应的决策记录 |
|
|
30
|
+
|
|
31
|
+
## 第三步:结构性决策落记录
|
|
32
|
+
|
|
33
|
+
分析中若发现「已经定型、且非显而易见」的结构性决策(为什么这么分层、为什么选这个库/范式、为什么这个边界这样划),在 [`.agents/notes/implemented/architecture/`](../../notes/implemented/architecture/) 写一篇决策记录(格式见[决策记录规则](../../notes/README.md)),并把链接加进「关键决策索引」。
|
|
34
|
+
|
|
35
|
+
## 约束
|
|
36
|
+
|
|
37
|
+
- **只陈述可验证的事实**,不臆造、不替项目做未发生的设计决定。
|
|
38
|
+
- **不确定的地方写 `TODO`**,不要编造。
|
|
39
|
+
- 全中文书写。
|
|
40
|
+
- 一句话写清职责,避免空话和重复。
|
|
41
|
+
- 完成后提示用户审阅「关键决策索引」和每个 `TODO`。
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: pr-description
|
|
3
|
+
description: 创建 PR 或更新 PR 描述时使用;定义各段结构、Issue 引用、测试设计与 AI 参与度声明。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# PR 描述
|
|
7
|
+
|
|
8
|
+
## 结构
|
|
9
|
+
|
|
10
|
+
四个二级标题,固定顺序:`## Motivation`、`## Changes`、`## Testing`、`## AI Usage`。
|
|
11
|
+
|
|
12
|
+
### Motivation
|
|
13
|
+
- 一句话说问题。
|
|
14
|
+
- 至少引用一个 issue:解决用 `Fixes/Closes/Resolves #N`,仅提供上下文用 `Refs #N`。
|
|
15
|
+
|
|
16
|
+
### Changes
|
|
17
|
+
- **接口变化**:命令/参数/配置键/环境变量/公开导出/持久化格式的改动;没有写 None。
|
|
18
|
+
- **行为变化**:用户/模型/开发者可观察到的结果变化(含默认值、性能、时序、输出);没有写 None。
|
|
19
|
+
- 只写 diff 保证、且测试覆盖的行为。
|
|
20
|
+
|
|
21
|
+
### Testing
|
|
22
|
+
先测试设计,再测试条目。
|
|
23
|
+
|
|
24
|
+
**测试设计**(按改动类型选形式):
|
|
25
|
+
|
|
26
|
+
| 改动类型 | 测试设计要展示 |
|
|
27
|
+
|---|---|
|
|
28
|
+
| 行为变化 | 场景 × 前后行为 × 覆盖测试的矩阵 |
|
|
29
|
+
| 性能变化 | 每阶段前后数值 + 测量条件 |
|
|
30
|
+
| 无行为变化的 refactor/迁移 | 如何证明行为不变(逐字节对比/快照不变/新旧对比) |
|
|
31
|
+
| 仅文档 | 如何校验(链接/示例可编译等) |
|
|
32
|
+
|
|
33
|
+
**测试条目**:每条一个测试方法,写清命令/步骤与覆盖的行为;只列已跑且有结果的;证据放 `<details><summary>Proof</summary>`。
|
|
34
|
+
|
|
35
|
+
### AI Usage
|
|
36
|
+
|
|
37
|
+
记录 AI 在各阶段的参与度与谁做决定。分级(从少到多):
|
|
38
|
+
|
|
39
|
+
| 级别 | 含义 | AI 参与度 |
|
|
40
|
+
|---|---|---|
|
|
41
|
+
| hint 人工独立 | 人做,AI 只给被动建议 | 0–10% |
|
|
42
|
+
| assist 人工主导 | 人供主要内容/关键决策,AI 补部分 | 15–25% |
|
|
43
|
+
| pair 人工引导 | 人给关键方向/约束并多次修订 | 30–50% |
|
|
44
|
+
| copilot 人工把关 | AI 完成,人评审选择 | 55–85% |
|
|
45
|
+
| auto 模型自主 | AI 自主完成,人只设目标 | 90–100% |
|
|
46
|
+
|
|
47
|
+
按固定阶段记录:breakdown 问题拆解、design 方案设计、testing 验收测试、implementation 技术实现、review 评审处理。依据会话记录与任务记录打分,不按代码量/时间/token。
|
|
48
|
+
|
|
49
|
+
## 更新时机
|
|
50
|
+
|
|
51
|
+
建 PR 时写全;PR 存在后描述与代码不符时更新受影响段;堆叠 PR 每层各写自己的描述。
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: pre-push-checks
|
|
3
|
+
description: 推送、force-push、标 ready、或声称检查通过前使用;选能覆盖即将推送 diff 的最小测试/检查,不无脑跑全量。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 提交前检查
|
|
7
|
+
|
|
8
|
+
在 push 前跑一次相关本地证据。唯一例外是「发布后才发现重写」的情况(如堆叠 PR 级联 rebase),之后立刻补验,证据通过前不合并。CI 拥有全量覆盖;本地只跑 diff 能影响的最小集合。
|
|
9
|
+
|
|
10
|
+
## 检查改动范围
|
|
11
|
+
|
|
12
|
+
1. 确认分支与 checkout(`git status --short --branch`)。
|
|
13
|
+
2. 确认真实 base,按它看完整范围(不要猜 base)。
|
|
14
|
+
|
|
15
|
+
## 按 diff 选证据
|
|
16
|
+
|
|
17
|
+
没有统一基线。每个行为改动选「它回归时必然失败的最窄测试/检查」:
|
|
18
|
+
|
|
19
|
+
- **代码行为**:跑拥有该行为的测试文件/用例;共享契约变了再加相邻包测试。
|
|
20
|
+
- **文档/决策记录**:跑文档门禁。
|
|
21
|
+
- **用户可见 UI**:走 ui-ux 的改动分级与最低检查。
|
|
22
|
+
- **可见输出**(模型/编辑器/CLI/终端):跑拥有该输出的快照或真实用例。
|
|
23
|
+
- **包清单/公开导出/构建**:跑构建 + 相关 smoke。
|
|
24
|
+
- **真实 provider/agent 行为**:跑相关 e2e(有凭据时),绝不打印密钥。
|
|
25
|
+
|
|
26
|
+
不要因为「要 commit/push」就重跑一个已经通过的检查。
|
|
27
|
+
|
|
28
|
+
## 保护历史重写 push
|
|
29
|
+
|
|
30
|
+
rebase 允许;独立分支重写前先 fetch 当前远程 ref 并记录 OID,用 `--force-with-lease=<branch>:<oid>` 发布。裸 `--force` 禁用。重写后重新 fetch 头,重审未决评审、审批、可合并性与检查——重写前的哈希/行内评论锚点不是当前证据。
|
|
31
|
+
|
|
32
|
+
## 处理失败
|
|
33
|
+
|
|
34
|
+
相关检查失败就停,修或解释 blocker,别 push 赌 CI 不一样。疑似环境特定的失败要证明:记录命令/失败/平台差异,确认非平台证据,优先修跨平台不确定性。
|
|
35
|
+
|
|
36
|
+
## Push 流程
|
|
37
|
+
|
|
38
|
+
1. 跑一次选中的检查。
|
|
39
|
+
2. 正常 commit,检查 pre-commit 修复器改动的文件。
|
|
40
|
+
3. push。
|
|
41
|
+
4. 验证远程 ref == 本地 HEAD。
|
|
42
|
+
5. GitHub PR 用 `gh pr checks` 看远程 CI,pending 报 pending。
|