메뉴
在用户明确要求生成技术方案、技术实现文档或 technical_design.md 时激活；输入源为同目录下的 brief.md 和 acceptance.feature，必须先校验二者存在且 acceptance.feature 已冻结，然后在同目录产出 technical_design.md，并严格基于真实代码、组件文档和公共契约进行设计。原 requirement.md (散文 PRD) 已废弃，不再作为输入。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
契约治理三件套的「值层」。核对同一个物理契约值（MQ topic/group、OSS bucket、消息字段名/别名、内部 HTTP 路径等）在 .env/.env.example/代码生效点/Java 对端多处是否逐字相等，找出配置漂移与死值，防止消息收不到/文件取不到。本 skill 只比对「同一个值在多处是否一致」，不判断结构/语义是否破坏对端（那是结构层，转 contract-guard），也不改文档。
指导 LLM 如何使用 toLink-Rag 项目的 MQ 消息中台进行消息收发、定义新消息类型以及处理多厂商适配逻辑。
当用户认为当前模块代码实现完毕，且当前分支应为 dev，需要从 dev 基于当前修改创建规范分支、提交并发起合并到 dev 的 GitHub PR 时使用；也用于发布收口，即直接创建 dev -> master 的 release PR，不新建 release 分支。适用于“从 dev 新建分支”“把当前修改提 PR”“实现完成创建 feature/refactor 分支并 PR”“发布新版本”“dev 合并 master”等交付收口场景。本 skill 是交付链终点，并在建分支/提 PR 前执行收口门槛：测试未过、契约文档失同步、acceptance 未提升者拒绝收口。
当用户要求把需求、功能、技术方案、架构改造、故障复盘、项目治理实践或实现过程写成博客/技术文章时必须使用；尤其适用于“写一篇博客”“生成技术博客”“把这个需求写成文章”“根据这个功能写博客”“把项目实现讲清楚”等请求。使用时要基于用户给出的需求和 toLink-Rag 当前仓库的真实代码、文档、契约、配置与测试证据完成分析，默认输出 Markdown 到 `.specs/blog/《博客名称》.md`。文章须采用「少量
把项目里已有的内部组件（如 MQ 中台、解析 pipeline、缓存层、对象存储）抽象成一份「项目自有 skill」，让 AI 每次接入都自动复用该组件的架构边界与约定。读组件真实代码，提炼「架构定位 / 职责边界 / 已落地清单 / 扩展点 / 红线」五要素，按统一原型生成 SKILL.md，登记到 .ai/skills/README.md 注册表并跑校验。
当用户要提 issue、登记 bug、记录新需求时使用；自动识别所属项目，生成结构化 issue 内容，先在 Linear 建主记录、再在 GitHub 建镜像，并双向回链。用户说"提个 issue""记一下这个 bug""把这个需求登记一下""同步到 Linear 和 GitHub""别再依赖 Linear 自动同步"时都应触发，即使没有明确说出"Linear"或"GitHub"。
| name | technical-design |
| description | 在用户明确要求生成技术方案、技术实现文档或 technical_design.md 时激活；输入源为同目录下的 brief.md 和 acceptance.feature，必须先校验二者存在且 acceptance.feature 已冻结，然后在同目录产出 technical_design.md，并严格基于真实代码、组件文档和公共契约进行设计。原 requirement.md (散文 PRD) 已废弃，不再作为输入。 |
| when_to_use | 当用户明确要求"生成技术方案 / 生成技术实现文档 / 生成 technical_design.md / 开始技术设计"，且同目录已存在冻结的 brief.md + acceptance.feature 时激活。若任一上游产物缺失，必须先转回对应 skill；不允许仅凭聊天记忆生成技术文档。 |
本 skill 把已确认的 brief.md 和 acceptance.feature 转化为可落地的 technical_design.md。
它主要回答：
它不负责：
implementation-execution）新版工作流的输入源：
.specs/<feature-name>/brief.md（业务理解 + 模块影响面判断 + 概念数据模型）.specs/<feature-name>/acceptance.feature（Gherkin 验收契约，机器可读的业务规则）已废弃的输入源：
requirement.md（旧版散文 PRD）requirement.md，应在 technical_design.md 开头注明"基于历史 requirement.md 而非 acceptance.feature 生成"，并尽量补齐 Gherkin。acceptance.feature 是技术方案最权威的"做对了"标准——TD 中的每个方法级实现都应该能对应到一条或多条 Scenario。
brief 是"假设"，不是方案：brief 第 3 章给出的是模块影响面判断与概念数据模型（关键实体 / 字段 / 关系），作为 TD 的输入假设。TD 的职责是逐条确认或修正该假设、而非从零重推：
docs/api/schemas/mysql.md 与机器强制同步规则。只有满足以下条件时才允许使用本 skill：
.specs/<feature-name>/brief.md 存在且已冻结.specs/<feature-name>/acceptance.feature 存在且已冻结technical_design.md若缺失任一上游产物：
brief-generatoracceptance-generator不允许基于聊天记忆直接生成技术文档。
执行本 skill 时至少读取：
AGENTS.md.specs/<feature-name>/brief.md.specs/<feature-name>/acceptance.feature.specs/<feature-name>/state.yaml（机器拥有的阶段状态，取代旧 feature_info.md）.ai/skills/technical-design/technical_design.template.mddocs/api/**、docs/internals/naming_conventions.md、docs/internals/mq.md（按改动涉及面选读）按需补读：
technical_design.mdimplementation_report.md组件文档强制规则（路径以本项目真实文档为准）：
docs/internals/object_storage.mddocs/internals/mq.md、docs/api/mq_contracts.mddocs/api/schemas/qdrant.md、docs/internals/vectorization.mddocs/api/schemas/elasticsearch.mddocs/internals/parse_task_pipeline.md只要方案中准备"使用、修改、扩展、复用"某组件或模块，就必须先读对应代码或文档。不允许凭类名猜测、历史印象或通用框架经验直接写方案。
固定为：
.specs/<feature-name>/technical_design.md
要求：
.specs/ 整目录 git-ignored，feature 临时工作目录；见 .specs/README.md）.ai/skills/technical-design/technical_design.template.md同时回写 state.yaml：phase 保持 technical_design；冻结时把 artifacts.technical_design.frozen 置为 true。
technical_design.md 结构遵循模板。最低章节：
从仓库根或模块根开始展示。每个文件 / 目录后标注动作：
[新增] / [修改] / [删除] / [测试新增] / [测试修改] / [不改] / [待确认][修改] / [新增] 必须用一句话说明改动目的[不改] 用于明确"不动"的公共契约文件，避免实现阶段误改[待确认] 必须在"风险与待确认问题"章节解释只列本次涉及的文件，不粘贴完整项目树。
| 文件 | 类 | 方法 | 动作 | 输入 | 输出 | 改动目的 | 对应 Scenario |
|---|
每个 [修改] / [新增] 方法的"对应 Scenario"必须填写至少一条来自 acceptance.feature 的 Scenario 名称。这是新流程的核心追溯链：业务规则 → 验收 Scenario → 方法实现 → 测试。
对每个 [修改] / [新增] 方法说明：
如果某个文件标为 [修改] 但没有方法级方案，TD 不合格。
如果某方法需要新增参数或返回值，必须写明调用方同步改动。
新增强制规则：
pytest tests/acceptance/<feature>.feature 等具体命令先用脚本做机器门禁：
python scripts/acceptance/flow-guard.py check <feature-name> technical_design
该命令校验 state.yaml 合法且 brief、acceptance 均已冻结。返回 HARD STOP 时按 Next: 回上游，不得继续。通过后再确认：
brief.md 存在acceptance.feature 存在任一缺失，停止并说明，不允许凭记忆生成。
从 brief.md 提取，并对每条模块影响面判断标注沿用 / 修正（不从零重写）：
修正过的假设记一行"与 brief 判断的差异"（哪里改了、为什么），写入文档修订记录或输入依据映射表。
从 acceptance.feature 提取：
把 Scenario 列表作为"必须满足的契约清单"——TD 中的每个方法实现都应该指向至少一条 Scenario。
至少确认：
[修改] 文件是否真实存在[新增] 文件的父目录是否符合现有项目结构[修改] 方法是否真实存在[新增] 方法所属类是否真实存在或已说明新建原因未扫代码就写方案 → TD 默认不合格。
逐条 acceptance.feature 中的 Scenario 自查：
展示给开发者后进入审核循环：
state.yaml：把 artifacts.technical_design.frozen 置为 true，phase 推进到 implementationimplementation-execution以下问题不清楚时必须先向用户提问，不允许直接产出最终 TD：
提问规则：
合格的 TD 必须做到：
应避免的表达：
除非已经明确指出现有逻辑具体是哪个类、哪个流程。
brief.md + acceptance.feature；缺失任一 → 转上游 skillimplementation-execution