AI 时代如何使用团队 Skill 开发项目从上下文工程到功能落地在复杂业务项目里让 AI 直接“读仓库然后开发”很容易翻车。尤其是这种场景一个服务不是孤立模块而是为了兼容外部协议同时还要参考旧业务系统的实现方式。比如这次的项目可以抽象成cloud-api-adapter它的目标是兼容某厂商 Cloud API但内部又要参考legacy-dock-service的设备调度、指令生命周期、错误语义和状态缓存。这类项目最怕两件事AI 只盯着某一个功能点忽略整个 adapter 的定位AI 把参考仓库当成依赖直接复用或耦合旧代码路径所以我没有直接进入开发而是用一套 skill 流程把“项目上下文”先工程化。一、AI 时代项目结构需要多一层“AI 协作基础设施”这次实践之后我有一个更强的感受AI 时代的项目工程不再只是src、test、config、docs这些传统目录。如果希望 AI 真正参与一个长期项目而不是每次都像一个临时外包一样重新读仓库、重新猜上下文项目里需要多一层“AI 协作基础设施”。这层内容不一定都由人手写也不应该全部混在普通业务文档里。它大致可以分成三类。目录或文档是否必须主要来源作用docs/ai-coding/必须project coding skill 生成人再校准AI 进入项目时的上下文入口docs/plans/必须superpower / planning skill 生成人确认单次功能开发的执行计划和审查记录项目自身业务文档必须团队自己提供和维护给人类维护者看的长期业务、架构、协议知识docs/specs/或功能设计文档视项目复杂度决定AI 辅助生成人确认沉淀较大功能的设计方案graphify-out/可选graphify 生成用知识图谱辅助理解复杂代码关系这里最核心的是前面三类。docs/ai-coding/不是普通文档它更像是 AI 的项目入口。它告诉 AI这个项目是什么、边界在哪里、哪些模块是核心区、哪些模块只是参考区、哪些代码路径不能耦合、开发前必须先看哪些资料。docs/plans/解决的是另一个问题AI 这一次准备怎么改。项目上下文告诉 AI “这个系统是什么”执行计划告诉团队 “这次变更准备怎么做”。这两个东西不能混在一起。项目自身业务文档仍然必须存在。AI 上下文不能替代人的架构文档、协议说明、部署说明、业务流程说明。原因很简单docs/ai-coding/是为了让 AI 高效协作业务文档是为了让团队长期维护系统。所以我更倾向于把 AI 时代的项目文档分成这样三层AI 项目上下文由 project coding skill 初始化再由人补充规则和边界。AI 执行计划由 superpower / planning skill 生成再由人确认后执行。人类业务文档由团队自己维护作为项目长期知识资产。至于 ADR、verification 这类目录并不是不要而是不应该为了 AI 协作机械增加。很多项目的docs/ai-coding/或功能计划里已经包含了关键决策、风险、验证方式再单独拆一层反而可能造成重复维护。目录结构应该服务项目而不是服务仪式感。这一点也许是整套实践里最值得沉淀的结论AI coding 真正需要的不是更多提示词而是项目里有一套 AI 能读、团队能审、后续能追踪的协作结构。二、先用 project-context-init 初始化项目上下文第一步是执行project-context-init。它的作用不是生成一堆泛泛的项目说明而是让 AI 先明确几个边界项目元素本次定义核心工作区cloud-api-adapter参考区legacy-dock-service协议目标兼容某厂商 Cloud API文档来源厂商官方 Cloud API 文档当前关注不局限远程控制模块而是整个 adapter 的上下文一开始我也犯了一个典型错误把关注点放到了远程控制模块上。后来调整成远程控制只是下一步要开发的能力项目上下文必须覆盖整个 adapter。否则后续开发载荷控制、直播、属性设置、航线任务、状态上报等能力时AI 都可能拿某一个模块的设计去机械套用。这一步最后沉淀到类似这些文件docs/ai-coding/contexts.mddocs/ai-coding/cloud-api-adapter/project-profile.mddocs/ai-coding/cloud-api-adapter/architecture-summary.mddocs/ai-coding/cloud-api-adapter/coding-rules.mddocs/ai-coding/cloud-api-adapter/open-questions.mddocs/ai-coding/cloud-api-adapter/feature-prompt-context.md三、手工调整AI 生成上下文后必须人工校准项目初始化不是结束而是开始。AI 生成的上下文通常能给出一个框架但很多关键业务约束必须人工补充。我们这次重点补了几个约束。1. 任务模式改成“混合型”不是所有功能都允许 AI 直接实现。我们明确规定第一阶段恢复上下文、阅读资料、总结现状、提出问题和方案。第二阶段只有我明确说“开始实现”“继续开发”或“按方案改代码”后才允许修改代码、补测试、运行验证命令。这个规则非常重要。它避免 AI 在协议没吃透、业务映射没确认时就开始改文件。2. 明确旧业务服务只是参考区legacy-dock-service不是 adapter 的依赖也不是调用目标。它只能用于参考原业务 API 怎么设计controller / service / DTO 怎么组织指令模型如何转换错误码如何表达生命周期和超时怎么处理但 adapter 不能Java 依赖legacy-dock-serviceFeign/HTTP 调用legacy-dock-service注入legacy-dock-serviceservice共享 DTO 形成强耦合这条边界写进feature-prompt-context.md后后续 AI 才不会把“参考实现”误解成“复用实现”。3. 根目录不能写死不同同事的本地目录可能不同。所以文档中不能写死类似D:\workspace\xxx\drone-cloud-api而是改成从docs/ai-coding/cloud-api-adapter/向上确认项目根目录判断依据是存在pom.xml存在docs/ai-coding/存在核心模块cloud-api-adapter这个小调整能让上下文文档在团队内可复用。四、open-questions 不是缺陷清单而是下一步开发入口初始化后open-questions.md里会留下很多问题。一开始看起来像“缺失证据”但对于我们来说远程控制模块正是下一步要开发的内容。所以这里不应该写成“初始化失败”而应该改成“下一步远程控制开发范围”。比如控制下行 topic 是否需要订阅控制上行 topic 是否需要 publisher控制状态字段来源是什么控制权 heartbeat 如何维护高频控制数据是否落库超时释放、急停、状态回推如何处理这类问题不是上下文初始化没完成而是功能开发前必须确认的设计问题。五、feature-intake-template 怎么用feature-intake-template的作用是把一次新功能开发变成结构化输入。假设下一步要开发远程控制模块中的某些指令不应该只说帮我实现远程控制。更好的输入方式是官方协议链接是什么本次要实现哪些 method属于services、events、property还是控制下行 topic是否需要services_reply是否需要本地生命周期是否参考legacy-dock-service中已有指令厂商协议字段和内部字段如何映射哪些语义不能擅自改这样 AI 进入project-feature-dev时不会靠猜。六、进入 project-feature-dev先讨论方案不急着写代码当我真正准备开发远程控制模块时使用的是project-feature-dev。这次的问题是开发厂商远程控制协议文档里从 flyto 执行结果事件通知 到 更新 flyto 目标点 中间所有的指令先讨论方案。这句话触发的是第一阶段不是实现阶段。AI 需要先做几件事读取项目上下文读取feature-prompt-context.md对照厂商官方远程控制文档搜索 adapter 现有 services / events / reply / state 链路搜索legacy-dock-service中同类控制链路给出能力归类、映射判断和实现路径最终确认这一段远程控制并不是高频控制下行链路而主要是类型method事件上报fly_to_point_progress事件上报takeoff_to_point_progress事件上报control_status_notify事件上报joystick_invalid_notify服务指令flight_authority_grab服务指令control_mode_enter服务指令control_mode_exit服务指令takeoff_to_point服务指令fly_to_point服务指令fly_to_point_stop服务指令fly_to_point_update这个判断很关键因为它决定第一版可以优先走thing/product/{gateway_sn}/services和events不必一开始就实现高频控制 MQTT 中继。七、这套流程的核心价值这套 skill 流程的价值不是“让 AI 多读点文件”。真正的价值是把 AI 的工作方式从看到需求就写代码变成先建立项目边界再建立功能边界再建立实现方案可以用一张流程图表示否是project-context-init生成项目上下文人工校准 contexts补充 feature-prompt-context整理 open-questions使用 feature-intake-templateproject-feature-dev第一阶段: 读资料和方案讨论用户是否确认开始实现第二阶段: 改代码、补测试、验证八、我的实践建议如果你也想在复杂项目里使用 Codex / AI coding agent我建议至少做到这几点不要让 AI 只围绕当前功能建上下文要先定义整个服务的定位。参考仓库必须写清楚边界是“参考”不是“依赖”。把“什么时候允许改代码”写进上下文。open-questions不要当成失败清单它是后续需求澄清入口。每个新功能都用 intake template 结构化输入。对协议适配类项目必须要求 AI 先做“官方协议 - adapter 实现 - 内部业务链路”的三方映射。对高风险功能先讨论方案再进入实现。九、总结AI coding 真正难的地方不是让 AI 写出某个 Java 类。难的是让 AI 在一个真实业务系统里知道哪些文件能改哪些代码只能参考哪些协议必须遵守哪些语义不能自作主张哪些问题必须先问人project-context-init解决的是“AI 怎么认识项目”。手工调整解决的是“AI 怎么遵守团队规则”。project-feature-dev解决的是“AI 怎么进入一次具体开发”。当这三步连起来AI 才不只是一个代码生成器而更像一个能接手上下文、理解边界、按节奏推进的协作者。十、如何安装这套项目开发 Skill如果你也想在自己的项目里尝试这种方式可以从这个仓库开始project-coding-skills推荐先阅读仓库中的中文 README里面会说明当前支持的 skill、安装方式和使用入口。常见的安装方式是使用 Agent Skills CLInpx skillsaddhuajiexiewenfeng/project-coding-skills安装后重点关注这几个 skillproject-context-init初始化或刷新项目级 AI coding 上下文。project-feature-dev进入新功能开发前加载项目规则、上下文和开发流程。feature-intake-template把新需求整理成 AI 更容易理解和执行的结构化输入。我的建议是不要一上来就在正式业务分支里让 AI 大改代码。可以先选一个已有项目执行一次项目初始化看看生成的docs/ai-coding/是否能准确表达项目边界再人工补充团队规则最后用一个中等复杂度的新功能验证整套流程。 AI 时代，如何使用团队 Skill 开发项目：从上下文工程到功能落地
AI 时代如何使用团队 Skill 开发项目从上下文工程到功能落地在复杂业务项目里让 AI 直接“读仓库然后开发”很容易翻车。尤其是这种场景一个服务不是孤立模块而是为了兼容外部协议同时还要参考旧业务系统的实现方式。比如这次的项目可以抽象成cloud-api-adapter它的目标是兼容某厂商 Cloud API但内部又要参考legacy-dock-service的设备调度、指令生命周期、错误语义和状态缓存。这类项目最怕两件事AI 只盯着某一个功能点忽略整个 adapter 的定位AI 把参考仓库当成依赖直接复用或耦合旧代码路径所以我没有直接进入开发而是用一套 skill 流程把“项目上下文”先工程化。一、AI 时代项目结构需要多一层“AI 协作基础设施”这次实践之后我有一个更强的感受AI 时代的项目工程不再只是src、test、config、docs这些传统目录。如果希望 AI 真正参与一个长期项目而不是每次都像一个临时外包一样重新读仓库、重新猜上下文项目里需要多一层“AI 协作基础设施”。这层内容不一定都由人手写也不应该全部混在普通业务文档里。它大致可以分成三类。目录或文档是否必须主要来源作用docs/ai-coding/必须project coding skill 生成人再校准AI 进入项目时的上下文入口docs/plans/必须superpower / planning skill 生成人确认单次功能开发的执行计划和审查记录项目自身业务文档必须团队自己提供和维护给人类维护者看的长期业务、架构、协议知识docs/specs/或功能设计文档视项目复杂度决定AI 辅助生成人确认沉淀较大功能的设计方案graphify-out/可选graphify 生成用知识图谱辅助理解复杂代码关系这里最核心的是前面三类。docs/ai-coding/不是普通文档它更像是 AI 的项目入口。它告诉 AI这个项目是什么、边界在哪里、哪些模块是核心区、哪些模块只是参考区、哪些代码路径不能耦合、开发前必须先看哪些资料。docs/plans/解决的是另一个问题AI 这一次准备怎么改。项目上下文告诉 AI “这个系统是什么”执行计划告诉团队 “这次变更准备怎么做”。这两个东西不能混在一起。项目自身业务文档仍然必须存在。AI 上下文不能替代人的架构文档、协议说明、部署说明、业务流程说明。原因很简单docs/ai-coding/是为了让 AI 高效协作业务文档是为了让团队长期维护系统。所以我更倾向于把 AI 时代的项目文档分成这样三层AI 项目上下文由 project coding skill 初始化再由人补充规则和边界。AI 执行计划由 superpower / planning skill 生成再由人确认后执行。人类业务文档由团队自己维护作为项目长期知识资产。至于 ADR、verification 这类目录并不是不要而是不应该为了 AI 协作机械增加。很多项目的docs/ai-coding/或功能计划里已经包含了关键决策、风险、验证方式再单独拆一层反而可能造成重复维护。目录结构应该服务项目而不是服务仪式感。这一点也许是整套实践里最值得沉淀的结论AI coding 真正需要的不是更多提示词而是项目里有一套 AI 能读、团队能审、后续能追踪的协作结构。二、先用 project-context-init 初始化项目上下文第一步是执行project-context-init。它的作用不是生成一堆泛泛的项目说明而是让 AI 先明确几个边界项目元素本次定义核心工作区cloud-api-adapter参考区legacy-dock-service协议目标兼容某厂商 Cloud API文档来源厂商官方 Cloud API 文档当前关注不局限远程控制模块而是整个 adapter 的上下文一开始我也犯了一个典型错误把关注点放到了远程控制模块上。后来调整成远程控制只是下一步要开发的能力项目上下文必须覆盖整个 adapter。否则后续开发载荷控制、直播、属性设置、航线任务、状态上报等能力时AI 都可能拿某一个模块的设计去机械套用。这一步最后沉淀到类似这些文件docs/ai-coding/contexts.mddocs/ai-coding/cloud-api-adapter/project-profile.mddocs/ai-coding/cloud-api-adapter/architecture-summary.mddocs/ai-coding/cloud-api-adapter/coding-rules.mddocs/ai-coding/cloud-api-adapter/open-questions.mddocs/ai-coding/cloud-api-adapter/feature-prompt-context.md三、手工调整AI 生成上下文后必须人工校准项目初始化不是结束而是开始。AI 生成的上下文通常能给出一个框架但很多关键业务约束必须人工补充。我们这次重点补了几个约束。1. 任务模式改成“混合型”不是所有功能都允许 AI 直接实现。我们明确规定第一阶段恢复上下文、阅读资料、总结现状、提出问题和方案。第二阶段只有我明确说“开始实现”“继续开发”或“按方案改代码”后才允许修改代码、补测试、运行验证命令。这个规则非常重要。它避免 AI 在协议没吃透、业务映射没确认时就开始改文件。2. 明确旧业务服务只是参考区legacy-dock-service不是 adapter 的依赖也不是调用目标。它只能用于参考原业务 API 怎么设计controller / service / DTO 怎么组织指令模型如何转换错误码如何表达生命周期和超时怎么处理但 adapter 不能Java 依赖legacy-dock-serviceFeign/HTTP 调用legacy-dock-service注入legacy-dock-serviceservice共享 DTO 形成强耦合这条边界写进feature-prompt-context.md后后续 AI 才不会把“参考实现”误解成“复用实现”。3. 根目录不能写死不同同事的本地目录可能不同。所以文档中不能写死类似D:\workspace\xxx\drone-cloud-api而是改成从docs/ai-coding/cloud-api-adapter/向上确认项目根目录判断依据是存在pom.xml存在docs/ai-coding/存在核心模块cloud-api-adapter这个小调整能让上下文文档在团队内可复用。四、open-questions 不是缺陷清单而是下一步开发入口初始化后open-questions.md里会留下很多问题。一开始看起来像“缺失证据”但对于我们来说远程控制模块正是下一步要开发的内容。所以这里不应该写成“初始化失败”而应该改成“下一步远程控制开发范围”。比如控制下行 topic 是否需要订阅控制上行 topic 是否需要 publisher控制状态字段来源是什么控制权 heartbeat 如何维护高频控制数据是否落库超时释放、急停、状态回推如何处理这类问题不是上下文初始化没完成而是功能开发前必须确认的设计问题。五、feature-intake-template 怎么用feature-intake-template的作用是把一次新功能开发变成结构化输入。假设下一步要开发远程控制模块中的某些指令不应该只说帮我实现远程控制。更好的输入方式是官方协议链接是什么本次要实现哪些 method属于services、events、property还是控制下行 topic是否需要services_reply是否需要本地生命周期是否参考legacy-dock-service中已有指令厂商协议字段和内部字段如何映射哪些语义不能擅自改这样 AI 进入project-feature-dev时不会靠猜。六、进入 project-feature-dev先讨论方案不急着写代码当我真正准备开发远程控制模块时使用的是project-feature-dev。这次的问题是开发厂商远程控制协议文档里从 flyto 执行结果事件通知 到 更新 flyto 目标点 中间所有的指令先讨论方案。这句话触发的是第一阶段不是实现阶段。AI 需要先做几件事读取项目上下文读取feature-prompt-context.md对照厂商官方远程控制文档搜索 adapter 现有 services / events / reply / state 链路搜索legacy-dock-service中同类控制链路给出能力归类、映射判断和实现路径最终确认这一段远程控制并不是高频控制下行链路而主要是类型method事件上报fly_to_point_progress事件上报takeoff_to_point_progress事件上报control_status_notify事件上报joystick_invalid_notify服务指令flight_authority_grab服务指令control_mode_enter服务指令control_mode_exit服务指令takeoff_to_point服务指令fly_to_point服务指令fly_to_point_stop服务指令fly_to_point_update这个判断很关键因为它决定第一版可以优先走thing/product/{gateway_sn}/services和events不必一开始就实现高频控制 MQTT 中继。七、这套流程的核心价值这套 skill 流程的价值不是“让 AI 多读点文件”。真正的价值是把 AI 的工作方式从看到需求就写代码变成先建立项目边界再建立功能边界再建立实现方案可以用一张流程图表示否是project-context-init生成项目上下文人工校准 contexts补充 feature-prompt-context整理 open-questions使用 feature-intake-templateproject-feature-dev第一阶段: 读资料和方案讨论用户是否确认开始实现第二阶段: 改代码、补测试、验证八、我的实践建议如果你也想在复杂项目里使用 Codex / AI coding agent我建议至少做到这几点不要让 AI 只围绕当前功能建上下文要先定义整个服务的定位。参考仓库必须写清楚边界是“参考”不是“依赖”。把“什么时候允许改代码”写进上下文。open-questions不要当成失败清单它是后续需求澄清入口。每个新功能都用 intake template 结构化输入。对协议适配类项目必须要求 AI 先做“官方协议 - adapter 实现 - 内部业务链路”的三方映射。对高风险功能先讨论方案再进入实现。九、总结AI coding 真正难的地方不是让 AI 写出某个 Java 类。难的是让 AI 在一个真实业务系统里知道哪些文件能改哪些代码只能参考哪些协议必须遵守哪些语义不能自作主张哪些问题必须先问人project-context-init解决的是“AI 怎么认识项目”。手工调整解决的是“AI 怎么遵守团队规则”。project-feature-dev解决的是“AI 怎么进入一次具体开发”。当这三步连起来AI 才不只是一个代码生成器而更像一个能接手上下文、理解边界、按节奏推进的协作者。十、如何安装这套项目开发 Skill如果你也想在自己的项目里尝试这种方式可以从这个仓库开始project-coding-skills推荐先阅读仓库中的中文 README里面会说明当前支持的 skill、安装方式和使用入口。常见的安装方式是使用 Agent Skills CLInpx skillsaddhuajiexiewenfeng/project-coding-skills安装后重点关注这几个 skillproject-context-init初始化或刷新项目级 AI coding 上下文。project-feature-dev进入新功能开发前加载项目规则、上下文和开发流程。feature-intake-template把新需求整理成 AI 更容易理解和执行的结构化输入。我的建议是不要一上来就在正式业务分支里让 AI 大改代码。可以先选一个已有项目执行一次项目初始化看看生成的docs/ai-coding/是否能准确表达项目边界再人工补充团队规则最后用一个中等复杂度的新功能验证整套流程。