Menu
当修改 AGENTS.md/CLAUDE.md、docs/api、docs/internals、docs/ops，或代码变更影响这些文档记录的 API、MySQL schema、MQ 契约、Redis 缓存、OSS、错误码、模块架构、配置时，检查并同步更新对应文档，保证项目文档自动维护。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
当用户要求基于某个需求、功能、改造、技术方案或项目实践生成博客文章时使用；必须结合用户给出的完整需求、当前项目真实实现逻辑、业务场景和代码/文档上下文做深入分析，输出通俗易懂且专业的 Markdown 博客到 `.specs/blog/《博客名称》.md`。
MySQL 建表与字段规范（面向 Java 管理端业务：用户、LLM 配置、数据集、知识文件、解析任务）。统一命名、索引、字段类型、时间戳、引擎字符集与注释要求，便于研发与 DBA 评审落地。
SpringDoc OpenAPI 3 中文注解生成工作流。为 Spring Boot Controller 和 DTO 生成符合企业级规范的中文 Swagger 注解（@Tag、@Operation、@Parameter、@Schema）。
brief.md 和 acceptance.feature 已冻结后，生成 .specs/<需求名>/technical_design.md；必须基于真实 Java 代码、组件文档和契约。
为 toLink-Service 的 HTTP 接口构建并执行全面的 curl 黑盒测试。分析待测接口与边界条件，必要时直连数据库或经接口造数，对本地已启动服务发起 curl 请求，断言响应，最终在对话中返回测试结果汇总。
实现完成后，从当前改动创建规范分支、提交并发起 PR。
| name | doc-maintenance-sync |
| description | 当修改 AGENTS.md/CLAUDE.md、docs/api、docs/internals、docs/ops，或代码变更影响这些文档记录的 API、MySQL schema、MQ 契约、Redis 缓存、OSS、错误码、模块架构、配置时，检查并同步更新对应文档，保证项目文档自动维护。 |
| when_to_use | 当用户要求修改项目文档，或代码/配置/数据库/MQ/API/Redis/OSS 改动会导致 docs 下的架构、约定、参考资料不准确时激活。触发示例：'改了 API 记得更新文档'、'新增错误码'、'调整数据模型'、'修改 MQ 消息结构'、'更新 AGENTS'、'同步文档'、'维护项目说明' |
让项目文档跟随真实代码自动同步，避免 AGENTS.md、docs/api/、docs/internals/、docs/ops/ 之间出现过期说明。
本 skill 不是要求每次改代码都重写全部文档，而是要求在相关契约变化时做最小必要同步。
在以下情况必须使用本 skill：
AGENTS.md 或 CLAUDE.mdscripts/db/init.sql / link-api/src/main/resources/schema.sql，影响表结构以下情况一般不需要同步文档：
按变更内容选择对应文档，不要无差别更新所有文件。
| 变更内容 | 必查文档 |
|---|---|
| Controller / API DTO 变更 | docs/api/api_contracts.md |
| Entity / Mapper / DDL 变更 | docs/api/mysql_schema.md + scripts/db/init.sql + link-api/src/main/resources/schema.sql |
| MQ 消息对象、消费者、生产者、Topic 变更 | docs/api/mq_contracts.md + docs/internals/mq_module.md |
| Redis 缓存 key、TTL、结构变更 | docs/internals/cache_module.md |
| OSS 存储路径、文件入口变更 | docs/internals/object_storage_module.md + docs/internals/document_file_module.md |
| 错误码新增或修改 | docs/api/error_codes.md |
| 模块边界、组件职责、业务链路变更 | docs/internals/project_structure.md |
| 配置项（application.yml 等）变更 | docs/ops/configuration.md |
| Agent 入口、阅读路径、目录结构 | AGENTS.md |
| 当前需求的 brief / acceptance / 技术方案 | .specs/<需求名>/ 下对应产物 |
先识别本次变更影响的契约类型：API、MySQL、MQ、Redis、OSS、错误码、架构、配置。
按"文档映射"读取最少必要文档。
对照真实代码或真实配置，不从记忆补写不确定内容。
只更新失效段落，保持原文档结构和粒度。
完成后运行文档同步校验：
python3 scripts/check_ai_links.py
python3 scripts/check_docs_sync.py --working
用 git diff 检查是否仍有旧字段名、旧 topic、旧路径残留。
AGENTS.md 重新膨胀成完整知识库；它只保留入口和阅读路径。scripts/db/init.sql、link-api/src/main/resources/schema.sql、application.yml 和当前文档为准，不从记忆臆造。最终回复需说明：