教 Claude Code 学会项目专属技能：用 SKILL.md 按需注入架构规范
2026/08/21 16:00阅读量 5
针对AI编码助手生成的代码不符合项目自身架构规范的问题，开发团队在 Qt/QML 嵌入式 Linux 项目中为 Claude Code 引入项目专属技能（skills），以 SKILL.md 形式将架构约定按需注入上下文，替代 CLAUDE.md 等静态文档。实际案例展示了两项技能：创建 Qt 类和编写可测试 QML 及测试，帮助模型输出更贴近团队规范、减少人工清理。
事件概述
面对 AI 编码助手只会写“通用代码”的问题，开发团队开始为 Claude Code 定义项目专属技能（project-specific skills）。技能以文件夹内的 SKILL.md 文件承载，通过 YAML frontmatter 中的名称与描述让模型判断何时加载，从而把团队架构规范直接放在当前生成步骤的上下文附近。
核心信息
- 问题根源：Claude Code 默认写出的 Qt/C++ 代码能编译，但不符合项目特定模式；即使把架构建议写进 CLAUDE.md 或通过 @ 链接 ARCHITECTURE.md，长会话多步任务中这些规则仍会逐渐失去约束力。
- Skill 机制：Claude Code 中一个 skill 就是一个包含 SKILL.md 的文件夹，frontmatter 包含 name 和 description。Claude 会读取所有可用技能的概要，并在判断当前提示或计划步骤与某个技能匹配时，将完整 SKILL.md 载入上下文。
- 项目架构背景：示例项目基于 Qt 6 + QML，运行于嵌入式 Linux；C++ 侧采用接口优先的严格分层，构造函数注入依赖，并为每个接口提供 mock，支撑 SOLID 设计与单元测试。
- 两个具体技能：
creating-qt-classes规定接口、实现类、mock 及 QML 类型注册写法；writing-qml-and-tests规定可测试 QML 结构、UnitTestCase 辅助和 mock 单例约定。 - QML 约定示例：可交互元素需按
FileName_itemId规则设置 objectName；异步操作应使用tryVerify/tryCompare代替wait()后接verify()/compare()，以便在检查条件时运行 Qt 事件循环。
值得关注
核心思路是把架构指导从“长期停留在上下文顶部的静态前言”变成“按需提取的即时提示”。对于有着大量重复性、但高度特异工程约定的项目，这种技能封装能让 Claude Code 的输出更贴近团队标准，减少人工清洗。