【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载导读本文围绕 learn-harness-engineering 仓库中日文版 AGENTS.md 模板docs/ja/resources/openai-advanced/repo-template/AGENTS.md展开讲解如何为长时间运行的编码 Agent 设计一份短而准的 AGENTS.md它不作为巨型指令转储而是充当指向仓库各系统文档的路由层配合启动工作流、路由映射、工作契约、完成定义与会话结束例程让 Agent 每次会话都能以一致状态启动、在边界内工作、凭可执行证据收尾。读完本文你将掌握该模板的完整设计骨架并看到它在 harness-creator skill 模板与projects/project-01/solution/AGENTS.md实际项目中的落地形态。一、为什么 AGENTS.md 必须是路由层而不是指令转储模板开篇即点明核心设计哲学このリポジトリは長時間実行されるコーディングエージェントの作業に最適化されています。このファイルは短く保ち、巨大な指示のダンプではなく、記録のシステム文書へのルーティング層として使用してください。翻译过来就是仓库是为长时间运行的编码 Agent 优化的AGENTS.md 应保持简短不是巨型指令堆而是通向记录系统system of record文档的路由层。这与本仓库课程的论证一脉相承。docs/ja/lectures/lecture-04-why-one-giant-instruction-file-fails/专门讨论为什么单个巨型指令文件会失败把全部规则塞进一个文件会稀释 Agent 的注意力、超过上下文预算、且难以增量维护。SKILL.md 中 Harness Creator 的设计规则也明确写着Keep the root instruction file short: routing and invariants, not a full manual.根指令文件保持精简只放路由与不变式而非完整手册。Put project facts in project docs, not in the skill.项目事实放进项目文档不要堆进 skill 文件。因此 AGENTS.md 的正确职责只有三件事路由告诉 Agent 要看系统状态去哪个文件、要看设计决策去哪个文件不变式跨会话恒成立的硬规则工作契约、完成定义生命周期钩子启动前做什么、结束时做什么。而架构细节、质量评分、产品规格等项目事实一律下沉到独立文档由路由映射表索引。二、スタートアップワークフロー写代码前的 7 步启动路径模板要求 Agent 在修改任何代码之前按序完成以下步骤这是防止状态不一致就开工的第一道闸门pwdでリポジトリルートを確認する —— 用pwd确认当前位于仓库根目录ARCHITECTURE.mdを読む —— 读取架构文档掌握当前系统映射与严格依赖规则docs/QUALITY_SCORE.mdを読む —— 读取质量评分确认哪个领域/层最薄弱docs/PLANS.mdを読み、作業中のアクティブプランを開く —— 读取计划文档打开正在进行的活动计划docs/product-specs/の関連するプロダクト仕様を読む —— 读取相关产品规格標準ブートストラップと検証パスを実行する —— 运行仓库标准引导与验证路径ベースライン検証が失敗している場合、スコープを追加する前にベースラインを修復する ——若基线验证失败先修复基线再谈新增范围。第 7 步是整条工作流的分水岭它把环境健康置于功能开发之上杜绝 Agent 在破损基线上叠加新改动从而避免失败堆失败。仓库中的对应实现init.sh 标准验证路径模板第 6 步所说的标准引导与验证路径在 harness-creator 模板 中落成了一个可复用的init.sh。它的关键设计包括set -e任何一条验证命令失败立即退出让基线问题立刻显形包管理器自动探测按pnpm-lock.yaml→yarn.lock→bun.lock/bun.lockb→ 默认npm的顺序识别项目所用的包管理器再执行对应安装命令npm scripts 探测式执行用node -e读取package.json的scripts按check→typecheck→type-check的优先级运行类型检查随后依次尝试lint、test、build多语言支持对pyproject.toml/requirements.txt跑pytest与compileall对go.mod跑go test对Cargo.toml跑cargo test对pom.xml/build.gradle/*.csproj分别走 Maven/Gradle/dotnet友好收尾验证完成后打印 Next steps提醒 Agent 去读feature_list.json、只挑一个未完成功能、实现后重新验证再宣称完成。实际项目中的范例可见 projects/project-01/solution/AGENTS.md其启动规则同样要求先读本文件 → 读docs/ARCHITECTURE.md→ 读docs/PRODUCT.md→ 跑bash init.sh→ 读feature_list.json且明确If it fails, fix build errors before proceeding失败就先修再继续。三、ルーティングマップ一份索引式文档清单模板用一张路由映射表把何时该读哪个文件固化成了机器可执行的查表逻辑路由目标角色ARCHITECTURE.md域映射domain map、分层模型layer model、依赖规则dependency rulesdocs/design-docs/index.md设计决策与核心信念design decisions core beliefsdocs/product-specs/index.md当前产品行为与验收标准acceptance criteriadocs/PLANS.md计划的完整生命周期与执行计划策略docs/QUALITY_SCORE.md产品域与各层的健康度healthdocs/RELIABILITY.md运行时信号、基准benchmark、重启预期docs/SECURITY.md密钥、沙箱、数据、外部动作的规则docs/FRONTEND.mdUI 约束、设计系统规则、可访问性检查这张表的本质是**记录系统的目录**Agent 不需要靠记忆或聊天历史猜测项目状态任何时刻都能按表定位到权威来源。这与 SKILL.md 提出的五子系统模型skills/harness-creator/SKILL.md严格对应子系统最小产物用途Instructions指令AGENTS.md/CLAUDE.md启动路径、工作规则、完成定义State状态feature_list.json、progress.md当前功能、状态、证据、下一步Verification验证init.sh或文档化命令Agent 宣称完成前必须运行的测试/检查Scope范围功能依赖与完成标准防止越界与半成品Lifecycle生命周期session-handoff.md、会话结束例程让下一会话可重启路由映射表中的每个文档都是这五个子系统在记录系统中的落点。四、ワーキングコントラクトAgent 必须遵守的六条工作契约模板以契约条款形式定义了 Agent 日常工作的硬性约束每一条都直指本仓库课程中反复出现的 Agent 失败模式一度に一つの境界付けられたプランまたはフィーチャースライスから作業する—— 一次只做一个有边界的计划或功能切片。对应one active feature设计规则SKILL.md防止 Agent 同时推进多个任务导致上下文混乱。コードの検査だけで作業完了とマークしない。実行可能な証拠が必要である—— 仅看过代码不算完成必须提供可执行证据。这对应课程 lecture-09-why-agents-declare-victory-too-earlyAgent 过早宣布胜利与 lecture-10-why-end-to-end-testing-changes-results端到端测试改变结果证据必须是实际运行验证命令的输出而不是看起来没问题的推断。動作を変更した場合、同じセッションで対応するプロダクト、プラン、または信頼性の文書を更新する—— 改了行为就在同一会话内更新对应的产品/计划/可靠性文档。这防止代码改了、文档没改的漂移。繰り返しのレビューフィードバックが見られた場合、チャットで再説明するのではなく、機械的なルール、チェック、またはリンターに昇格させる—— 反复出现的评审意见要升级为机械化规则/检查/链接器而不是每次在聊天里重新解释一遍。这是把知识沉淀进仓库而非会话的关键机制。生成された素材はdocs/generated/に、ソース参照はdocs/references/に配置する—— 生成物放docs/generated/源引用放docs/references/用目录结构区分机器产物与人工参考。このファイルを肥大化させるのではなく、小さく最新の文書を追加することを優先する—— 优先新增小而新的文档而不是让本文件膨胀再次呼应路由层而非指令转储的哲学。落地feature_list.json 作为状态记录系统契约中状态的机器化承载者是feature_list.json。其 JSON Schemaskills/harness-creator/templates/feature-list.schema.json定义了每个功能条目的结构id唯一标识强制^feat-\d$格式如feat-001name、description功能名称与行为描述dependencies必须先完成的前置功能 ID 数组——这是范围控制的基础status枚举not-started/in-progress/blocked/doneevidence状态为done时记录的验证证据。在 projects/project-01/solution/AGENTS.md 中可以看到它的实际用法每个功能有pass/fail/not-started三种状态实现后更新为pass并附证据被阻塞则标fail并写明原因且永不删除功能条目——删除即丢失历史记录。五、完了の定義完成 五条全部满足模板给出了一套可判定的完成定义Definition of Done杜绝 Agent 的我感觉完成了一项变更只有在以下全部成立时才被视为完成ターゲット動作が実装されている —— 目标行为已实现必要な検証が実際に実行された —— 必要验证确实被执行强调实际运行而非假设証拠が関連するプランまたは品質文書にリンクされている —— 证据已链接到相关计划或质量文档影響を受ける文書が最新の状態である —— 受影响的文档已保持最新リポジトリが標準スタートアップパスからクリーンに再起動できる —— 仓库能通过标准启动路径干净重启。对比模板版 AGENTS.mdskills/harness-creator/templates/agents.md中的 checklist可以看到同一逻辑的更轻量表达- [ ] Target behavior is implemented - [ ] Required verification actually ran (tests / lint / type-check) - [ ] Evidence recorded in feature_list.json or progress.md - [ ] Repository remains restartable from standard startup path两条规则殊途同归实现 验证 证据 文档同步 可重启五者缺一不可。第 5 条尤其重要——它把完成与下一会话能否无缝继续绑定这正是课程 lecture-12-why-every-session-must-leave-a-clean-state每个会话必须留下干净状态所讨论的核心。六、セッションの終了结束会话前的 5 步例程模板要求 Agent 在结束会话前按序执行アクティブな実行プランを更新する—— 更新活动执行计划ドメインやレイヤーに意味のある変更があった場合、docs/QUALITY_SCORE.mdを更新する—— 若领域/层有实质变化更新质量评分債務を先送りした場合、docs/exec-plans/tech-debt-tracker.mdに新しい債務を記録する—— 若延期了技术债在技术债追踪器中登记適切なタイミングで終了したプランをdocs/exec-plans/completed/に移動する—— 将适时结束的计划移入已完成目录次のアクションが明確な再起動可能な状態でリポジトリを残す—— 让仓库处于下一步动作明确、可重启的状态。这套例程的核心目标是下一个会话打开仓库时不需要任何口头交接也能知道现在做到哪、接下来做什么。会话产生的所有认知增量——计划状态、质量评分、技术债、完成记录——都必须写回记录系统而不是留在 Agent 的上下文窗口里上下文窗口在会话结束后即丢失这正是 lecture-05-why-long-running-tasks-lose-continuity 讲的问题。配套状态文件progress.md 与 session-handoff.md仓库模板提供了两个配套文件支撑可重启状态progress.md 模板会话连续性日志包含当前状态最后更新时间、活动功能 ID、已完成/进行中/下一步清单、阻塞与风险、决策记录含背景与被否决方案、本次会话修改的文件、完成证据测试/类型检查/手动验证的命令与输出以及给下一会话的笔记。session-handoff.md 模板面向多会话任务的交接单包含当前目标、本会话完成项、验证证据表格检查项/命令/结果/备注、文件变更、决策、阻塞与风险以及下一会话启动清单读 AGENTS.md → 读 feature_list.json 与 progress.md → 复查交接单 → 编辑前先跑 init.sh。两者分工progress.md是持续的会话日志session-handoff.md是会话间的接力棒。实际项目中 projects/project-01/solution/claude-progress.md 即是前者的真实落地。七、模板在 harness-creator skill 中的完整工作流将本文讨论的 AGENTS.md 模板放入更大上下文看它是 Harness Creator skill 五子系统中的Instructions 子系统与 Statefeature_list.json/progress.md、Verificationinit.sh、Scope依赖与完成标准、Lifecyclesession-handoff.md共同构成一套完整的 harness。Skill 提供了配套自动化# 创建 harness本地仓库 node skills/harness-creator/scripts/create-harness.mjs --target /path/to/project # 审计现有 harness输出五子系统评分 node skills/harness-creator/scripts/validate-harness.mjs --target /path/to/project # 生成可分享的评估报告 / 运行结构基准 node skills/harness-creator/scripts/render-assessment-html.mjs --target /path/to/project node skills/harness-creator/scripts/run-benchmark.mjs --target /path/to/project --html /path/to/report.html其中create-harness.mjs支持--agent-file CLAUDE.md、--package-manager npm|pnpm|yarn|bun、--commands cmd one,cmd two、--force等选项会按 agents.md 模板 生成一份带占位符的 AGENTS.md。Skill 的设计规则与本文模板完全一致根指令文件只放路由与不变式、验证命令显式可运行、要求证据后才标记完成、一次只激活一个功能、优先追加状态文件而非依赖聊天历史、脚本不隐藏破坏性行为覆盖需用户明确批准。八、总结把 AGENTS.md 当作会话操作系统的路由层这份日文版 AGENTS.md 模板的完整价值可以概括为一句话它把长时间运行 Agent 的可靠性从提示词技巧转译成了仓库结构约定。启动工作流保证每次会话从一致基线出发路由映射让记录系统可被机器定位工作契约约束行为边界完成定义把完成变成可判定的五元组会话结束例程确保认知增量全部落盘。五个部分环环相扣最终目标与模板结尾一致——次のアクションが明確な再起動可能な状態でリポジトリを残す留下下一步动作明确、可重启的仓库状态。如果要在自己的项目里实践这套设计可以直接复用仓库中的现成资产agents.md 模板本模板的英文轻量版、init.sh 模板、feature-list schema、progress.md 模板 与 session-handoff.md 模板再参考 project-01 的 solution 目录 看它们如何组合成一份真实可用的 AGENTS.md。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐Learn Harness Engineering 实战以 AGENTS.md 为路由层构建 OpenAI 风格的长时 Agent 仓库系统Learn Harness Engineering 实战以 AGENTS.md 为路由层构建 OpenAI 风格的长时 Agent 仓库系统 导读 本文基于以 AGENTS.md 为路由层的 Agent-First 仓库模板在 learn-harness-engineering 中构建可重启的 system-of-record 文档体系以 AGENTS.md 为路由层的 Agent First 仓库模板在 learn harness engineering 中构建可重启的 system of面向长期编码 Agent 的 OpenAI 风格仓库路由层learn-harness-engineering 高级仓库模板 AGENTS.md 实战解析面向长期编码 Agent 的 OpenAI 风格仓库路由层learn harness engineering 高级仓库模板 AGENTS.md 实战解析 本篇创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考