Skip to content

Commit a529084

Browse files
AparenciaAparencia
committed
docs: 新增 docs-starter-kit 新项目文档骨架与全仓优化计划
1 parent faeeb17 commit a529084

49 files changed

Lines changed: 7623 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs-starter-kit/.docscheckignore‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# docs-check.mjs 豁免清单
2+
# 每行一个 glob 模式（匹配相对 docs/ 的路径），命中文件跳过链接/索引/命名检查。
3+
# 用途：历史快照文档保留原貌（见 versions/README.md"历史文档链接说明"），不纳入门禁。
4+
# 注意：豁免是例外而非常态，新文档一律不得加入此清单。
5+
6+
# 示例：历史版本文档（docs 重组前撰写，内部链接指向已删除目录，保留原貌）
7+
# versions/v0.1.0.md
8+
# versions/v0.2.0/**

‎docs-starter-kit/Foresight/README.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# 前瞻构想（Foresight）
2+
3+
> 未排期的战略构想、设计文档与头脑风暴。**已立项内容移入 `product/` 或 `versions/` 跟踪**。
4+
5+
## 使用规则
6+
7+
- 状态标注：每篇文档头部必须标注 `**状态**: 前瞻构想（未排期）` 或具体状态（已立项/已实现/已归档）
8+
- 头脑风暴产物用 [brainstorm-template.md](../templates/brainstorm-template.md)
9+
- 竞品/调研分析用 [third-party-eval-template.md](../templates/third-party-eval-template.md)
10+
- 落地完成后：文档移入 `archive/YYYY-MM-DD/` 快照，索引标 `[ ] 已归档`
11+
12+
## 建议文件
13+
14+
| 文档 | 何时需要 |
15+
|------|---------|
16+
| roadmap.md | 有阶段性路线图时 |
17+
| brainstorming-*.md | 功能创意发散时 |
18+
| competitive-analysis.md | 竞品调研时 |
19+
20+
## 维护规则
21+
22+
- 每篇 Foresight 文档在 docs/README.md 总导航中登记
23+
- 定期（如每季度）清理：已实施 → 归档；长期未排期 → 保留但标注日期

‎docs-starter-kit/README.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Docs Starter Kit — 可直接投入新项目的文档骨架
2+
3+
> 从熵减（Entropydecrease）项目文档体系提炼的**通用化**文档模板树：工程化（索引驱动 / 模板驱动 / ADR / 版本沉淀 / 归档机制 / 自动化检查）与个人开发化（轻量 / 低维护 / 按需裁剪）的平衡产物。
4+
> 本目录**不含任何项目特有内容**（品牌名、具体功能、历史文档），复制即用。
5+
6+
---
7+
8+
## 🚀 快速启用（5 分钟）
9+
10+
```bash
11+
# 1. 复制骨架到你的项目
12+
cp -r docs-starter-kit/* <你的项目>/docs/
13+
cp docs-starter-kit/.docscheckignore <你的项目>/docs/
14+
15+
# 2. 复制文档检查脚本（可选，推荐）
16+
cp docs-starter-kit/scripts/docs-check.mjs <你的项目>/scripts/
17+
18+
# 3. 初始化
19+
# - 编辑 docs/README.md 顶部：项目名 + 一句话描述
20+
# - 建立 git 后把 docs/ 提交入库
21+
```
22+
23+
**初始化 Checklist**（复制后逐项完成）：
24+
25+
- [ ] `docs/README.md`：填入项目名、简介、技术栈
26+
- [ ] `docs/standards/README.md`：按团队规模勾选要执行的规范（个人项目可只保留 git-workflow / ai-coding / documentation / testing）
27+
- [ ] `docs/adr/`：删除示例，从第一项真实决策开始
28+
- [ ] `docs/knowledge/`：清空 bugs/ solutions/ learnings/ 示例，保留 index.md 骨架
29+
- [ ] `docs/versions/`：创建当前版本的 v0.1.0.md
30+
- [ ] `docs/archive/`：删除"基线归档"示例索引，从第一个归档日开始
31+
- [ ] `package.json`：加入 `"docs:check": "node scripts/docs-check.mjs"`，可选接入 lint-staged/CI
32+
- [ ] 根 README 加一行指向 `docs/` 的链接
33+
34+
---
35+
36+
## 📐 目录结构
37+
38+
```
39+
docs/
40+
├── README.md # 总导航：目录说明 + 维护节奏 + 写作规范速查（本文件）
41+
├── standards/ # 工程规范（20 个通用文档 + README 索引）
42+
├── templates/ # 文档模板（12 个 + README 索引 + 选择指南）
43+
├── adr/ # 架构决策记录（README + 编号规则）
44+
├── knowledge/ # 知识库（index + bugs/ + solutions/ + learnings/）
45+
├── versions/ # 版本迭代（README + 沉淀规则）
46+
├── product/ # 产品文档（按需裁剪：需求池/品牌/定价）
47+
├── Foresight/ # 前瞻规划（按需裁剪：路线图/头脑风暴）
48+
├── archive/ # 归档机制（README + 日快照 + tech-debt 滚动）
49+
└── scripts/ # 文档自动化（docs-check.mjs）
50+
```
51+
52+
## 🧭 按需裁剪指南
53+
54+
| 项目类型 | 保留 | 可裁剪 |
55+
|---------|------|--------|
56+
| 个人工具/库 | standards 全部 + templates 全部 + adr + knowledge + versions | product/ Foresight/ archive/（或仅留 archive 目录占位） |
57+
| 小团队产品 | 全部保留 | product/ 只留 requirements-pool.md |
58+
| 中型产品 | 全部保留 + 按需扩展 product/ | — |
59+
60+
## 🔁 维护节奏（工程化承诺）
61+
62+
- **每次文档变更**：`node scripts/docs-check.mjs` 校验链接/索引/命名（可挂 lint-staged）
63+
- **每次发版**：更新 CHANGELOG + `versions/vX.Y.Z.md`
64+
- **每次技术决策**：新建 `adr/ADR-XXX-*.md`（模板复制）
65+
- **每次踩坑**：新建 `knowledge/bugs/YYYY-MM-DD-*.md`（模板复制）并登记索引
66+
- **日收工（<15 分钟）**：已实施文档移入 `archive/YYYY-MM-DD/`，滚动 tech-debt.md
67+
68+
---
69+
70+
## ⚠️ 使用注意
71+
72+
- 本骨架的 standards/templates 是**通用最佳实践沉淀**，随熵减项目演进同步更新；如你 fork 后大幅修改，建议独立维护
73+
- `.docscheckignore` 声明历史快照豁免——新文档一律不得加入该清单
74+
- 中文为主的项目文档约定：文件命名 kebab-case 或中文短描述，禁止临时后缀（"重制2"、"_tmp"）

‎docs-starter-kit/adr/README.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# 架构决策记录（ADR）索引
2+
3+
> 记录重要技术决策的背景、备选方案与权衡。规范见 [ADR 标准](../standards/adr.md)，
4+
> 模板见 [ADR 模板](../templates/adr-template.md)。
5+
6+
| 编号 | 标题 | 状态 | 日期 |
7+
|------|------|------|------|
8+
| ADR-001 | （示例：你的第一个决策） | 提议 | YYYY-MM-DD |
9+
10+
## 编号规则
11+
12+
按创建顺序递增，三位数字（ADR-001、ADR-002…），编号一经分配不再复用。
13+
文件名格式：`ADR-XXX-kebab-case-title.md`。
14+
15+
## 状态说明
16+
17+
| 状态 | 含义 |
18+
|------|------|
19+
| 提议 | 尚在讨论，未开始实施 |
20+
| 已接受 | 决策生效，代码/配置按此实施 |
21+
| 已废弃 | 不再适用，但保留供历史追溯 |
22+
| 已取代 | 被更新的 ADR 替代，需注明取代者编号 |
23+
24+
## 使用建议
25+
26+
- 决策 ≥ 30 分钟讨论或有多个备选方案时，就值得写 ADR
27+
- 每个 ADR 独立文件，索引表按编号排序
28+
- 被取代的 ADR 不删除，改为"已取代"并注明新编号（保留决策历史）

‎docs-starter-kit/archive/README.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# 文档归档机制
2+
3+
> 唯一权威入口：归档判定标准、日收工 SOP、技术债滚动规则、只读约束。
4+
> 关联：[文档编写规范](../standards/documentation.md)、[技术债务管理](../standards/tech-debt.md)、[归档模板](../templates/archive-template.md)。
5+
6+
## 目的
7+
8+
为已实施完成的文档提供"生命终态"去向：按天快照（`YYYY-MM-DD` 子文件夹）、git mv 保留历史、不可变可追溯。
9+
10+
## 目录结构
11+
12+
```
13+
docs/archive/
14+
├── README.md # 本说明 + 归档日期索引
15+
├── YYYY-MM-DD/ # 某日归档
16+
│ ├── README.md # 当日索引：归档清单 + 债务摘要
17+
│ ├── tech-debt.md # 当日权威债务清单（滚动）
18+
│ └── ...已实施文档快照
19+
```
20+
21+
## 归档对象判定
22+
23+
**可归档（生命终态）**：已落地实施的方案/设计文档、已验收的实施文档、已验证的知识卡（索引标 `[ ] 已归档`）、被取代的 ADR、已发布版本的规划文档、已执行的 spec/plan。
24+
25+
**不归档（持续活跃）**：standards/、templates/、knowledge/index.md、当前生效 ADR、CHANGELOG、README、versions/ 内容。
26+
27+
**判定核心**：内容已实施完成、不再需要活跃维护 → 归档。归档时同步更新活跃区索引。
28+
29+
## 日收工归档 SOP（每个工作日，< 15 分钟）
30+
31+
1. **整理昨日债务**：读 `docs/archive/<昨日>/tech-debt.md`，逐条核对：已偿 → closed（注偿还提交）；未偿 → 继承为 carried
32+
2. **识别今日新债务**：扫描今日提交中的 TODO/FIXME/HACK、妥协方案 → 登记 open
33+
3. **筛选今日已实施文档**：`git log --since=<今日>` 筛 docs 变更 → 按判定标准 → 先确认待归档文档已入库再 `git mv` 入今日归档夹
34+
4. **写当日 README**：归档清单 + 债务摘要
35+
5. **更新活跃区索引**：链接改指归档路径 + 标 `[ ] 已归档`
36+
6. **原子提交**：`docs(archive): archive YYYY-MM-DD`；add 时列出归档夹与涉及文件，禁止 `-A` 目录级 add 波及未跟踪文件
37+
38+
首次归档（基线）无昨日清单可整理，跳过第 1 步。
39+
40+
## 技术债滚动规则
41+
42+
- 任何时刻，债务状态以**最新一日**归档的 `tech-debt.md` 为唯一权威；旧归档仅历史追溯
43+
- 昨日未偿债务今日保留为 `carried`（只写 ID + 一行摘要）
44+
- 无新增债务的归档日，仍须继承昨日清单（"最新归档必有权威清单"）
45+
- 编号沿用 TD-XXX，类型沿用四类分类（有意/无意/环境变化/腐化），字段：`来源归档`、`状态`（open/carried/closed）
46+
47+
## 只读约束
48+
49+
| 约束 | 保证 |
50+
|------|------|
51+
| 技术债只认最新归档 | 上方滚动规则 |
52+
| 旧归档仅可阅读已达成内容 | 除最新一日外禁止修改归档文件；归档与提交原子化，git 历史可审计 |
53+
| 时间戳命名 | `YYYY-MM-DD`；空白日不建夹 |
54+
55+
## 归档索引
56+
57+
| 归档日期 | 内容摘要 | 未偿债务 |
58+
|----------|---------|----------|
59+
| （基线归档日） | 首次归档内容摘要 | （登记 TD-001 或空） |

‎docs-starter-kit/archive/YYYY-MM-DD-README-template.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# YYYY-MM-DD 归档索引
2+
3+
> 归档日索引模板。复制本文件到 `docs/archive/YYYY-MM-DD/README.md` 后填写。
4+
5+
## 归档内容
6+
- （列出今日移入的已实施文档，如：xxx-design.md / xxx-implementation.md）
7+
8+
## 技术债摘要
9+
- 未偿 N 笔：TD-XXX 描述（P 优先级）；详见 tech-debt.md
10+
11+
## 备注
12+
- 下个归档日需先整理本日清单（继承 carried 债务）

‎docs-starter-kit/archive/tech-debt-template.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# 技术债清单（权威：YYYY-MM-DD）
2+
3+
> 本清单为当前唯一权威债务清单，归档日滚动更新；旧归档清单仅历史追溯。
4+
5+
## 未偿债务
6+
7+
| ID | 摘要 | 类型 | 优先级 | 来源归档 | 状态 |
8+
|----|------|------|--------|----------|------|
9+
| （从 TD-001 开始登记） | | | | | open |
10+
11+
## 今日已偿
12+
13+
| ID | 摘要 | 偿还提交 |
14+
|----|------|----------|
15+
| （无） | | |
16+
17+
## 登记规则
18+
19+
- 类型四分类：有意（deliberate）/ 无意（inadvertent）/ 环境变化（environment）/ 腐化（bit rot）
20+
- 优先级：P0 立即处理 / P1 近期 / P2 排期 / P3 观察
21+
- 偿还时在"今日已偿"登记，状态改 closed

‎docs-starter-kit/knowledge/index.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# 知识库索引
2+
3+
> 项目踩坑记录、技术方案与学习笔记汇总。详见 [知识管理规范](../standards/knowledge-management.md)、[知识卡片模板](../templates/knowledge-card-template.md)。
4+
> **新卡片写入后必须同步登记下表**（docs-check.mjs 会校验索引覆盖）。
5+
6+
## 🐛 bugs/ — 踩坑记录
7+
8+
| 日期 | 标题 | 标签 |
9+
|------|------|------|
10+
| （空，从第一条开始） | | |
11+
12+
## 💡 solutions/ — 技术方案
13+
14+
| 日期 | 标题 | 标签 |
15+
|------|------|------|
16+
| （空，从第一条开始） | | |
17+
18+
## 🧠 learnings/ — 学习笔记
19+
20+
| 日期 | 标题 | 标签 |
21+
|------|------|------|
22+
| （空，从第一条开始） | | |
23+
24+
---
25+
26+
## 沉淀规则（30 秒速记）
27+
28+
1. **什么时候写**：解决了值得再犯的错误 / 做了值得复用的方案 → 立即花 5 分钟记录
29+
2. **命名**：`YYYY-MM-DD-kebab-case-标题.md`
30+
3. **模板**：从 [knowledge-card-template.md](../templates/knowledge-card-template.md) 复制
31+
4. **索引**：登记本表 + 补充标签（标签用于检索与关联）
32+
5. **归档**：知识卡被取代或项目完结后，按归档机制移入 `archive/YYYY-MM-DD/`

‎docs-starter-kit/product/README.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# 产品文档
2+
3+
> 按需裁剪目录。个人项目可整体删除；有产品形态时按下列结构维护。
4+
5+
## 建议文件
6+
7+
| 文档 | 何时需要 |
8+
|------|---------|
9+
| requirements-pool.md | 有需求池/待办规划时（需求 → 版本 → 实现追踪） |
10+
| brand-story.md | 有对外品牌叙事时 |
11+
| pricing.md | 有定价/商业模式时 |
12+
| user-research.md | 有用户访谈/反馈分析时 |
13+
14+
## 与 Foresight/ 的分工
15+
16+
- `product/`：已立项、需持续维护的产品文档（需求池、品牌、定价）
17+
- `Foresight/`：未排期的构想、头脑风暴、竞品分析（立项后移入 product/ 或 versions/ 跟踪）
18+
19+
## 维护规则
20+
21+
- 新文档从 [prd-template.md](../templates/prd-template.md) / [brainstorm-template.md](../templates/brainstorm-template.md) 复制
22+
- 每个产品文档在 docs/README.md 总导航中登记

‎docs-starter-kit/product/requirements-pool.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# 需求池
2+
3+
> 项目需求的统一登记入口：需求 → 优先级 → 版本 → 实现 → 验收追踪。
4+
5+
## 需求条目
6+
7+
| ID | 需求 | 优先级 | 状态 | 目标版本 | 备注 |
8+
|----|------|--------|------|---------|------|
9+
| REQ-001 | （示例：第一个需求） | P1 | 待评估 | v0.1.0 | — |
10+
11+
## 优先级定义
12+
13+
| 优先级 | 含义 |
14+
|--------|------|
15+
| P0 | 阻塞发布，必须立即做 |
16+
| P1 | 近期版本必须包含 |
17+
| P2 | 排期做 |
18+
| P3 | 观察/待定 |
19+
20+
## 状态流转
21+
22+
待评估 → 已立项（关联 prd-template 产出 PRD）→ 已排期（进入 versions/vX.Y.Z.md）→ 已实现（验收后关闭）
23+
24+
## 维护规则
25+
26+
- 新需求从 [prd-template.md](../templates/prd-template.md) 补充详情
27+
- 已实现需求标记关闭并注明版本，保留一行记录（追溯）
28+
- 需求变更走评审：变更影响范围、优先级、排期

0 commit comments

Comments
 (0)