docs: 共有技能收归 meta 单一份并加工作区级笔记校验入口
- write-notes-like-deepseek 从三个子仓库的重复副本改为 meta 唯一副本 - 新增 .agents/scripts/verify-notes.ts,从 meta 视角一次校验四个笔记根 - workspace-layout 补「共有技能单一来源」的落位与理由 - .rgignore 排除 archived 历史快照
This commit is contained in:
@@ -0,0 +1,69 @@
|
||||
# 按需阅读:Note 文件格式
|
||||
|
||||
> SKILL §2 的展开。写/改 Note 时对照;只改代码不动 Note 时跳过。
|
||||
|
||||
## 头块(前三行,检查脚本会核对)
|
||||
|
||||
```markdown
|
||||
# Agent Note: <标题>
|
||||
|
||||
Status: <状态>
|
||||
```
|
||||
|
||||
- `proposed` → `Status: proposed`
|
||||
- `implemented` → `Status: implemented`
|
||||
- `rejected` → `Status: rejected — <一句话原因>`
|
||||
|
||||
标题前必须带 `Agent Note: ` 前缀,标题本身用简体中文;状态不含日期与括号;必须与所在 lifecycle 文件夹一致(脚本会交叉核对)。文件名日期是首次提出日,git 承载其余时间信息。
|
||||
|
||||
## Body 骨架
|
||||
|
||||
每篇 Note 都以 `## Problem` 开头——动机要能脱离方案独立成立。之后按 lifecycle区分:
|
||||
|
||||
**`proposed/`**
|
||||
|
||||
```markdown
|
||||
## Problem
|
||||
## Proposal
|
||||
…自由节…
|
||||
## Alternatives considered
|
||||
## Acceptance criteria
|
||||
## Risks
|
||||
```
|
||||
|
||||
`Proposal` 可用将来时;`Acceptance criteria` 说清什么可观察状态算完成;`Risks` 同时写风险与已知取舍。
|
||||
|
||||
**`implemented/`**
|
||||
|
||||
```markdown
|
||||
## Problem
|
||||
## Decision
|
||||
…自由节…
|
||||
## Alternatives considered
|
||||
## Consequences
|
||||
```
|
||||
|
||||
`Decision` 用现在时描述已落地事实;门禁只拒提案标题(`## Proposal` / `## Plan` / `## Migration plan` / `## Acceptance criteria` 及其中文别名);用 `## Consequences` 同时记录代价与收益;可按需加 `## Testing` / `## Verification` 等现在时事实节。现在时靠人写,不靠词法扫描。
|
||||
|
||||
**`rejected/`**
|
||||
|
||||
冻结的 proposal 形态,verdict 在 `Status:` 行;保留提案时的 `Alternatives` 等节,不改写为对立面。
|
||||
|
||||
## Alternatives considered(必写)
|
||||
|
||||
每篇 Note 必含 `## Alternatives considered`:每个**真考虑过**的备选为何没选,一段一备选(可用 `### Why not <X>?` 子节)。没有过的选项不要编。「不做 / 复用现状」仅当当时真的权衡过才写。脚本只检查这一节在不在。
|
||||
|
||||
## 时态与禁止改写
|
||||
|
||||
- `proposed` 可用将来时;`implemented` 一律现在时,描述已落地事实。
|
||||
- 一条 Note 永远不被改写成另一个决定;被取代用新 Note 接管,旧 Note 按归档/合并规则处理。
|
||||
|
||||
头块标题兼容全角冒号(`# Agent Note:标题`,中文输入法常打出全角);新笔记建议半角。
|
||||
|
||||
## 自由节与文风
|
||||
|
||||
- 自由节(package 拓扑、wire 契约、schema 等)放在 `Decision` 与 `Alternatives` 之间。
|
||||
- 保留可检索的机制名与 `must`/`may`/`never` 时序强调;一个事实只在一处讲透,其余链过去。
|
||||
- 跨 Note 引用用相对 Markdown 链接 `[topic](../../implemented/architecture/2026-…-….md)`,不要裸数字。
|
||||
|
||||
格式与别名表对齐 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的 notes 规范;本项目为中文单语:标题、节标题与正文用简体中文,头块 `Agent Note:` 与 `Status:` 保持英文原文以便脚本核对。
|
||||
Reference in New Issue
Block a user