doc-consistency

用途

doc-consistency 是一个文档一致性技能，用于 vscode-sidebar-terminal 项目，目标是确保项目文档准确反映当前实现。当代码发生变更后，该技能指导开发者同步更新相应文档，避免文档与实现脱节。

何时使用

根据资料，以下情况应使用该技能：

实现新功能之后
修复了会改变行为的缺陷之后
创建发布之前
添加或修改配置选项时
添加或修改键盘快捷键时
更新架构或模式时
审查文档质量时

文档更新工作流

1. 识别变更的组件

代码变更后，先确定哪些文档需要更新。资料给出的对应关系如下：

新功能：README.md、CHANGELOG.md
缺陷修复：CHANGELOG.md
配置变更：README.md（Configuration）、CHANGELOG.md
快捷键变更：README.md（Keyboard Shortcuts）、CHANGELOG.md
架构变更：CLAUDE.md，可能还包括领域级 CLAUDE.md 文件
WebView 变更：src/webview/CLAUDE.md、CLAUDE.md
测试模式变更：src/test/CLAUDE.md

2. 按顺序更新文档

CHANGELOG.md：始终最先更新。在 [Unreleased] 区段下添加条目，使用正确的分类（Added/Changed/Fixed 等），如适用则包含 issue/PR 编号。
README.md：若有用户可见变更则更新。新功能更新 Features 表，设置变更更新 Configuration 区段，绑定变更更新 Keyboard Shortcuts。
CLAUDE.md：若影响开发流程则更新。新增 npm 脚本更新 Commands 区段，模式变更更新 Architecture 区段，最佳实践更新则更新 Guidelines。
领域专属文档：若涉及专门领域则更新。WebView 变更更新 src/webview/CLAUDE.md，测试变更更新 src/test/CLAUDE.md。

3. 验证一致性

从 references/verification-checklist.md 运行验证检查，资料中给出的命令包括：

版本检查：

node -p "require('./package.json').version"

命令检查：

node -p "require('./package.json').contributes.commands.map(c => c.command).join('\n')"

配置检查：

node -p "Object.keys(require('./package.json').contributes.configuration.properties).join('\n')"

发布前文档检查清单

每次发布前需验证：

CHANGELOG.md 有新版本条目且日期正确
所有新功能已在 README.md 中记录
所有变更的配置已正确记录
所有键盘快捷键已记录且平台正确
各文件中的版本号一致
文档中没有遗留 TODO 项
链接可用

快速参考命令

检查未记录的命令

node -e "
const pkg = require('./package.json');
const fs = require('fs');
const readme = fs.readFileSync('README.md', 'utf8');
pkg.contributes.commands.forEach(cmd => {
  const shortName = cmd.command.replace('secondaryTerminal.', '');
  if (!readme.includes(shortName)) {
    console.log('Undocumented:', cmd.command);
  }
});
"

检查未记录的配置

node -e "
const pkg = require('./package.json');
const fs = require('fs');
const readme = fs.readFileSync('README.md', 'utf8');
Object.keys(pkg.contributes.configuration.properties).forEach(key => {
  if (!readme.includes(key)) {
    console.log('Undocumented config:', key);
  }
});
"

检查 CHANGELOG 版本

VERSION=$(node -p "require('./package.json').version")
grep -q "## \[$VERSION\]" CHANGELOG.md && echo "Version documented" || echo "Version missing in CHANGELOG"

文档结构

README.md 结构

# Product Name
[Badges]
**Description**
[Hero Image]
## Quick Start
## Key Features
## Keyboard Shortcuts
## Command Palette
## Configuration
## Architecture
## Performance
## Troubleshooting
## Development
## Known Limitations
## Privacy
## Contributing
## Links
## License

CHANGELOG.md 条目格式

## [X.Y.Z] - YYYY-MM-DD

### Added
- **Feature Name**: Description (#issue-number)

### Fixed
- **Bug Name**: Fix description (#issue-number)
  - Technical detail if helpful

### Changed
- **Component Name**: What changed

CLAUDE.md 结构

## Development Flow
## Essential Development Commands
## Architecture Overview
## Development Guidelines
## Known Issues & Workarounds
## Performance Optimization
## Testing Strategy
## Emergency Response

参考文件

资料列出以下参考文件及其使用时机：

references/documentation-structure.md：理解项目文档布局时
references/verification-checklist.md：运行一致性检查时
references/writing-guidelines.md：撰写或改进文档时

常见问题与解决方案

功能在代码中但未记录：在 README.md 的 Key Features 表中添加功能描述；在 CHANGELOG.md 的适当区段添加条目；若架构变更则更新 CLAUDE.md。
配置默认值变更：更新 README.md 的 Configuration 区段；在 CHANGELOG.md 的 Changed 下添加条目；验证 package.json 描述是否匹配。
键盘快捷键修改：更新 README.md 的 Keyboard Shortcuts 表；同时包含 Mac 和 Win/Linux 绑定；添加 CHANGELOG.md 条目。
日文文档不同步：对比 README.md 与 docs/README_ja.md；用新内容更新日文版本；考虑领域级 CLAUDE.md 文件是否需要翻译。

写作风格快速参考

简洁：用户会快速浏览文档
准确：与当前实现完全一致
以用户为中心：聚焦“如何使用”而非“如何工作”
一致：遵循每个文件中的现有模式
可操作：包含命令和示例

限制

资料未提供该技能的具体安装方式、支持的平台范围、收费或价格信息，这些内容暂未提供。