sc-readme

文档自动更新技能

基于 Git 更改进行智能文档维护，支持交叉引用验证、过时情况报告，以及针对关键更新的多模型共识。

快速开始

# Update README based on current branch changes
/sc:readme

# Multi-document review and update (all project docs)
/sc:readme --scope all

# Target specific documentation
/sc:readme --scope api-docs

# Preview changes without writing
/sc:readme --preview

# Analyze N recent commits instead of branch diff
/sc:readme --commits 20

# Force PAL consensus for all updates
/sc:readme --consensus

# Compare against different base branch
/sc:readme --base develop

# Staleness report only (no changes)
/sc:readme --report-only

行为流程

1. 发现 - 运行 git diff 或 git log 查找已更改的文件
2. 分析 - 阅读已更改的文件，并按类型分类（API、配置、依赖项、功能）
3. 映射 - 使用事实来源映射，匹配已更改文件与受影响的文档
4. 验证 - 检查所有文档之间的一致性
5. 规划 - 找出需要更新的章节，并生成过时情况报告
6. 生成 - 使用 Edit 工具更新文档章节
7. 核验 - 使用 PAL codereview 审查最终文档

标志

标志	类型	默认值	描述
--base	string	main	用于比较的基准分支
--preview	bool	false	预览更改，不写入文件
--consensus	bool	false	强制所有更新都使用 PAL 共识
--scope	string	readme	目标：readme、all 或自定义文档路径
--commits	int	-	分析最近的 N 个提交，而非分支差异
--report-only	bool	false	仅生成过时情况报告，不做更改
--cross-ref	bool	true	启用交叉引用验证

使用的 Git 命令

# Branch diff mode (default)
git diff main...HEAD --name-status
git diff main...HEAD
git log main...HEAD --oneline

# Commit mode (--commits N)
git log --oneline -N --name-only --pretty=format: | sort -u | grep -v '^$'
git log --oneline -N

更改类别

类别	文件模式	受影响的文档
API	新增导出的 *.py、*.ts、*.js 文件	README、API 文档
依赖项	package.json、requirements.txt、pyproject.toml	README、安装文档
配置	.env*、*.config.*、settings.*	README、配置文档
功能	新模块、重要新增内容	README、功能文档
数据库	models/、migrations/	数据库文档、README
前端	src/components/、src/pages/	前端文档、README
基础设施	docker-compose*、Dockerfile、CI 配置	DevOps 文档、README

多文档模式（--scope all）

使用 --scope all 时，发现并验证项目中的所有文档文件。

文档发现

自动检测文档文件：

# Find all markdown docs (excluding node_modules, .venv, etc.)
find . -name "*.md" -not -path "*/node_modules/*" -not -path "*/.venv/*" -not -path "*/dist/*"

常见文档模式：

文档文件	用途
README.md	项目主要文档
CLAUDE.md	Claude Code 指南
CONTRIBUTING.md	贡献指南
docs/*.md	扩展文档
frontend/README.md	前端专属文档
api/README.md	API 文档

事实来源映射

将代码更改映射到受影响的文档：

代码模式	受影响的文档
src/api/**、app/routers/**	README、API 文档
src/models/**、app/models/**	README、数据库文档
src/components/**、frontend/src/**	README、前端文档
migrations/**	数据库文档
.env.example	README、所有包含环境变量引用的文档
tests/**	README（测试结构章节）

交叉引用验证

启用 --cross-ref（默认）时，验证文档间的一致性：

• README 中提到的 API 路由与实际路由处理程序一致
• 所有文档中的环境变量与 .env.example 一致
• 文档中引用的文件路径确实存在（通过 Glob）
• 所有文档中的组件名称保持一致
• 文档中的命令在语法上有效

过时情况报告

## Documentation Staleness Report

**Commits Analyzed**: 20 | **Docs Scanned**: 6 | **Issues Found**: 3

### README.md
**Status**: STALE
**Affected by**: src/api/users.py, src/models/user.py

- [ ] API Routes table missing new `/users/bulk` endpoint
- [ ] Environment variables section missing `BULK_IMPORT_LIMIT`

### docs/DATABASE.md
**Status**: UP-TO-DATE
No changes needed.

### frontend/README.md
**Status**: STALE
**Affected by**: src/components/UserProfile.tsx

- [ ] Component list missing UserProfile

更新顺序

按依赖顺序处理文档：

1. 首先处理 README.md（主要参考文档）
2. 其次处理 CLAUDE.md（必须与 README 保持一致）
3. 最后处理其他文档（以 README 作为事实来源）

MCP 集成

PAL MCP

# Consensus for API/breaking changes
mcp__pal__consensus(
    models=[{"model": "gpt-5.2", "stance": "for"}, {"model": "gemini-3-pro", "stance": "against"}],
    step="Evaluate: Does this documentation update accurately reflect the code changes?",
    relevant_files=["/README.md", "/src/changed_file.py"]
)

# Review final documentation
mcp__pal__codereview(
    review_type="quick",
    step="Review documentation accuracy and cross-reference consistency",
    relevant_files=["/README.md", "/docs/API.md"]
)

工具协作

• Bash - Git 命令（git diff、git log）
• Read - 文档文件、已更改的源文件
• Edit - 就地更新文档章节
• Glob - 文件路径验证、文档发现
• Grep - 交叉引用检查、模式验证

示例

更新单个 README

/sc:readme
# 1. git diff main...HEAD --name-status
# 2. Read README.md + changed files
# 3. Identify sections needing updates
# 4. PAL consensus if API changes detected
# 5. Update README.md

审查多个文档

/sc:readme --scope all --commits 20
# 1. git log --oneline -20 for change context
# 2. Discover all .md documentation files
# 3. Map changes to affected docs
# 4. Cross-reference validation
# 5. Generate staleness report
# 6. Update all affected docs

仅生成过时内容报告

/sc:readme --report-only --scope all
# Generates report without making changes

预览模式

/sc:readme --preview
# Same analysis, but output proposed changes instead of writing

防护措施

1. 修改前备份文档
2. 未经用户确认，绝不删除章节
3. 破坏性更改需要达成共识
4. 保留与代码更改无关的自定义内容
5. 按顺序处理——先处理 README，再处理依赖文档
6. 仅修改文档范围内的 .md 文件
7. 始终可通过 git checkout 进行基于 Git 的回滚

相关技能

• /sc:git - Git 操作
• /sc:document - 通用文档生成
• /sc:pr-check - PR 前验证