教会Claude Code掌握项目专属技能

在ICS，我们为嵌入式Linux构建了大量Qt和QML应用程序。过去一年里，我们也在使用编程智能体——尤其是Claude Code——将其集成到IDE和常规工具链中。它的承诺很简单：描述一个变更，获得补丁，审查后提交PR，然后继续推进。

但现实要复杂得多。开箱即用的情况下，Claude能写出合理且可编译的Qt和C++代码，但它写出的代码并不完全符合我们项目偏好的模式和风格。本文的核心，就是如何通过项目专属技能来弥合这一差距——以我们的一个内部项目为例：一个Qt 6应用程序，配备QML用户界面、严格的接口优先架构，以及自研的QML测试框架。

我们的项目技术栈如下：Qt 6、运行在嵌入式Linux设备上的QML用户界面、遵循SOLID设计原则的接口优先C++架构、用于C++单元测试的Google Test，以及一套高度扩展的QtTest用于QML测试。没有任何模型是针对这种组合训练的，尤其是我们用于实现QML 100%代码覆盖率的自研QML测试框架。

Claude Sonnet和Claude Opus等前沿模型非常擅长模式模仿。给定少量现有类，Claude通常能推断出我们的约定（接口命名规范、QObject实例的所有权归属、QML类型注册方式），并在这些约定范围内生成代码。

但"通常"背后隐藏着大量的不确定性，而且随着会话时间的延长，这种不确定性会愈发明显。我们最初的解决方案很直接：将架构建议追加到CLAUDE.md中，或通过@链接的ARCHITECTURE.md文件引入。这确实有所改善——Claude会读取该文件，对于简短的提示，我们能得到大致符合约束的代码。

然而，随着会话的深入，效果迅速下降。当Claude执行多步骤计划时，位于上下文数百行之前的规则开始"淡出视野"。智能体文件始终存在于上下文中，但"存在于上下文"和"对下一个Token具有显著影响"并不是一回事。

我们认为最佳的解决方案，是停止将架构建议视为静态的项目前言，转而将其作为按需加载的指导内容。这正是"技能"机制的用武之地。

什么是技能

在Claude Code中，技能是一个包含SKILL.md文件的文件夹，该文件具有YAML前置元数据和Markdown格式的说明内容。前置元数据包含两个主要字段：名称和描述。Claude会读取所有可用技能的名称和描述，当它判断某个提示或计划步骤与某项技能匹配时，便会将完整的SKILL.md内容加载到上下文窗口中，紧邻当前活跃的对话轮次。

这种邻近性是真正的优势所在——相关说明会出现在待回答提示的附近，而不是被埋没在冗长对话记录的顶部。

Q&A

Q1：项目专属技能（Skill）在Claude Code中是如何工作的？

A：在Claude Code中，技能是一个包含SKILL.md文件的文件夹，文件中有YAML前置元数据（包括名称和描述）以及Markdown格式的说明。Claude会读取所有可用技能的名称和描述，当判断某个提示或计划步骤与某项技能匹配时，就会将完整的SKILL.md内容加载到上下文窗口中，紧邻当前对话轮次，从而让相关指令在生成代码时更具影响力。

Q2：为什么把架构建议写进CLAUDE.md文件效果会随时间变差？

A：因为"存在于上下文"和"对下一个Token具有显著影响"并不等同。当Claude执行多步骤计划时，位于上下文数百行之前的规则会逐渐"淡出视野"，对模型生成下一段代码的实际约束力大幅下降。会话越长，这种衰减越明显。

Q3：ICS的Qt/QML项目对AI生成代码有哪些具体要求？

A：ICS的项目要求包括：遵循接口优先的C++架构以支持SOLID设计原则、特定的接口命名规范、明确的QObject实例所有权规则、QML类型注册方式，以及使用自研QML测试框架实现100%的QML代码覆盖率。这些约定没有任何模型经过专门训练，因此需要通过项目专属技能来补充引导。