living-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Living Docs

动态文档

Generate documentation driven by actual code changes. Every document traces to specific commits and files. When code changes, docs change.

Language policy: Generate all documentation in English. Include Spanish translations in the

aliases

frontmatter field.

基于实际代码变更生成文档。每份文档都可追溯到特定的提交和文件。代码变更时，文档同步更新。

语言策略：所有文档均以英文生成，在

aliases

前置元数据字段中包含西班牙语翻译。

Folder Structure

文件夹结构

All generated docs live under

${GIT_REPO_ROOT}/docs/

(relative to the repository root). Create this structure if it doesn't exist:

docs/
├── components/          # Component Docs (services, apps, libraries)
│   ├── auth-service.md
│   ├── user-service.md
│   └── shared-utils.md
├── changelogs/          # Changelogs and release notes
│   ├── changelog-auth-service-2026-02-13.md
│   └── changelog-global-2026-02-13.md
├── adrs/                # Architecture Decision Records
│   ├── adr-001-redis-caching.md
│   └── adr-002-event-driven-auth.md
├── runbooks/            # Runbooks and SOPs
│   ├── runbook-deploy-auth-service.md
│   └── runbook-database-migration.md
└── index.md             # Auto-generated index linking all docs

所有生成的文档都存放在

${GIT_REPO_ROOT}/docs/

（相对于仓库根目录）。如果该结构不存在，请创建：

docs/
├── components/          # 组件文档（服务、应用、库）
│   ├── auth-service.md
│   ├── user-service.md
│   └── shared-utils.md
├── changelogs/          # 变更日志和发布说明
│   ├── changelog-auth-service-2026-02-13.md
│   └── changelog-global-2026-02-13.md
├── adrs/                # 架构决策记录（ADRs）
│   ├── adr-001-redis-caching.md
│   └── adr-002-event-driven-auth.md
├── runbooks/            # 运行手册和标准操作流程（SOPs）
│   ├── runbook-deploy-auth-service.md
│   └── runbook-database-migration.md
└── index.md             # 自动生成的索引，链接所有文档

File Naming Conventions

文件名命名规范

Doc Type	Directory	Filename Pattern
Component Doc	`docs/components/`	`{component-name}.md`
Changelog	`docs/changelogs/`	`changelog-{scope}-{YYYY-MM-DD}.md`
ADR	`docs/adrs/`	`adr-{NNN}-{slug}.md`
Runbook	`docs/runbooks/`	`runbook-{operation-slug}.md`
Index	`docs/`	`index.md`

文档类型	目录	文件名格式
组件文档	`docs/components/`	`{component-name}.md`
变更日志	`docs/changelogs/`	`changelog-{scope}-{YYYY-MM-DD}.md`
ADR	`docs/adrs/`	`adr-{NNN}-{slug}.md`
运行手册	`docs/runbooks/`	`runbook-{operation-slug}.md`
索引	`docs/`	`index.md`

Index File

索引文件

After generating or updating docs, update

docs/index.md

with links to all docs:

markdown

undefined

生成或更新文档后，更新

docs/index.md

，添加所有文档的链接：

markdown

undefined

Documentation Index

文档索引

Auto-generated. Last updated: YYYY-MM-DD

自动生成。最后更新时间：YYYY-MM-DD

Components

组件

[[auth-service]] — Authentication and authorization service
[[shared-utils]] — Shared utility library

[[auth-service]] — 认证与授权服务
[[shared-utils]] — 共享工具库

Recent Changelogs

近期变更日志

[[changelog-auth-service-2026-02-13]] — Added OAuth2 support

[[changelog-auth-service-2026-02-13]] — 新增OAuth2支持

Architecture Decisions

架构决策

[[adr-001-redis-caching]] — Accepted

[[adr-001-redis-caching]] — 已采纳

Runbooks

运行手册

[[runbook-deploy-auth-service]] — Deployment procedure

---

[[runbook-deploy-auth-service]] — 部署流程

---

Workflow

工作流程

1. Gather context     → Determine diff scope
2. Extract diff data  → Run extract-diff.sh or git commands
3. Classify changes   → Identify what matters (see references/analysis-patterns.md)
4. Select templates   → Pick doc types (see references/templates.md)
5. Generate docs      → Write markdown with full YAML frontmatter
6. Verify output      → Cross-check generated docs against diff
7. Present summary    → Show what was generated and why

1. 收集上下文     → 确定diff范围
2. 提取diff数据  → 运行extract-diff.sh或git命令
3. 分类变更内容   → 识别重要变更（参考references/analysis-patterns.md）
4. 选择模板       → 挑选文档类型（参考references/templates.md）
5. 生成文档      → 编写带有完整YAML前置元数据的Markdown文档
6. 验证输出      → 对照diff交叉检查生成的文档
7. 呈现总结      → 展示生成的内容及原因

Step 1: Gather Context

步骤1：收集上下文

Determine from the user's message (ask only if not inferrable):

Diff scope: Branch comparison (e.g.,
```
feature/X
```
vs
```
Develop
```
) or last N commits?
Existing docs: Any docs to update rather than create from scratch?

Defaults (when not specified):

Diff scope: Current branch vs default branch (auto-detected from repo)
Output path: Always
```
${GIT_REPO_ROOT}/docs/
```
(using the folder structure above)
Existing docs: Search
```
${GIT_REPO_ROOT}/docs/
```
for matching filenames before creating new docs

从用户的消息中确定以下信息（仅在无法推断时询问）：

Diff范围：分支对比（如
```
feature/X
```
vs
```
Develop
```
）还是最近N次提交？
现有文档：是否有需要更新的文档，而非从零开始创建？

默认规则（未指定时）：

Diff范围：当前分支与默认分支（从仓库自动检测）
输出路径：始终为
```
${GIT_REPO_ROOT}/docs/
```
（使用上述文件夹结构）
现有文档：创建新文档前，先在
```
${GIT_REPO_ROOT}/docs/
```
中搜索匹配的文件名

Step 2: Extract Diff Data

步骤2：提取Diff数据

Run the extraction script from this skill's directory:

bash

undefined

从本技能的目录运行提取脚本：

bash

undefined

Branch comparison (auto-detects default branch)

分支对比（自动检测默认分支）

bash <this-skill-path>/scripts/extract-diff.sh <repo-path> --branch <target>

Last N commits

Filtered by path (for monorepos)

按路径过滤（适用于单体仓库）

bash <this-skill-path>/scripts/extract-diff.sh <repo-path> --branch Develop --path services/auth/


For multi-repo workspaces, run per repository.

bash <this-skill-path>/scripts/extract-diff.sh <repo-path> --branch Develop --path services/auth/


对于多仓库工作区，需针对每个仓库分别运行。

Large Diff Strategy

大Diff处理策略

When the diff is large (100+ files changed or output exceeds ~50KB):

Start with
--stat
only — Use the file list and change counts to plan
Read full diff only for high-impact files — APIs, schemas, configs, contracts, new files
Read only changed hunks for medium-impact files — Business logic, services
Skip full diff for low-impact files — Tests, formatting, comments
Split by directory — If still too large, analyze one component/service at a time

当Diff内容较大（变更文件超过100个或输出大小超过约50KB）：

先仅使用
--stat
—— 利用文件列表和变更数量制定计划
仅读取高影响文件的完整diff —— API、模式、配置、契约、新文件
仅读取中影响文件的变更块 —— 业务逻辑、服务
跳过低影响文件的完整diff —— 测试、格式调整、注释
按目录拆分 —— 如果仍然过大，逐个分析组件/服务

Step 3: Classify Changes

步骤3：分类变更内容

Read

references/analysis-patterns.md

for the full classification guide.

Priority: High-impact changes (new components, public API changes, business logic changes, schema migrations, new dependencies, infra changes) are always documented. Medium-impact (internal refactors, test changes) only if significant. Low-impact (formatting, comments, patch bumps) are skipped.

Key distinctions (from analysis-patterns.md):

Business logic vs refactor: Did test expectations change? → business logic. Same tests pass? → refactor.
Interface exposure: External (public API) > Inter-component (shared packages) > Internal (same module). Document proportionally.

Map each significant change to doc types:

Change Type	Impact	Doc Types
New component / module	High	Component Doc (new)
Public API change	High	Component Doc + Changelog (Breaking if contract changed)
Business logic change	High	Component Doc + Changelog
Inter-component interface change	High	Component Doc + flag downstream consumers
Schema / data model change	High	ADR + Component Doc
Major dependency added	Medium-High	ADR + Component Doc
Infrastructure / deployment change	Medium	Runbook
Internal refactor (same behavior)	Low	Changelog (Internal) or skip
Release milestone	—	Changelog

完整的分类指南请参考

references/analysis-patterns.md

。

优先级：高影响变更（新组件、公共API变更、业务逻辑变更、模式迁移、新依赖、基础设施变更）必须记录。中影响变更（内部重构、测试变更）仅在影响重大时记录。低影响变更（格式调整、注释、补丁版本升级）可跳过。

关键区分（来自analysis-patterns.md）：

业务逻辑vs重构：测试预期是否变更？→ 业务逻辑。测试仍通过？→ 重构。
接口暴露层级：外部（公共API）> 组件间（共享包）> 内部（同一模块）。按比例记录。

将每个重要变更映射到对应的文档类型：

变更类型	影响级别	文档类型
新组件/模块	高	组件文档（新建）
公共API变更	高	组件文档 + 变更日志（若契约变更则标记为破坏性变更）
业务逻辑变更	高	组件文档 + 变更日志
组件间接口变更	高	组件文档 + 标记下游消费者
模式/数据模型变更	高	ADR + 组件文档
新增主要依赖	中高	ADR + 组件文档
基础设施/部署变更	中	运行手册
内部重构（行为不变）	低	变更日志（内部）或跳过
发布里程碑	—	变更日志

Step 4: Select and Fill Templates

步骤4：选择并填充模板

Read

references/templates.md

for all templates and the frontmatter schema.

Frontmatter rules:

ALWAYS include all required fields:

aliases

type

layer

status

owner

tech_stack

last_updated

source_branch

commit_range

Use
```
[[wiki-links]]
```
for owner, tech_stack, and cross-references
Set
```
last_updated
```
to today's date
Set
```
source_branch
```
and
```
commit_range
```
from the actual diff
Set
```
status
```
honestly:
```
active
```
,
```
debt
```
,
```
zombie
```
, or
```
gap
```
Populate
```
aliases
```
with English keywords + Spanish equivalents
Infer
```
owner
```
and
```
tech_stack
```
using the heuristics in templates.md → "Inferring Frontmatter from Diffs"
Omit template sections that don't apply (e.g., don't include "Events Published" for a REST-only service)

所有模板及前置元数据schema请参考

references/templates.md

。

前置元数据规则：

必须包含所有必填字段：

aliases

、

type

、

layer

、

status

、

owner

、

tech_stack

、

last_updated

、

source_branch

、

commit_range

对于owner、tech_stack和交叉引用，使用
```
[[wiki-links]]
```
格式
将
```
last_updated
```
设置为当前日期
根据实际diff设置
```
source_branch
```
和
```
commit_range
```
如实设置
```
status
```
：
```
active
```
、
```
debt
```
、
```
zombie
```
或
```
gap
```
在
```
aliases
```
中填充英文关键词及西班牙语对应词
使用templates.md中的启发式方法从Diff推断
```
owner
```
和
```
tech_stack
```
→ "从Diff推断前置元数据"
省略不适用的模板章节（例如，纯REST服务无需包含“发布的事件”章节）

Step 5: Generate Docs

步骤5：生成文档

Write docs to the folder structure defined above.

Updating existing docs: Read first, preserve frontmatter structure, update

last_updated

and

commit_range

, modify only affected sections, append to "Recent Changes".

按照上述文件夹结构写入文档。

更新现有文档：先读取现有文档，保留前置元数据结构，更新

last_updated

和

commit_range

，仅修改受影响的章节，在“近期变更”中追加新内容。

Merge Strategy for Incremental Updates

增量更新的合并策略

When a doc already exists:

Section	Strategy
Frontmatter	Merge: Update `last_updated` , `commit_range` , `status` . Preserve `owner` , `aliases` (append new ones)
What It Does	Replace only if the component's purpose fundamentally changed
API Surface / Exported API	Merge: Add new entries, update changed entries, mark removed entries as deprecated
Dependencies	Replace with current state
Configuration	Merge: Add new env vars, update changed ones
Key Files	Replace with current state
Recent Changes	Append new changes at the top, keep last 5-10 entries

当文档已存在时：

章节	策略
前置元数据	合并：更新 `last_updated` 、 `commit_range` 、 `status` 。保留 `owner` 、 `aliases` （追加新的别名）
功能描述	仅在组件用途发生根本性变更时替换
API接口/导出API	合并：添加新条目，更新变更条目，将已移除条目标记为已弃用
依赖项	替换为当前状态
配置	合并：添加新环境变量，更新已变更的变量
关键文件	替换为当前状态
近期变更	追加：在顶部添加新变更，保留最近5-10条记录

Step 6: Verify Output

步骤6：验证输出

Before presenting to the user, cross-check:

Every endpoint/export mentioned in docs exists in the diff or codebase
All frontmatter required fields are populated (no empty or placeholder values except
```
owner: "[[TBD]]"
```
)
File paths referenced in "Key Files" actually exist
Breaking changes flagged in Changelog match actual contract changes in the diff
No duplicate docs (check existing files before creating new ones)

呈现给用户前，交叉检查以下内容：

文档中提及的每个端点/导出项在diff或代码库中均存在
所有前置元数据必填字段已填充（除
```
owner: "[[TBD]]"
```
外，无空值或占位符）
“关键文件”中引用的文件路径实际存在
变更日志中标记的破坏性变更与diff中的实际契约变更一致
无重复文档（创建新文档前检查现有文件）

Step 7: Present Summary

步骤7：呈现总结

Show the user what was generated:

undefined

向用户展示生成的内容：

undefined

Documentation Generated

生成的文档

File	Type	Reason
docs/components/auth-service.md	Component Doc	New endpoints in routes/users.ts
docs/changelogs/changelog-auth-2026-02-13.md	Changelog	12 commits with 3 features, 2 fixes

文件	类型	原因
docs/components/auth-service.md	组件文档	routes/users.ts中新增端点
docs/changelogs/changelog-auth-2026-02-13.md	变更日志	12次提交，包含3个功能、2个修复

Key Changes Documented

已记录的关键变更

[bullets]

[项目符号列表]

Skipped (Low Impact)

已跳过的低影响内容

[what and why]


Always update `${GIT_REPO_ROOT}/docs/index.md` with links to all generated docs (for multi-repo workspaces, do this per repository).

---

[内容及原因]


始终更新`${GIT_REPO_ROOT}/docs/index.md`，添加所有生成文档的链接（对于多仓库工作区，需针对每个仓库执行此操作）。

---

Quality Rules

质量规则

No fluff: Every sentence carries information. Cut filler.
Trace to code: Every claim references a file, commit, or config.
Tables over prose: For endpoints, env vars, dependencies — always tables.
Be honest: If the diff reveals tech debt, set
```
status: debt
```
. Living docs tell the truth.
Aliases matter: Include concept name, Spanish translation, common abbreviations.
Omit empty sections: Don't include template sections that have no content for this component.

无冗余内容：每句话都需承载信息，删除冗余表述。
可追溯到代码：每个声明都需引用文件、提交或配置。
优先使用表格：对于端点、环境变量、依赖项，始终使用表格。
如实记录：如果diff显示存在技术债务，设置
```
status: debt
```
。动态文档需如实反映情况。
别名很重要：包含概念名称、西班牙语翻译、常用缩写。
省略空章节：不包含当前组件无内容的模板章节。

Few-Shot Example

示例

Input: Diff Summary

输入：Diff摘要

=== FILE STATS ===
 services/auth/src/routes/auth.ts   | 45 +++++++++--
 services/auth/src/services/oauth.ts | 120 ++++++++++++++++++++++++++++
 services/auth/src/types/auth.dto.ts |  15 ++++
 packages/shared-types/src/user.ts   |   8 ++--
 services/auth/package.json          |   2 +  (added passport-google-oauth20)
 services/auth/tests/oauth.test.ts   |  85 ++++++++++++++++++++

=== COMMIT LOG ===
a1b2c3d feat: add Google OAuth2 login flow
d4e5f6g feat: add OAuth callback handler
h7i8j9k fix: handle missing email in OAuth profile
l0m1n2o chore: add passport-google-oauth20 dependency

=== FILE STATS ===
 services/auth/src/routes/auth.ts   | 45 +++++++++--
 services/auth/src/services/oauth.ts | 120 ++++++++++++++++++++++++++++
 services/auth/src/types/auth.dto.ts |  15 ++++
 packages/shared-types/src/user.ts   |   8 ++--
 services/auth/package.json          |   2 +  (added passport-google-oauth20)
 services/auth/tests/oauth.test.ts   |  85 ++++++++++++++++++++

=== COMMIT LOG ===
a1b2c3d feat: add Google OAuth2 login flow
d4e5f6g feat: add OAuth callback handler
h7i8j9k fix: handle missing email in OAuth profile
l0m1n2o chore: add passport-google-oauth20 dependency

Output: Classification

输出：分类结果

New OAuth service file (oauth.ts, 120 lines) → High impact, new feature → Component Doc update
Route changes (auth.ts, 45 lines) → Public API change → Component Doc + Changelog
Shared types change (packages/shared-types/user.ts) → Inter-component interface → Component Doc + flag consumers
New major dependency (passport-google-oauth20) → ADR candidate
New tests with different expectations → Confirms business logic change, not refactor

新增OAuth服务文件（oauth.ts，120行）→ 高影响，新功能 → 更新组件文档
路由变更（auth.ts，45行）→ 公共API变更 → 组件文档 + 变更日志
共享类型变更（packages/shared-types/user.ts）→ 组件间接口变更 → 组件文档 + 标记消费者
新增主要依赖（passport-google-oauth20）→ ADR候选
新增测试且预期变更 → 确认是业务逻辑变更，而非重构

Output: Generated Docs

输出：生成的文档

```
docs/components/auth-service.md
```
— Updated: added OAuth endpoints, new dependency, new key files
```
docs/changelogs/changelog-auth-2026-02-13.md
```
— New: 2 features (OAuth login, callback handler), 1 fix
```
docs/adrs/adr-003-google-oauth.md
```
— New: Decision to use passport-google-oauth20 for social login
```
docs/components/shared-types.md
```
— Updated: flag that
```
UserDTO
```
interface changed (consumed by 2 services)

```
docs/components/auth-service.md
```
—— 更新：新增OAuth端点、新依赖项、新关键文件
```
docs/changelogs/changelog-auth-2026-02-13.md
```
—— 新建：2个功能（OAuth登录、回调处理）、1个修复
```
docs/adrs/adr-003-google-oauth.md
```
—— 新建：决定使用passport-google-oauth20实现社交登录
```
docs/components/shared-types.md
```
—— 更新：标记
```
UserDTO
```
接口已变更（被2个服务使用）

Resources

资源

```
scripts/extract-diff.sh
```
— Extract structured diff data (file stats, commit log, full diff)
```
references/templates.md
```
— All doc templates with frontmatter schema
```
references/analysis-patterns.md
```
— How to classify changes from diffs

```
scripts/extract-diff.sh
```
—— 提取结构化diff数据（文件统计、提交日志、完整diff）
```
references/templates.md
```
—— 所有文档模板及前置元数据schema
```
references/analysis-patterns.md
```
—— 如何从diff分类变更内容