代理同步

人工智能 社区

技能解读

当前原文的自动摘译,尚未人工审校。

何时使用

创建 PR 之前 — 检查分支的更改是否需要 AGENTS.md 更新 PR 合并到主库之后 — 审核合并的更改是否使 AGENTS.md 文件过时 根据明确请求 — “AGENTS.md 文件是最新的吗?”

1. 确定差异

找出相对于基础分支发生了什么变化。该方法取决于上下文: 在功能分支上(PR 之前):与 main 进行比较 在合并到 main 之后:用户应指定要审核的 PR 或提交范围。使用合并提交或 PR 编号来获取差异: 显式检查:如果用户只是说“检查 AGENTS.md”,则与 main 进行比较

2. Map changes to AGENTS.md territories

每个 AGENTS.md 文件“拥有”它所在的目录和所有子目录(除非子目录有自己的 AGENTS.md)。通过从每个更改的文件中查找最近的 AGENTS.md 来构建相关 AGENTS.md 文件的列表。示例:对src/prefect/server/api/flows.py的更改归src/prefect/server/AGENTS.md所有(如果存在),否则为src/prefect/AGENTS.md。仅分析在其区域内至少有一个已更改文件的 AGENTS.md 文件。如果结构更改(新目录、移动的文件)影响它们记录的目录树,还包括父 AGENTS.md 文件。

3. Check for missing AGENTS.md files

在分析现有的 AGENTS.md 文件之前,请检查任何已更改的目录是否应该有自己的 AGENTS.md 但没有。 New AGENTS.md files should be rare.仅当目录同时具有以下两种情况时才推荐一个: 未来代理在编辑之前需要识别的真实所有权边界 隐藏约定、不明显的合同或无法通过阅读代码快速了解的重复出现的陷阱

4. Analyze each relevant AGENTS.md

AGENTS.md 文件形成一个层次结构 - 当代理加载任何文件时,所有祖先文件也会加载,从而创建一个 T 形视图(顶部的广泛上下文,代理工作的具体细节)。这对同步检查有两个影响: 最不常见的祖先规则:共享知识应该存在于覆盖所有需要它的路径的最浅 AGENTS.md 中。如果相同的事实出现在多个兄弟 AGENTS.md 文件中,请标记它 - 它应该移动到它们的父级。相反,如果父 AGENTS.md 包含仅适用于一个子目录的详细信息,建议将其向下移动。

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
人工智能
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@PrefectHQ · 未声明许可证
上下文用量评级
中等消耗
接入复杂程度
需简单配置
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 命令执行
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# AGENTS.md Sync

Detect when code changes make durable AGENTS.md guidance stale and produce a report with specific recommendations. Treat AGENTS.md files as operating manuals for future agents, not changelogs for recent diffs.

## When to use

- Before creating a PR — check if the branch's changes warrant AGENTS.md updates
- After a PR merges to main — audit whether merged changes left AGENTS.md files outdated
- On explicit request — "are the AGENTS.md files up to date?"

## Workflow

### 1. Determine the diff

Figure out what changed relative to the base branch. The approach depends on context:

- **On a feature branch (pre-PR):** diff against main
  ```bash
  git diff main...HEAD --name-status
  git diff main...HEAD
  ```
- **After a merge to main:** the user should specify which PR or commit range to audit. Use the merge commit or PR number to get the diff:
  ```bash
  gh pr diff <number>
  ```
- **Explicit check:** if the user just says "check AGENTS.md", diff against main

### 2. Map changes to AGENTS.md territories

Each AGENTS.md file "owns" the directory it lives in and all subdirectories (unless a child directory has its own AGENTS.md). Build a list of which AGENTS.md files are relevant by walking up from each changed file to find the nearest AGENTS.md.

Example: a change to `src/prefect/server/api/flows.py` is owned by `src/prefect/server/AGENTS.md` (if it exists), otherwise `src/prefect/AGENTS.md`.

Only analyze AGENTS.md files that have at least one changed file in their territory. Also include parent AGENTS.md files if structural changes (new directories, moved files) affect the directory tree they document.

### 3. Check for missing AGENTS.md files

Before analyzing existing AGENTS.md files, check whether any changed directories *should* have their own AGENTS.md but don't. New AGENTS.md files should be rare. Recommend one only when the directory has both:

- A real ownership boundary that a future agent needs to recognize before editing
- Hidden conventions, non-obvious contracts, or recurring pitfalls that cannot be learned quickly from reading the code

Look at the directories containing changed files. For each one that lacks an AGENTS.md, check:
1. **Ownership boundary**: Does this directory represent a responsibility shift with different contracts than its parent?
2. **Hidden knowledge**: Are there non-obvious patterns, invariants, conventions, or failure modes that a developer would not learn quickly from code?
3. **Durability**: Will this guidance still matter after the triggering PR is old news?
4. **Hierarchy fit**: Would this belong better in an existing parent AGENTS.md instead?

Directory size and sibling AGENTS.md files can be weak signals, but they are never sufficient on their own. Do not recommend a new AGENTS.md just because a directory has 5+ files, gained a new module, or has sibling directories with AGENTS.md files.

When the case is not high-confidence, do not create the file. Capture the possible update as a recommendation instead, with the missing evidence or question that would make it actionable.

When recommending a new AGENTS.md, use the Explore agent to read the directory's code and draft the file using this template:

```markdown
# <Module Name>

<One-sentence purpose statement.>

## Purpose & Scope

What this module does. Explicit responsibility boundaries.
What it does NOT do (prevents scope creep).

## Entry Points & Contracts

Key APIs, functions, classes that external consumers use.
Input/output contracts. Invariants that must hold.

## Usage Patterns

Canonical examples of correct usage.
"If you need to do X, here's how."

## Anti-Patterns

What NOT to do. Common mistakes. Each should be a real mistake, not hypothetical.

## Pitfalls

Non-obvious gotchas. Implicit assumptions.
"You'd think X, but actually Y because Z."
```

The initial content must be concise and durable. Do not include `[ASK]` placeholders, file lists, changelog context, or speculative guidance. If the hidden knowledge cannot be stated confidently, write a recommendation instead of creating the file.

### 4. Analyze each relevant AGENTS.md

AGENTS.md files form a hierarchy — when an agent loads any file, all ancestor files load too, creating a T-shaped view (broad context at the top, specific detail where the agent works). This has two implications for the sync check:

**Least common ancestor rule**: Shared knowledge should live at the shallowest AGENTS.md that covers all paths needing it. If the same fact appears in multiple sibling AGENTS.md files, flag it — it should move to their parent. Conversely, if a parent AGENTS.md contains detail that only applies to one child directory, suggest moving it down.

**Upward propagation**: When a child AGENTS.md changes (or a new one is created), check whether the parent needs updating — either to add a cross-reference to the new child, or to re-summarize what the child directory does. Parent nodes should summarize their children's responsibilities, not duplicate their details.

For each AGENTS.md in scope, read it fully, then compare its claims against the diff **and** the current source code. Look for these categories of issues:

**Accuracy** — claims in AGENTS.md that don't match the actual code, regardless of whether the diff caused the discrepancy:
- Described behaviors that don't match what the code actually does (e.g., "renews at 75% of duration" when it actually renews immediately then sleeps 75%)
- Function signatures or parameters listed that are wrong or incomplete
- Responsibilities attributed to the wrong layer or module
- Error handling or failure modes described incorrectly

For claims that are verifiable (specific behaviors, function signatures, which module does what), read the source file and confirm. Don't trust that existing AGENTS.md content was ever correct — it may have been wrong from the start.

**Signal density** — content that duplicates what's discoverable from code rather than surfacing hidden knowledge:
- Full function signatures that just repeat the code (the *contracts* and *gotchas* around those functions are the high-signal parts)
- Trivial usage examples that match what's in docstrings or is obvious from the API
- File-by-file directory listings that `ls` would show — the *layering concept* or *architectural invariant* matters, not the enumeration
- Content that a developer would learn in 30 seconds of reading the source

AGENTS.md should capture what's *not* visible in the code: invariants, hidden contracts, non-obvious failure modes, things that look one way but behave another.

A behavior discovered in one changed function is not AGENTS-worthy by default.
Promote it only if it exposes a subsystem-level editing rule, a cross-file
contract, or a recurring failure mode future agents need before choosing
which implementation to read. Otherwise prefer a code comment, docstring,
test name, or no documentation change.

If the same guidance is already present in nearby code comments, docstrings, or tests, AGENTS.md should usually not repeat it.

**Missing invariants** — implicit contracts the code relies on that aren't documented:
- Parallel implementations that must stay in sync (e.g., sync and async versions of the same module)
- Ordering requirements or sequencing constraints
- Singleton behaviors or shared mutable state
- Cleanup responsibilities and what happens when they're skipped
- "This looks stateless but actually depends on X"

**Structural drift** — the AGENTS.md describes an ownership boundary, durable package layout, or module responsibility that no longer matches reality:
- Directories or packages added/removed/renamed in a way that changes responsibility boundaries
- New architectural layers or cross-file contracts not mentioned
- Removed components still listed as active responsibilities

**Command drift** — documented commands that may no longer work or are incomplete:
- Build/test/run commands referencing changed entry points
- New tooling or scripts not mentioned

**Convention drift** — code patterns or conventions described in AGENTS.md that the diff contradicts:
- New patterns established by the changes that aren't documented
- Existing conventions the changes deprecate or replace

**Description drift** — prose descriptions that no longer accurately characterize the code:
- Component descriptions that miss new responsibilities
- Architecture notes that don't reflect refactoring

**Hierarchy drift** — content living at the wrong level in the AGENTS.md tree:
- Knowledge duplicated across sibling AGENTS.md files that should be in their parent (least common ancestor)
- Parent-level detail that only applies to one child directory
- Parent summaries of child directories that no longer match after changes

For each finding, check whether it's actually stale — read the current state of the filesystem (not just the diff) to confirm. A diff showing a new file, helper, flag, or one-off fix doesn't mean AGENTS.md is wrong if AGENTS.md intentionally omits that level of detail.

Only recommend or apply updates for high-confidence, lasting guidance:
- Architectural boundaries
- Non-obvious invariants
- Cross-file contracts
- Recurring failure modes
- Commands or conventions that future agents are likely to need

Do not document:
- One-off implementation details or temporary bug context
- Facts obvious from reading names, imports, or nearby code
- File lists or every new module
- Changelog-style summaries of the triggering diff
- Advice that only matters for the current PR

### 5. Produce the report

Output a concise report grouped by AGENTS.md file. For each file, list findings with:
- **What's stale** — the specific line or section
- **Why** — which change caused it
- **Suggested fix** — the concrete text to add, remove, or change

Format:

```markdown
## AGENTS.md Sync Report

### New AGENTS.md recommended: `src/prefect/utilities/`

This directory now owns a distinct retry protocol used by multiple callers, and contributors must preserve its ordering invariant. Suggested outline:
- Purpose and ownership boundary
- Ordering invariant that callers rely on
- Failure mode to test when changing it

### `src/prefect/server/AGENTS.md`

1. **[Accuracy]** Lease renewal described as "renews at 75% of duration" but code renews immediately then sleeps 75%
   - Caused by: incorrect from initial creation
   - Suggested fix: "renews immediately on entry, then sleeps for 75% of `lease_duration` between renewals"

2. **[Signal density]** Full function signatures duplicate the code — remove parameter lists, keep contracts
   - Suggested fix: Replace `concurrency(names, occupy=1, ...)` with `concurrency()` and describe the non-obvious behaviors instead

3. **[Missing invariant]** Sync and async implementations must stay in lockstep but this isn't documented
   - Suggested fix: Add "Any behavior change to `_asyncio.py` must be mirrored in `_sync.py`"

4. **[Structural]** New directory `src/prefect/server/events/` not listed in directory structure
   - Caused by: `src/prefect/server/events/` added in this branch
   - Suggested fix: Add `events/` to the directory listing with description

### `./AGENTS.md` (root)
No changes needed.
```

If nothing is stale, say so clearly — don't manufacture findings.

### 6. Offer next steps

After presenting the report, offer:
- **Apply fixes** — make the suggested edits directly
- **Create a follow-up PR** — if this is a post-merge audit, offer to create a branch and PR with just the AGENTS.md updates
- **Skip** — if the changes are minor or the user disagrees with the suggestions

## Reactive mode

Outside of diff-driven analysis, if during normal development you discover missing context that should be in an AGENTS.md, propose an addition. Signs of missing context:

- You spent nontrivial time reconstructing a durable invariant that could be a one-liner in AGENTS.md
- You hit a non-obvious error because of an undocumented constraint
- You discovered a cross-system dependency that isn't mentioned anywhere
- A code review caught something that AGENTS.md should have prevented

Propose additions like this:
```
I discovered that [finding]. This isn't in [path]/AGENTS.md.

Proposed addition to the [section] section:
> [concrete text to add]

Should I add this?
```

## Quality checks for new or updated AGENTS.md content

- **Compression**: Can any section be shorter without losing information?
- **Deduplication**: Does anything repeat what a parent AGENTS.md already says? If so, remove it and rely on the hierarchy.
- **Specificity**: Replace vague statements with concrete ones. Not "be careful with auth" but "place logic after the `require_*` call".
- **Target length**: 20-80 lines for new files. If longer, compress or write recommendations instead.

## Important guidelines

- Be conservative — only flag things that are genuinely wrong or missing. AGENTS.md files are intentionally concise and don't need to document every file.
- Don't suggest adding content that's obvious from the code itself. AGENTS.md captures non-obvious patterns, gotchas, and high-level structure. Equally, flag *existing* content that merely restates the code — full function signatures, trivial examples, and file enumerations are low-signal and should be trimmed or replaced with the hidden knowledge around them.
- Don't trust that existing AGENTS.md content was ever correct. Verify factual claims (behaviors, signatures, responsibility attribution) against the source code, not just against the diff. Content can be wrong from day one.
- Don't suggest stylistic rewrites. Focus on factual accuracy and signal density.
- When in doubt about whether something is stale, check the filesystem to confirm rather than guessing from the diff alone.
- Respect the existing level of detail in each AGENTS.md. If a file only lists top-level directories, don't suggest adding individual files.
- Look for undocumented invariants — parallel implementations that must stay in sync, ordering constraints, singleton behaviors, cleanup responsibilities. These are the highest-value additions because they're invisible in code and cause the most breakage when violated.

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。