ARTICLE DETAIL

资讯详情

深耕编程入门与网站建设的一线实战洞察。

Sure 仓库的 AI 指令适配层:多 Harness 指令入口的统一维护实战

Sure 仓库的 AI 指令适配层:多 Harness 指令入口的统一维护实战 金融科技后端前端移动开发桌面应用AI 应用【免费下载链接】sureThe personal finance app for everyone (by everyone)项目地址https://gitcode.com/gh_mirrors/sure5/sure点击查看免费下载本篇技术指南围绕 Sure个人财务管理应用开源仓库中的 harness-adapters.md 展开讲解该仓库如何在同一份权威指令AGENTS.md之上为 Claude Code、Cursor、GitHub Copilot、Junie、Gemini Code Assist 等多个 AI 编程 Harness 维护薄薄的“适配层”并沉淀出可复用的多入口指令治理方法。读完本文你将掌握各 Harness 指令入口的加载机制与差异、Cursor 规则.mdc的 frontmatter 加载语义、维护多 Harness 指令的通用原则以及如何识别并归档遗留辅助脚本。一、背景为什么一个仓库需要多个指令入口现代 AI 编程工具Claude Code、Cursor、GitHub Copilot、JetBrains Junie、Gemini Code Assist 等各有自己的“记忆”文件约定有的读取根目录AGENTS.md有的支持文件导入有的要求.mdc扩展名加 frontmatter还有的通过 YAML 控制代码审查行为。如果为每个工具各维护一份完整独立的指令副本任何一条约定比如“新迁移必须使用当前 Rails 版本”都需要在多处同步修改极易出现漂移——preservation map 中记录的 Junie 复制九条 Cursor 规则后“源文件后续变更不会自动同步到副本”就是典型教训。Sure 仓库的解法是单源权威 薄适配层权威指令根目录 AGENTS.md 存放共享的仓库级要求并链接到 docs/llm-guides/ 下按主题拆分的详细指南架构、测试、UI、API、Provider 等适配层每个 Harness 的入口文件只负责“发现和路由”用各自原生语法指向AGENTS.md及适用指南不复制正文。harness-adapters.md 正是这份适配策略的说明文档配套的 instruction-preservation-map.md 则是记录迁移决策、文件处置和历史演进的审计清单。二、支持的命令入口Harness与加载行为文档以表格形式明确了当前仓库支持的六个入口及其加载方式以下是完整对照路径均已转换为仓库根目录相对路径Harness仓库入口文件加载行为AGENTS 兼容工具AGENTS.md读取根指令及其中链接的适用指南。Claude CodeCLAUDE.md会话启动时通过原生AGENTS.md导入加载权威文件。CursorAGENTS.md 与 .cursor/rules/ 项目规则原生支持根级AGENTS.md保留的.mdc规则通过引用共享指南并保留其原有适用性。GitHub Copilot.github/copilot-instructions.md仓库级指令显式要求 Agent 阅读 AGENTS 及其适用指南。JunieAGENTS.md 与 .junie/guidelines.md当前 Junie 会自动发现根级 AGENTS遗留入口把旧客户端指向同一份指南。Gemini Code AssistGitHub.gemini/config.yaml保留现有审查配置不变这是配置而非指令适配层。实际文件中可以看到这些适配层的具体写法CLAUDE.md 全文仅一行AGENTS.md——Claude 将CLAUDE.md中的AGENTS.md视为导入指令相对导入从导入文件所在位置解析因此该文件与 AGENTS 都是普通文本文件在 Windows 上同样可用.github/copilot-instructions.md 与 .junie/guidelines.md 内容同为两句话先要求阅读并遵循AGENTS.md再要求遵循其中链接的共享指南——这是显式的“读/跟随”链接属于对 Agent 的指令而非声称每个 Copilot 表面都会自动展开 Markdown 链接。2.1 Claude CodeAGENTS.md导入Claude Code 使用AGENTS.md从CLAUDE.md导入根文件。要点在于“导入”语义相对导入基于导入文件的位置解析使用导入后两份文件都保持普通文本文件性质跨平台含 Windows表现一致。这避免了维护两份正文、只保留一行适配器的成本。2.2 Cursor.mdc规则与 frontmatterCursor 支持根级与嵌套的AGENTS.md同时项目规则要求.mdc扩展名、frontmatter 以及文件引用用于包含共享内容。仓库中的适配器统一使用仓库根路径引用例如 .cursor/rules/general-rules.mdc--- description: Miscellaneous rules to get the AI to behave globs: * alwaysApply: true --- AGENTS.mdfrontmatter 的语义直接影响规则是否被加载文档特别强调两点alwaysApply: true使规则即使同时声明了 globs 也保持全局加载空description与空globs如 Stimulus 规则保留“手动可用”状态添加任意一项都可能改变规则的发现行为。2.3 GitHub Copilot仓库级入口而非依赖自动发现Copilot 对指令文件的支持在 GitHub、CLI 与 IDE 各功能间并不一致因此仓库选择保留仓库级入口而不是依赖所有 Copilot 表面都能自动发现AGENTS.md。值得注意的是Copilot CLI 单独支持在copilot-instructions.md、AGENTS.md和CLAUDE.md中使用相对文件导入。2.4 Junie发现顺序与“不要复制”当前 Junie 的检查顺序是.junie/AGENTS.md→ 根AGENTS.md→ 遗留的.junie/guidelines.md或 guidelines 目录。因此文档明确警告不要引入独立的.junie/AGENTS.md副本因为它会优先于共享的根文件被加载反而破坏单源原则。遗留适配器使用显式读/跟随链接而非未文档化的导入指令。2.5 Gemini Code Assist 与 Gemini CLI 的边界Gemini Code Assist.gemini/config.yaml控制 GitHub 审查行为保留code_review.disable: true、摘要设置、严重性阈值与忽略模式。实际文件内容如下have_fun: true code_review: disable: true comment_severity_threshold: MEDIUM max_review_comments: -1 pull_request_opened: help: false summary: true code_review: true ignore_patterns: []虽然 Code Assist 支持用.gemini/styleguide.md提供审查指令但本仓库没有该文件本次整合也不新增。它属于“配置”而非“指令适配器”。Gemini CLI是另一个独立集成使用GEMINI.md、支持导入并可通过settings.json中的context.fileName更换上下文文件名。本仓库没有受跟踪的 Gemini CLI 上下文配置审查 YAML 也不配置它——文档明确划出这条边界避免把两者混为一谈。三、Cursor 适配层的适用性保留清单文档给出了七条.mdc规则保留的 frontmatter 值全表共享内容已按仓库根路径改写规则共享内容globsalwaysApplygeneral-rules.mdcAGENTS.md*trueproject-design.mdc架构指南*truetesting.mdc测试指南test/**falseview_conventions.mdcUI 指南app/views/**,app/javascript/**,app/components/**/*.jsfalsestimulus_conventions.mdcUI 指南空falseui-ux-design-guidelines.mdc设计系统指南app/views/**,app/helpers/**,app/javascript/controllers/**trueapi-endpoint-consistency.mdcAPI 端点一致性指南app/controllers/api/v1/**/*.rb, spec/requests/api/v1/**/*.rb, test/controllers/api/v1/**/*.rbfalse这张表体现了三个可复用的设计决策常开规则引用通用指南general-rules.mdc*alwaysApply: true与project-design.mdc常开把架构约定模型/PORO/concern 设计、依赖约束、Hotwire、校验位置等始终注入上下文作用域规则按 globs 触发testing.mdc、view_conventions.mdc、api-endpoint-consistency.mdc仅在改动命中对应文件时才加载避免无关任务被无关政策干扰原project-conventions.mdc已退役其内容并入架构指南由常开的project-design.mdc继续提供通用的cursor_rules.mdc模板与自动生成规则的self_improve.mdc触发机制被一并废弃具体处置记录在 preservation map。四、维护多 Harness 指令的工程原则文档给出了四条维护纪律它们可以抽象为任何多 Harness 仓库的通用准则内容分层通用要求放在AGENTS.md详细解释、示例与操作流程放在对应的共享指南docs/llm-guides/下的架构、测试、UI、设计系统、API 一致性、Provider、Goals 等适配层只做加载与路由不承载正文随代码演进代码、工作流或评审要求变化时同步更新指南示例必须对照当前文件验证链接保持准确已解决的临时建议应删除并在变更说明中解释原因改规则前先审查平行入口任何对强制检查、权限要求或 Harness 适用性的有意变更都要显式记录优先修改既有共享指南而不是为了反复出现的代码模式就新增一份 Harness 专属策略文件编辑适配器时验证目标与加载语法必须比对完整的 Cursor frontmatter 元数据值而不是接受允许额外 globs 或重复值的子串匹配。仓库中现成的 verify_api_endpoint_consistency.rb 就是这条纪律的自动化体现——它保护 API 指南及其作用域适配器而 api_endpoint_consistency_rule_test.rb 则校验适配器引用与作用域。五、Skill技能包候选评估为何暂不引入文档考察了两个“有界、可重复”的工作流作为 Skill 候选新增证券价格 Provider涉及注册表、MIC/货币处理、配置、UI/本地化与验证预览功能开关功能门控与发布流程。这两个流程在生态上有真实支持Copilot 与 Junie 都文档化了开放格式与共享的.agents/skills/位置。但仓库的结论是不引入 Skill 包装理由充分共享指南已让这些流程在所有支持的 Harness 中可用仓库本身已有 Rails Provider 生成器可完成同等工作Skill 包装会额外增加一层“发现与维护”成本而当前没有实证的调用、模板打包或执行收益财富wealth系列指南描述的是产品集成与运行协议不属于仓库编码类 Skill。这个判断同时呼应了 AGENTS.md 中“不要因为重复代码就生成更多 Harness 专属策略文件”的原则——治理成本本身也是被治理的对象。六、遗留辅助脚本与本地上下文的识别文档的最后一部分教读者如何区分“受支持的策略”与“遗留/本地生成物”这是审查 AI 指令仓库时最容易踩坑的地方6.1bin/update_structure.sh生成目录树的遗留助手bin/update_structure.sh 是可选的目录树生成脚本其输出.cursor/rules/structure.mdc在.gitignore中忽略不是共享策略来源。从脚本源码看它存在两个已知缺陷第 9 行把alwaysApply: true写入了不同的路径.cursor/structure/structure.mdc随后第 12 行又用# Project Structure覆盖了刚生成的头部。文档明确修复该生成器属于独立工作不影响本次指令整合。同理被忽略的agent.mdc、dev_workflow.mdc、taskmaster.mdc等路径都只是本地/生成上下文。6.2bin/codex-env遗留的 Linux 环境引导bin/codex-env 是遗留的 Linux 环境引导脚本不是标准安装流程也不是 Skill。从源码可以看到它的实际副作用安装系统包、把 PostgreSQL 本地认证改为trust、在 Ruby 版本不一致时注释掉 Gemfile 中的 Ruby 版本要求并标记Gemfile/Gemfile.lock为 assume-unchanged。文档的建议是保持其不变、不宣传为标准流程仓库环境搭建一律以维护中的 开发指南 为准。七、可迁移的方法论总结回到 harness-adapters.md 与 instruction-preservation-map.md这套多 Harness 指令治理方案可以提炼为五步可复用流程盘点用git ls-files列出全部受跟踪指令文件、历史引用与忽略的生成路径形成完整清单定源确定唯一的权威文件AGENTS.md把详细内容下沉到主题指南瘦身每个 Harness 入口只保留原生加载语法导入、读/跟随链接、.mdcfrontmatter删掉重复正文记录用 preservation map 固化每个文件的处置决策、历史演进与“有意的政策决策”例如“预 PR 门槛在所有 Harness 上统一且更强”“退役 Rails 7.2 迁移限制”“退役自动规则增殖”让后来的维护者无需考古校验用自动化测试如 verify_api_endpoint_consistency.rb持续保护关键适配器的引用与作用域。对于任何正在或准备使用多个 AI 编程工具的大型仓库这套“单源权威 薄适配层 审计记录 自动化校验”的组合是避免指令漂移、降低维护心智负担的务实范本。赞分享金融科技后端前端移动开发桌面应用AI 应用【免费下载链接】sureThe personal finance app for everyone (by everyone)项目地址https://gitcode.com/gh_mirrors/sure5/sure点击查看免费下载相关推荐深入 ECC 的 .gemini/GEMINI.md为 Gemini CLI 构建项目级指令基线与跨 Harness 适配层深入 ECC 的 .gemini/GEMINI.md为 Gemini CLI 构建项目级指令基线与跨 Harness 适配层 ECCEverything C人工智能AI 技能AI 插件AI 评测Agent 评测MCP Clients开发工具ECC Harness Audit 命令实战用确定性评分卡审计 Agent Harness 仓库ECC Harness Audit 命令实战用确定性评分卡审计 Agent Harness 仓库 导读 /harness audit 是 ECCEveryt人工智能AI 技能AI 插件AI 评测Agent 评测MCP Clients开发工具60分钟把电视盒变成7x24服务器Amlogic盒子运行Armbian完整指南60分钟把电视盒变成7x24服务器Amlogic盒子运行Armbian完整指南 本文带你完成 Armbian 盒子改造 开源项目 amlogic s9xxx嵌入式开发工具构建工具操作系统上一篇如何让GitHub下载速度提升500%国内开发者必备的加速神器下一篇3步搞定Steam游戏清单下载Onekey工具完全指南创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表