后实施文档技能

自动更新代码更改后的存储库文档。此技能确保代码实现后，文档与实际代码库保持同步。

变量

变量	默认值	描述
UPDATE_README	true	为新功能/API更新README.md
UPDATE_CHANGELOG	true	向CHANGELOG.md添加条目
UPDATE_DOCS_FOLDER	true	更新引用更改代码的docs/中的文件
UPDATE_DOCSTRINGS	true	更新更改函数/类的内联文档字符串
CHANGELOG_FORMAT	conventional	conventional, keep-a-changelog, simple
COMMIT_DOCS	true	与代码一起提交文档更改

指令

强制性 - 按照以下工作流程步骤进行。不要跳过步骤。

1. 分析所做的代码更改（git diff）
2. 确定文档影响
3. 如果添加了新功能/API，则更新README
4. 用更改摘要更新CHANGELOG
5. 扫描docs/文件夹以查找对更改符号的引用
6. 更新修改函数/类的内联文档字符串

红旗 - 停止并重新考虑

如果你即将：

• 在不了解代码更改的情况下更新文档
• 为琐碎的更改（错别字、格式化）添加CHANGELOG条目
• 为内部实现细节更新README
• 在未验证行为更改的情况下修改文档字符串

停止 -> 审查差异 -> 了解影响 -> 然后记录

工作流程

1. 收集更改上下文

分析当前实现中更改的内容：

# 获取更改的文件
git diff --name-only HEAD~1 HEAD

# 获取更改摘要
git diff --stat HEAD~1 HEAD

# 获取文档的详细更改
git diff HEAD~1 HEAD -- "*.py" "*.ts" "*.js" "*.go" "*.rs"

2. 对更改进行分类

确定更改的类型和范围：

更改类型	README影响	CHANGELOG条目	文档更新
新功能	添加到功能部分	feat:条目	如果有文档
错误修复	无更改	fix:条目	如果影响行为
重大更改	更新使用示例	BREAKING:条目	更新所有引用
API添加	添加到API部分	feat:条目	添加API文档
弃用	添加弃用说明	deprecate:条目	更新示例
性能	无更改	perf:条目	无
重构	无更改	refactor:条目	无
仅文档	N/A	无条目	N/A
仅测试	无更改	test:条目	无

3. 更新README.md

仅在重大更改时更新README：

将新功能添加到功能部分：

## 功能

- **新功能名称** - 简要描述它的功能

将新API添加到API/使用部分：

## API

### `newFunction(param: Type): ReturnType`

函数及其目的的描述。

如果API更改，则更新使用示例：

## 使用

```python
# 反映新API的更新示例
result = module.new_function(param="value")

4. 更新CHANGELOG.md

按照项目的格式添加条目：

常规变更日志：

## [未发布]

### 添加
- 添加用户认证端点（#123）

### 更改
- 更新数据库连接池大小以提高性能

### 修复
- 修复异步队列处理器中的竞态条件（#124）

### 弃用
- 弃用`old_function()`，转而使用`new_function()`

### 移除
- 移除对Python 3.8的支持

### 安全
- 修复用户输入处理中的XSS漏洞

保持变更日志格式：

## [未发布]

### 添加
- 新功能描述

### 更改
- 更改描述

5. 更新docs/文件夹

扫描文档文件以查找对更改符号的引用：

# 查找引用更改函数/类的文档
grep -r "changed_function\|ChangedClass" docs/

对于每个匹配项：

1. 验证文档是否仍然准确
2. 如果签名更改，则更新参数描述
3. 如果行为更改，则更新示例
4. 如果文件移动，则更新交叉引用

6. 更新内联文档字符串

对于每个带有文档字符串的修改函数/类：

Python：

def function(param: str) -> bool:
    """反映新行为的更新描述。

    参数：
        param: 更新的参数描述。

    返回：
        更新的返回值描述。

    引发：
        ValueError: 如果param无效（新错误情况）。
    """

TypeScript/JavaScript：

/**
 * 反映新行为的更新描述。
 *
 * @param param - 更新的参数描述
 * @returns 更新的返回值描述
 * @throws {Error} 如果param无效（新错误情况）
 */
function func(param: string): boolean {

食谱

README更新

• 如果：添加新公共功能
• 那么：阅读cookbook/readme-updates.md
• 结果：更新的功能列表和示例

CHANGELOG条目

• 如果：编写CHANGELOG条目
• 那么：阅读cookbook/changelog-formats.md
• 结果：正确格式化的条目

文档字符串标准

• 如果：更新内联文档
• 那么：阅读cookbook/docstring-standards.md
• 结果：一致的文档字符串格式

快速参考

需要记录什么

更改	README	CHANGELOG	docs/	文档字符串
新公共API	是	是	是	是
新内部函数	否	也许	否	是
错误修复	否	是	如果行为文档存在	如果签名更改
性能改进	否	是	否	否
重大更改	是	是	是	是
弃用	是	是	是	是

约定提交到CHANGELOG映射

提交类型	CHANGELOG部分
feat:	添加
fix:	修复
perf:	更改
refactor:	更改
deprecate:	弃用
BREAKING CHANGE:	更改（带重大说明）
security:	安全
docs:	（跳过）
test:	（跳过）
chore:	（跳过）

集成点

此技能被调用：

1. 由lane-executor：在完成实施任务后
2. 由测试工程师：在重要的测试添加后
3. 在PR创建前：确保文档是最新的

在Lane Executor中的示例集成

## 实施后步骤

完成实施后：
1. 运行`dependency-sync`技能以更新清单
2. 运行`post-impl-docs`技能以更新文档
3. 验证构建/测试仍然通过
4. 一起提交所有更改

输出

文档更新报告

{
  "status": "success",
  "updates": {
    "readme": {
      "updated": true,
      "sections_modified": ["Features", "API"]
    },
    "changelog": {
      "updated": true,
      "entries_added": [
        {"type": "feat", "description": "Add user authentication endpoint"}
      ]
    },
    "docs_folder": {
      "files_updated": ["docs/api.md", "docs/getting-started.md"],
      "references_fixed": 3
    },
    "docstrings": {
      "functions_updated": 5,
      "classes_updated": 2
    }
  },
  "commit_sha": "abc123"
}

无更改报告

{
  "status": "no_changes",
  "reason": "Changes are internal implementation only",
  "analysis": {
    "change_type": "refactor",
    "public_api_affected": false,
    "documentation_impact": "none"
  }
}