用途
Agent-Native Repo Playbook 用于审计和改进代码仓库，使其适配一种“智能体原生”的工作方式：单人开发者、高权限、由人类设定意图、由智能体完成实现。它的最终目标是让仓库成为一个可靠的执行框架（harness），使一个对项目没有上下文的“冷启动”智能体，能够把清晰的意图一路推进到实现、验证、面向产品的证明、清理和汇报，而只需极少的人工协调。
运行模型
手册定义了明确的人机分工：
- 人类负责意图、优先级、验收标准、品味和重大风险。
- 智能体负责代码、测试、文档、工具、验证、清理和日常跟进。
- 反复出现的困惑或失败被视为框架缺陷，应当修复，而不是重复提示。
模式与参考文件
使用前始终先阅读 references/best-practices.md，然后按任务类型只加载对应的参考文件：
- 评分卡：当需要评分、基准、就绪度或成熟度评估时，阅读 references/harness-readiness-rubric.md。
- 指南：当评审或修改根级或嵌套的 AGENTS.md、STRUCTURE.md 或同类指南时，阅读 references/agents-md-best-practices.md。
- 文档：当评审或修改文档位置、架构文档或文档新鲜度规则时，阅读 references/docs-structure-and-maintenance.md。
手册区分两种操作模式：
- 推荐模式：用于审计、评审、评分或报告请求，只给出建议，不编辑仓库。
- 实现模式：仅当用户明确要求变更或实现时才编辑仓库。
工作流程
- 阅读仓库的事实来源与执行面：根级和相关嵌套指南；结构图、架构、参考、决策和活跃追踪器；工作流、构建/测试命令、scripts/check-fast.sh 和完整检查；相关的本地技能、工具、日志和产品检查路径。
- 尊重本地契约：仓库指南和既有架构优先于本手册的默认设置。
- 追踪从发现到变更、静态验证、产品或服务证明、清理、汇报和恢复的完整流程，找出冷启动智能体会卡住、猜测或需要反复人工介入的地方。
- 优先处理能减少协调成本、或能把重复错误转化为机械反馈的缺口。倾向于小而可用的护栏，而非更多政策文字。
- 匹配请求的动作：审计时只推荐不编辑；实现时做出所请求的变更、更新持久文档，并按风险比例进行验证。
- 每个主要发现或完成声明都要有具体证据支撑，例如文件、命令、日志、截图、产物、冒烟测试等。
输出
对于推荐式审计，返回：
- 哪些做法有效。
- 最高杠杆的缺口。
- 指南审计：仅当根级指南在范围内时，给出保留 / 移动 / 删除建议。
- 建议的下一步：立即、近期和以后。
- 证据：具体文件路径和相关命令。
对于评分卡，额外给出 references/harness-readiness-rubric.md 要求的总体评分和维度表。
对于实现，先给出结果，并包含已运行的检查、相关的产品或服务证明、跳过的验证及原因，以及任何削弱证明的剩余框架缺口。
规则
- 保持“人类设定意图、智能体编写和维护实现及仓库文档”的模型。
- 优先使用自主反馈循环、确定性工具和机械护栏，而非提醒。
- 保持根级指南简洁，将其作为路由器；仅在本地边界规则有实质差异处添加嵌套指南。尊重 STRUCTURE.md 等有意的替代方案。
- 使用仓库的文档契约。若不存在，优先将系统形态放在 docs/architecture/，将精确实现事实放在 docs/references/。
- 对于带有规范定位技能的多仓库系统，将跨仓库归属和路由保留在那里，而将实现细节留在所属仓库。不要在技能中重复架构手册。
- 在受信任的仓库中倾向于直接、可恢复的工作流。没有具体需求或明确请求时，不要添加团队式审批、分支仪式或集中式政策层。
- 除非用户明确要求，不要引入集中式审计脚本。
- 使用 $project 维护持久项目追踪器，并按仓库指南关闭或归档已完成的追踪器。
资源
- references/best-practices.md：规范操作原则和默认优先级。
- references/harness-readiness-rubric.md：评分卡维度和输出契约。
- references/agents-md-best-practices.md：指南质量门和保留 / 移动 / 删除模型。
- references/docs-structure-and-maintenance.md：轻量文档契约和维护规则。
适用场景与限制
该手册适用于希望让智能体在仓库中自主完成实现与验证的单人开发者或高权限工作流，尤其适合需要审计仓库就绪度、改进 AGENTS.md 等指南、整理文档结构、或评估智能体协作成熟度的场景。其限制在于：它面向单人开发者、高权限、智能体原生的特定工作流，不适用于需要团队式审批或集中式政策层的场景；具体评分维度、命令和脚本内容需参考对应参考文件，本资料未提供这些文件的详细内容。