【免费下载链接】firstmateTalk to one agent. Ship with a crew.项目地址https://gitcode.com/gh_mirrors/fi/firstmate点击查看免费下载导读firstmate-coding-guidelines.agents/skills/firstmate-coding-guidelines/SKILL.md是 Firstmate 仓库中一个仅供 Agent 加载的参考技能用于约束对仓库共享、受跟踪材料AGENTS.md、README.md、CONTRIBUTING.md、.tasks.toml、.github/workflows/、bin/、.agents/skills/、公共skills/的任何修改。它解决的核心问题是AGENTS.md曾在两次重构之间从 585 行膨胀到 958 行——全部源于把本该路由到专属位置的条件化细节直接内联进了主契约。读完本文你将掌握 Firstmate 的知识放置决策树、契约单一所有者规则、内联桩inline-stub模式、技能触发卫生、Agent 依赖型检查的双测试要求以及一整套可直接执行的仓库风格规范。一、定位这是一份改仓库之前先读的 Agent 契约该技能在 Front Matter 中声明user-invocable: false与metadata.internal: true意味着它不对船长captain开放调用只由 Agentfirstmate 本身或接到 firstmate 仓库任务的 crewmate在编辑共享受跟踪材料之前加载。技能描述description本身即是加载触发索引Use before editing any of that material, whether working as firstmate directly or as a crewmate briefed on a firstmate-repo task.。它被登记在agent-skill-trigger-index中触发条件为load before changing firstmates shared, tracked material, as defined by section 1s list, whether editing directly or briefing a crewmate for a firstmate-repo task。共享受跟踪材料的精确清单由AGENTS.md第 1 节定义AGENTS.md、README.md、CONTRIBUTING.md、.tasks.toml、.github/workflows/、bin/、.agents/skills/以及公共skills/。而.env、data/、state/、config/、projects/、.no-mistakes/属于船长私有且被 gitignore不在此列。CONTRIBUTING.md的 Development 一节同样要求在对 firstmate 自身做任何跟踪变更前先加载本技能因为It has the knowledge-placement rules that keepAGENTS.mdfrom regrowing after each diet pass。二、知识放置决策树新事实写进哪个文件在仓库任何位置写入一个新事实前按以下顺序逐层询问停在第一个回答是的层级不得把事实放到比决策树给出的层级更方便的地方Firstmate AGENT 是否每个会话或每个回合都需要它来运行是 → 内联进AGENTS.md。Agent 是否只在可命名的情境下需要它一次 spawn、一次恢复、某类 wake、某个生命周期步骤是 → 放入.agents/skills/下的 agent-only 技能并在技能 description 中声明加载触发仅当某个常载规则必须点名该技能时才在AGENTS.md留一行内联指针。它是否属于公开产品、安装配置或用户/操作者参考是 → 放入按受众分类的docs/documentation-audiences.md对应表面且只保留当前行为、安装配置、支持上限、稳定不变量、简洁理由与当前验证入口。它是否属于贡献者/维护者架构内容是 → 放入分类的 maintainer-architecture 归属文档承载稳定归属、扩展点、机制边界与安全理由。它是否是对当前保证的可复用活动验证是 → 放入显式分类的 maintainer-verification 记录允许保留日期、版本、确切命令与确切输出参见docs/verification/runtime-backends.md。它是否属于任务或事件证据时间线、对话记录、分支、临时路径、失败假设、交付证明是 → 默认留在私有任务报告或 PR 证据中先把每个唯一当前事实蒸馏到其权威归属者。它是否属于机制细节确切 flags、确切命令、确切路径是 → 写入脚本自身的头部注释及其--help输出而不是AGENTS.md、技能或第二个文档归属者。机器消费的清单docs/documentation-audiences.json是所有受维护散文表面的单一分类归属者不要添加并行的 front matter 或第二份受众清单。该 JSON 由bin/fm-doc-audience-check.sh校验其脚本要求 inventory 根为对象、version必须为 1、scope.trackedPatterns必须精确等于[*.md, *.mdx, *.rst, *.txt, docs/examples/*]并强制每个被跟踪表面有且仅有一个受众分类。从源码实现看bin/fm-doc-audience-check.sh该检查还会验证README 的安装配置链接必须指向分类为 setup 受众的表面requiredOwnerPointers中每个归属指针的源文件必须真实存在且包含指向目标文件的链接所有本地 Markdown 链接必须能解析到真实文件与真实锚点任何逃逸出仓库根目录的相对链接../跳出仓库都会被判失败。三、单一所有者规则每个契约只完整陈述一次每个契约——数据格式、状态机、决策过程——全文只陈述一次。其余所有提及都必须是单行交叉引用而非复述。在真正的风险点允许一次刻意的单行强化例如把别忘了 X恰好放在遗忘 X 代价最高的位置但第二次复述契约实质内容是不允许的——两处副本会在只编辑其中一处的那一刻开始漂移。当你触碰某个契约时优先修补、替换或修剪归属者已有的措辞而不是追加新条款或新段落然后用 grep 搜索仓库中该契约的其他提及处更新交叉引用而不是把变更复制成第二份完整副本。该规则贯穿整个仓库的组织方式。例如AGENTS.md第 1 节对共享受跟踪材料的定义、第 8 节的 supervision 协议、bin/fm-lint.sh对 lint 定义的唯一归属——CONTRIBUTING.md明确写道bin/fm-lint.shis the single owner of the lint definition (the shellcheck file set, config, pinned shellcheck version, pinned actionlint workflow lint, and the backend-purity check)CI 使用其完整规范分区no-mistakes 预推送门使用其按上下文选择的默认配置。docs/verification/runtime-backends.md的头部也声明后端指南拥有当前安装配置、安全边界与限制而验证记录只存放可复用的版本化证据——这正是契约单点归属 交叉引用模式的文档化实例。四、内联桩模式内容移出 AGENTS.md 时留下什么当内容从AGENTS.md移入某个技能时用一个问题决定留下什么没有加载技能时什么必须依然存活答案是技能加载的触发条件加上任何在技能未加载的 wake 上会触发的安全关键事实。其余一切——过程、机制、周边细节——全部移走绝不留下半份复述以防万一——半份副本正是单一所有者规则禁止的重复。仓库中的模范是AGENTS.md第 8 节的 Away-mode and quiet-mode stubAGENTS.md它只内联保留技能调用触发条件/afk、/quiet、state/.afk-contract、state/.afk、FM_INJECT_MARK、state/.subsuper-*标记等其余一切指向/afk、/quiet与away-quiet-supervision技能。五、规模纪律AGENTS.md 的 token 成本对每一行即将加入AGENTS.md的内容应用决策树。如果某条新增需要超过几行的条件化细节只在特定情境下才重要或参考细节线格式、精确 schema、历史理由你几乎肯定加错了文件。关键成本模型AGENTS.md的 token 成本由每个 fleet 成员的每个会话、每次支付无论该会话是否会命中新行描述的情境而技能的成本只由真正加载它的会话支付。犹豫时先把事实以修补归属者已有措辞的方式写进技能或文档再向AGENTS.md只添加单行触发。这正是决策树第 1、2 层的经济学解释常载问题留在常载文件情境问题移入按需加载的技能。六、触发卫生新技能必须有人加载一个新技能如果没有东西加载它就是死重。规则如下每个新技能必须在description 中声明加载触发description 即常载触发索引。仅当某个常载规则必须点名该技能时才在AGENTS.md的对应操作节添加内联指针。触发必须写成条件load before X、load on Y wake绝不写成模糊指针。涉及 firstmate 自身受跟踪材料的任务 brief应告知 crewmate 加载本技能。bin/fm-brief.sh的REPO参数是一个调用者提供的字符串与data/projects.md中登记的项目不同它没有可靠信号能表明任务目标就是 firstmate 自身仓库从源码看bin/fm-brief.sh只是简单地把REPO取为位置参数并无项目身份校验因此在脚手架内部没有干净的位置自动检测这一情况。firstmate 改为手工把本技能的加载指令加入 firstmate 仓库的 briefCONTRIBUTING.md的 Development 一节承载同一条指令作为持久提醒。七、兼容性与强制先审查全部受影响的 harness 与运行时后端在改变共享受跟踪行为之前审查每个受影响的受支持主 harness 与运行时后端而不是只检查当前 fleet 中激活的适配器。只有当审查过某轴的集成面后才可把该轴标记为不适用行为变化时要同步更新对应的验证证据docs/verification/runtime-backends.md。对于关键安全、路由、启动与监督基础设施优先采用确定性与幂等性的强制机制而不是单纯依赖 Agent 记忆。指令保持权威层与发现层但要让重复执行安全收敛让无效或不安全状态在运行时能够强制的地方失败关闭fail closed。7.1 依赖 harness 的检查Harness-dependent checks本节是该规则及其满足方式的单一所有者。当检查的裁决来自厂商发出的东西进程名、渲染输出、spinner 或按键字形、banner、harness 绑定的按键时该检查就是 harness 依赖的。这类检查必须针对真实 harness 做端到端证明——桩或伪造 Agent 只能确认已经写进桩里的假设。这种证明被授权消耗 token相对于一个悄悄失效的检查代价很小。构建检查时要选择能回答问题的最具结构性的信号优先内核或协议事实胜过发布说明可能改动的字符串。当渲染表面确实是唯一来源时读取多个独立信号任一信号即可给出正向裁决使任何单个厂商字符串都不成为承重件。当表面信号不可避免时用大声失败、点名 harness 与版本的守卫兜底而不是静默降级。7.2 双测试要求每个此类检查需要两个测试因为它们因不同原因而失败1便携回归测试——放在tests/用真实进程且无 harness 固定逻辑使 CI 在一切运行 tmux 的地方强制分类器。刻意把信号分开驱动断言裁决在丢失其中一个后依然成立断言分歧本身使用例不会悄悄变为空泛。要逐一确认某个构造在每个支持平台上实际遮蔽了哪个信号同一个技巧在 macOS 与 Linux 上可能破坏不同来源而不是想当然。2实况守卫——属于live-harness-optin家族通过bin/fm-test-run.sh对每个已安装的 harness 真实演练并点名 harness 与版本失败。对缺失的 harness 显式报告而不是静默通过拒绝什么都没检查却通过的结论。守卫通过tests/lib.sh中的fm_live_gate开启tests/lib.sh它是该决策的单一所有者不消耗模型 token 的守卫在其工具安装处默认运行提交提示词的守卫保持 opt-in它自己的变量或FM_LIVE强制其开缺失工具则失败而非跳过或关。便携串行 CI 通道无凭据并安装公共 Pi 包因此免 token 守卫可演练可用 Pi 表面而不可用工具则能力跳过在每次 harness 升级后、信任刷新后的逐 harness 证据前运行一次提交提示词的守卫。将带日期的逐 harness 结果记录在docs/verification/runtime-backends.md并指向实况守卫作为刷新该记录的命令而不是让版本限定的观察腐烂成虚假声明。该验证文件正是这一模式的活实例bin/fm-test-run.sh tests/fm-harness-precedence.test.sh的逐条ok -输出、带版本号的验证记录Verified on 2026-09-02 on Linux 7.1.12都被保留而任务时间线、分支名、临时路径等则留在私有报告或 PR 证据中。八、文档变更审查对每个变更的受维护散文表面识别以下五项清单受众inventory audience、权威归属者authoritative owner、当前行为相关性current-behavior relevance、佐证证据的去向destination for supporting evidence、以及删除可能丢失的独特安全事实。只有在当前归属者与回归指针验证过后才移动或删除证据。在完成所有文档、审查修复与 lint 修复提交后针对这些标准重新审查完整分支差异而不是只看最新提交。运行bin/fm-doc-audience-check.shbin/fm-doc-audience-check.sh它强制执行分类、README 安装配置路由、本地链接目标与归属者指针而不对合法证据散文做关键词 lint——正如docs/documentation-audiences.md所强调的日期、版本、命令、路径、事件语言与转录式散文在 maintainer-verification 中是合法的需要语义审查而非关键词启发式。九、No-mistakes 测试配置禁止配置套件级 commands.test绝不在任何仓库的 no-mistakes 配置中配置确定性的套件级commands.test——无论它选择完整套件、变更测试、某个家族还是固定脚本清单。目标化验证属于 no-mistakes 证据路径而 CI 拥有广泛确定性回归覆盖。该规则的代价证据来自 Firstmate PR #3644固定一个 75–162 脚本的遍历每次验证耗时32.7 分钟移除后恢复为3.6 分钟的目标化验证姿态。因此目标化验证保持目标化用bin/fm-test-run.sh指定关心的 subject而不是链式运行bash tests/a.test.sh bash tests/b.test.sh因为脚本路径清单会获得与--changed相同的有限并发。十、仓库风格规则Repo style rules对受跟踪 Markdown 与脚本的硬性约束如下受跟踪 Markdown 中每行一个完整句子绝不把多个句子折到同一物理行。用普通短横线-绝不使用破折号em dash。绝不添加 Agent 名作为提交共同作者AGENTS.md第 1 节同样明文禁止。bin/*.sh与bin/backends/*.sh必须通过shellcheck。Firstmate 生产库测试与 source 了bin/脚本的命令必须显式用bash运行绝不经过工具 shell 的默认解释器。脚本变更完成前运行bin/fm-lint.shbin/fm-lint.sh它是 CI 与 no-mistakes 预推送门共同调用的 lint 定义唯一归属者其自身头部拥有该定义覆盖什么且拒绝在任何其他版本的任一 linter 下运行它固定一个精确的 shellcheck 版本与一个精确的 actionlint 版本。当任务点名某个特定工具时用该工具实现工作或在上线前显式标记替换及其新增依赖足迹以供审查。测试按tests/中既有模式同址放置命名为subject.test.sh扩展现有脚本而非发明新 runner。测试必须通过可执行程序或公共接口演练行为绝不断言实现源码字节——包括通过解析器、正则、快照或间接包装器。docs/verification/下的 maintainer-verification 记录记录主动经验事实而非假设或任务时间线包含支撑当前保证所需的日期、版本、确切运行命令与确切输出。事件时间线与交付证据保留在私有任务报告或 PR 证据中除非需要简洁理由来维持当前安全边界。这些风格约束在CONTRIBUTING.md的 Repo conventions 节同样有镜像表述如CLAUDE.md是真实的AGENTS.md指针、.claude/skills是指向.agents/skills的符号链接两处共同构成文档归属 交叉引用的完整闭环。十一、实践路径一次符合准则的共享材料变更把上述规则合成一次真实操作流程适用于 firstmate 直接修改或为 crewmate 起草 firstmate 仓库任务加载技能在编辑任何共享受跟踪材料前加载firstmate-coding-guidelines为 crewmate 起草 brief 时在 brief 中手工加入本技能的加载指令bin/fm-brief.sh无法自动识别 firstmate 自身仓库。运行决策树对每个新事实逐层询问归属停在第一个是AGENTS.md只接收常载规则与单行触发条件化细节进.agents/skills/机制细节进脚本头部与--help验证记录进docs/verification/证据进私有报告或 PR。遵守单一所有者规则修补归属者已有措辞grep 全仓库更新交叉引用不复制第二份完整副本。评估兼容面审查所有受影响的受支持 harness 与运行时后端harness 依赖的检查补上便携回归 实况守卫两个测试守卫经fm_live_gate开启。跑工具链bin/fm-lint.sh通过后用bin/fm-doc-audience-check.sh验证文档分类与本地链接用bin/fm-test-run.sh跑目标 subject 测试测试与被改脚本在tests/同址、命名subject.test.sh、通过公共接口断言。保持 no-mistakes 目标化不配置套件级commands.test验证走目标化证据路径。结语firstmate-coding-guidelines是一份防止主契约再次膨胀的元契约知识放置决策树回答事实归属单一所有者规则与内联桩模式消灭重复规模纪律与触发卫生控制 token 成本与加载有效性双测试要求与文档审查保证 Agent 依赖的检查不会静默失效风格规则让变更可 lint、可测试、可审计。对任何要触碰 Firstmate 共享受跟踪材料的人来说它既是检查清单也是仓库自身如何维护自身的源码级实现说明。赞分享【免费下载链接】firstmateTalk to one agent. Ship with a crew.项目地址https://gitcode.com/gh_mirrors/fi/firstmate点击查看免费下载相关推荐ClawX 能力所有者解析规则插件发现与激活之间的单一所有者约束ClawX 能力所有者解析规则插件发现与激活之间的单一所有者约束 导读 本文围绕 ClawX 仓库 harness 规范体系中名为 capability ow人工智能AI 应用桌面应用交互助手Gentle-AI 仓库地图包所有权、代码放置规则与贡献者导航指南Gentle AI 仓库地图包所有权、代码放置规则与贡献者导航指南 这篇技术指南以 Gentle AI 官方仓库地图 docs/codebase/reposIronClaw 类型放置规则Type Placement一份类型只有唯一定义并由其契约所有者持有IronClaw 类型放置规则Type Placement一份类型只有唯一定义并由其契约所有者持有 导读 本文讲解 IronClaw 工作区内部的一项关人工智能AI 应用交互助手AI Agent上一篇ant-design Progress.Circle 圆形进度条实战从官方 Demo 到源码级实现解析下一篇Trello Desktop版本更新历史从0.1.0到最新版本的功能演进创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
