메뉴
当修改 AGENTS.md/CLAUDE.md、docs/api、docs/internals、docs/ops，或代码变更影响这些文档记录的 API、MySQL schema、MQ 契约、Redis 缓存、OSS、错误码、模块架构、配置时，检查并同步更新对应文档，保证项目文档自动维护。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
当用户要求基于某个需求、功能、改造、技术方案或项目实践生成博客文章时使用；必须结合用户给出的完整需求、当前项目真实实现逻辑、业务场景和代码/文档上下文做深入分析，输出通俗易懂且专业的 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 和当前文档为准，不从记忆臆造。最终回复需说明：