用 Claude API 生成技术文档：从代码证据到 CI 审阅

把代码事实和模型解释分开

API 文档、README、更新日志、错误码说明和代码注释都可由模型辅助起草，但来源不同。参数和默认值优先来自代码或接口 schema，安装方法来自已验证脚本，更新日志来自实际变更；不能让模型补一个看似合理的许可证、性能指标或配置项。

原创流程：先为一个纯函数生成草稿，核对参数、返回值和异常，再扩大到模块。对生产仓库先做资料允许列表，排除密钥、客户数据和不应对外公开的代码；上传或调用 API 前确认组织授权。

可本地执行的 AST 提取演示

以下代码只解析虚构 Python 文本，提取函数名、文档字符串和行号，不执行被解析的模块。已通过本地断言测试。它没有分析完整签名、装饰器或动态行为，输出只能作为模型参考之一。

import ast

def inventory(source):
    tree = ast.parse(source)
    return [{"name": n.name, "line": n.lineno,
             "doc": ast.get_docstring(n) or ""}
            for n in tree.body
            if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))]

source = 'def normalize_title(text):\n    """去除标题首尾空格。"""\n    return text.strip()\n'
items = inventory(source)
assert items == [{"name": "normalize_title", "line": 1, "doc": "去除标题首尾空格。"}]

API 草稿与 CI 的安全流水线

把提取结果、相关源码和已通过测试的示例交给 Messages API，要求“只描述可见行为；未知条件列待确认；附源码位置；不修改源码”。保留模型、提示和输入版本，生成到独立草稿目录。上游调用方式按官方快速入门配置，本文没有发出真实请求。

CI 可用以下阶段组织，属于伪代码而非现成 Actions 文件：检查变更范围 → 离线提取 → 授权环境生成草稿 → 检查链接和示例 → 展示文档 diff → 维护者审核。外部 fork 的不可信代码不得与可用密钥放在同一有特权作业中；不要为了取到 secrets 使用危险事件组合。

验收和维护清单

对 README 从空环境复核安装与最小示例；对接口文档比较参数、异常和返回值；对更新日志检查版本与真实提交；对注释确认没有误导性保证。不能只让同一个模型“自评合格”就自动推送到主分支或发布站点。

记录需要人工修正的错误，优先改进证据采集和模板，再讨论模型选择。公开文档发布前检查商业信息与许可证。本文没有 CI 部署或节省时间实测，不声称文档自动化能消除技术债。