Back to Details

shunk031-manage-agent-guidance

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Manage Agent Guidance

管理Agent指导内容

Keep each durable instruction in one source of truth and expose it through thin adapters.
将每条持久化指令保存在单一可信源中，并通过轻量适配器对外暴露。

Workflow

工作流程

  1. Read all applicable guidance before proposing a change.
  2. Classify each rule as user-level, repository-level, subtree-level, task-only, custom-agent, or skill guidance. Treat a filename named in the request as a hypothesis, not as the confirmed target. Put behavioral rules shared across repositories at the user level, configuration and procedures for one repository at the repository level, and rules for a specific directory subtree at the subtree level.
  3. Locate the source of truth by inspecting higher-level instructions, managed sources, symlinks, imports, wrappers, and adapters. Edit that source for the classified scope instead of duplicating a rule across repository-level AGENTS.md files.
  4. Build a consumer map for every candidate overlap: record each canonical source, rendered path, actual reader, co-loaded higher-scope guidance, and standalone portability requirement. Matching wording does not prove redundant ownership, and different scope labels do not prove independent consumption. Decide separately for each consumer path instead of keeping or removing every copy as a group.
  5. Search current guidance and skills for an existing owner. Strengthen that owner instead of adding a duplicate.
  6. Before drafting or editing, report the evidence for scope, source of truth, existing ownership, and the consumer map. Name the inspected files, adapters, actual readers, and matching owner rule; if any are unknown, state what remains unverified.
  7. Follow the scope-classification and source-of-truth rules above. Put concise cross-task invariants in the applicable 
    AGENTS.md
    and specialized repeatable procedures in an existing relevant skill. Create a skill only when no existing owner fits and the procedure is substantial and reusable.
  8. Before committing or creating a PR, review the diff for each added instruction to confirm that its location matches its scope and that it does not duplicate higher-scope guidance; move it to the correct source of truth when the scope does not match, or ask before changing external state when it is unclear.
  9. Review the final diff for scope mismatch, duplication, secrets, transient facts, and adapter drift.
Do not draft or edit until steps 2–6 are complete. When evidence is unavailable, report the missing sources and propose the investigation instead of defaulting to the named file.
  1. 在提议修改前，阅读所有适用的指导内容。
  2. 将每条规则分类为用户级、仓库级、子目录级、仅任务级、自定义Agent或技能指导内容。将请求中提及的文件名视为假设，而非确认的目标文件。将跨仓库共享的行为规则放在用户级，单个仓库的配置和流程放在仓库级，特定目录子树的规则放在子目录级。
  3. 通过检查更高级别的指令、受管理的源文件、符号链接、导入项、包装器和适配器来定位可信源。针对已分类的范围编辑该源文件，而非在多个仓库级AGENTS.md文件中重复规则。
  4. 为每个可能存在重叠的候选对象构建消费者映射：记录每个规范源文件、渲染路径、实际读取者、共同加载的更高范围指导内容，以及独立可移植性要求。措辞匹配并不意味着归属冗余，不同的范围标签也不代表消费独立。针对每个消费者路径单独决策，而非批量保留或删除所有副本。
  5. 在当前指导内容和技能中搜索现有归属方。强化该归属方，而非添加重复内容。
  6. 在起草或编辑前，报告关于范围、可信源、现有归属及消费者映射的证据。列出已检查的文件、适配器、实际读取者及匹配的归属规则；若有未知项，说明尚未验证的内容。
  7. 遵循上述范围分类和可信源规则。将简洁的跨任务不变量放入适用的
    AGENTS.md
    ，将专门化的可重复流程放入现有相关技能中。仅当没有合适的现有归属方且流程具备实质性可复用性时，才创建新技能。
  8. 在提交或创建PR前，检查每条新增指令的差异，确认其位置与范围匹配，且未重复更高范围的指导内容；若范围不匹配，将其移至正确的可信源；若情况不明，在修改外部状态前先询问。
  9. 最终检查差异，确认是否存在范围不匹配、内容重复、机密信息、临时事实及适配器偏移问题。
在完成步骤2至6前，请勿起草或编辑内容。当证据不足时，报告缺失的源文件并提议开展调查，而非默认使用指定文件。

Persistence Quality

持久化质量

  • Persist only concise, actionable prevention that generalizes beyond the incident and states a reusable root-cause safeguard.
  • Exclude secrets, task-specific facts, transient state, incident narratives, and unverified assumptions.
  • Persistent guidance never references issue/PR numbers, migration tracking status, or other facts that expire. Guidance files are loaded indefinitely, but these facts have deadlines: the issue closes, the migration finishes, and the bare number becomes unresolvable outside its tracker — leaving future readers a rule they can neither verify nor act on. Record expiring facts in the issue tracker or a dated research note instead.
  • 仅持久化简洁、可操作的预防措施，需能推广至事件之外，并明确可复用的根本原因防护手段。
  • 排除机密信息、任务特定事实、临时状态、事件描述及未经验证的假设。
  • 持久化指导内容绝不能引用Issue/PR编号、迁移跟踪状态或其他会过期的事实。指导文件会被无限期加载，但这些事实有截止期限：Issue会关闭，迁移会完成，单纯的编号在跟踪器外无法解析——这会让未来的读者面对一条既无法验证也无法执行的规则。请将过期事实记录在Issue跟踪器或带日期的研究笔记中。

Instruction Migrations

指令迁移

Before assigning a destination, inspect code, adjacent configuration comments, tests, CI, schemas, and automation for an existing machine-enforced owner. Keep prose only when human or agent judgment remains and omission would materially change behavior. Treat incidents as reasons to improve enforcement, not permanent prose. When enforcement fully owns behavior, propose removal with concrete evidence and obtain approval rather than mapping it into 
AGENTS.md
or a new skill.
  1. Inventory every atomic rule in the source before deleting or compressing any section.
  2. Record one destination for every rule: always-on guidance, an existing skill, a custom agent, repository guidance, or an explicitly approved removal.
  3. Build a reverse index from each normalized rule to every destination and related guidance file, not only from the source to its proposed destination. Assign each rule exactly one authoritative owner, remove redundant copies, and record only intentional thin adapters as exceptions.
  4. For every approved removal, record the exact source requirement (ID and text) and a non-empty rationale in the static migration contract and migration deliverable.
  5. For every intentional thin adapter, record its exact path, exact minimal text or syntax, authoritative owner/destination, and why the exception is necessary.
  6. Name the existing owner skill or guidance file for every mapped destination; a category label alone is insufficient.
  7. Preserve examples when they disambiguate behavior that prose alone does not reliably produce.
  8. Add or update a static migration contract that fails when a mapped requirement disappears or a known duplicate remains outside its authoritative owner.
  9. Add behavioral evals for the moved capability, but never treat model evals as proof that every source requirement was migrated.
  10. In the final reverse audit, scan every guidance path for duplicate ownership and confirm that only recorded thin-adapter exceptions remain.
  11. Present every proposed removal and its rationale to the user. Do not delete an unmapped or unapproved rule.
  12. When a migration description or plan is requested, output the source, destination, removal, adapter, and reverse-audit records concretely rather than merely saying they should exist.
在指定目标位置前，检查代码、相邻配置注释、测试、CI、模式及自动化流程，确认是否存在由机器强制执行的现有归属方。仅当仍需人工或Agent判断，且省略内容会实质性改变行为时，才保留文字说明。将事件视为改进强制执行机制的理由，而非永久保留文字说明。当强制执行机制完全管控行为时，需提供具体证据并获得批准后，再提议移除相关内容，而非将其映射到
AGENTS.md
或新技能中。
  1. 在删除或压缩任何章节前，清点源文件中的每条原子规则。
  2. 为每条规则记录一个目标位置：始终启用的指导内容、现有技能、自定义Agent、仓库指导内容，或经明确批准的移除操作。
  3. 构建从每条标准化规则到所有目标位置及相关指导文件的反向索引，而非仅从源文件到提议目标位置的索引。为每条规则分配唯一的权威归属方，移除冗余副本，仅将有意设置的轻量适配器作为例外记录。
  4. 对于每项获批的移除操作，在静态迁移契约和迁移交付物中记录确切的源要求（ID和文本）及非空的理由。
  5. 对于每个有意设置的轻量适配器，记录其确切路径、确切的最小文本或语法、权威归属方/目标位置，以及例外的必要性原因。
  6. 为每个映射的目标位置指定现有的归属技能或指导文件；仅用类别标签是不够的。
  7. 当示例能消除仅靠文字说明无法可靠传达的行为歧义时，保留示例。
  8. 添加或更新静态迁移契约，当映射的要求消失或已知副本未在其权威归属方之外保留时，契约应触发失败。
  9. 为迁移后的能力添加行为评估，但绝不能将模型评估视为所有源要求已完成迁移的证明。
  10. 在最终反向审计中，扫描所有指导路径以检查归属重复情况，确认仅保留已记录的轻量适配器例外。
  11. 向用户展示每项提议的移除操作及其理由。请勿删除未映射或未获批的规则。
  12. 当被要求提供迁移描述或计划时，需具体输出源文件、目标位置、移除操作、适配器及反向审计记录，而非仅说明这些内容应该存在。

Repository Validation

仓库验证

  • For work in this public dotfiles repository, run guidance evaluation locally through 
    prek
    .
  • In this public dotfiles repository, use 
    SKIP=agent-guidance-eval
    only for an emergency.
  • Never skip static validation in this public dotfiles repository.
  • For this public dotfiles repository, run real model evaluation locally, not in CI.
  • For this public dotfiles repository, CI may test the evaluation runner only with a fake 
    codex
    executable.
  • 在该公开dotfiles仓库中工作时，通过
    prek
    在本地运行指导内容评估。
  • 在该公开dotfiles仓库中，仅在紧急情况下使用
    SKIP=agent-guidance-eval
    。
  • 在该公开dotfiles仓库中，绝不能跳过静态验证。
  • 在该公开dotfiles仓库中，在本地运行真实模型评估，而非在CI中运行。
  • 在该公开dotfiles仓库中，CI仅可使用伪造的
    codex
    可执行文件测试评估运行器。

Repository Wiring

仓库配置

  • Keep repository conventions in the root 
    AGENTS.md
    ; do not repeat user-level rules there.
  • Make root 
    CLAUDE.md
    a relative symlink to 
    AGENTS.md
    , not a copied file or an import stub.
  • Keep repo-local skills at 
    .agents/skills/<name>/SKILL.md
    and expose them to Claude with a relative 
    .claude/skills
    symlink when required.
  • Keep lengthy shared custom-agent instructions in 
    ~/.agents/agents/<name>.md
    . Preserve tool-specific metadata in thin Claude or Codex wrappers that direct the agent to the shared source.
  • Keep private infrastructure, credentials, internal endpoints, and environment-specific launch configuration out of public guidance.
  • Do not introduce a Markdown parser or generator to duplicate shared instructions into TOML or Markdown until that mechanism is explicitly needed.
  • 将仓库约定保存在根目录的
    AGENTS.md
    中；请勿在此重复用户级规则。
  • 将根目录的
    CLAUDE.md
    设置为指向
    AGENTS.md
    的相对符号链接，而非复制文件或导入存根。
  • 将仓库本地技能保存在
    .agents/skills/<name>/SKILL.md
    ，并在需要时通过相对路径的
    .claude/skills
    符号链接向Claude暴露这些技能。
  • 将冗长的共享自定义Agent指令保存在
    ~/.agents/agents/<name>.md
    。在轻量的Claude或Codex包装器中保留工具特定元数据，以引导Agent访问共享源文件。
  • 将私有基础设施、凭据、内部端点及环境特定的启动配置排除在公开指导内容之外。
  • 在明确需要前，请勿引入Markdown解析器或生成器，将共享指令复制到TOML或Markdown中。