如何让仓库对 AI 智能体友好：一份实用审计清单

An agent-ready repo is not a repo covered in AI decorations. It is a repo where the next worker can answer basic questions quickly: where does this behavior live, what should not change, how do I test it, and what evidence proves the job is done?

That worker might be Copilot. It might be Claude Code. It might be Cursor, Codex, or a human on their second day. The same fixes help all of them.

Key takeaways: what makes a repo agent-ready

• Root repository map: A concise table mapping folders to their architectural roles stops agents from guessing and editing legacy files.
• Explicit verification commands: Fast, reproducible checks (typecheck, lint, unit test) that agents can run autonomously to validate patches.
• Strict safety boundaries: Explicitly documenting files agents must never touch (auth, billing, migrations, production configs).
• Portable instructions (AGENTS.md): A vendor-neutral markdown file at repository root shared across Cursor, Claude Code, Copilot, and Codex CLI.

The checklist below is a practical baseline, not a claim that documentation automatically improves agent accuracy. Its purpose is to make context discoverable, constraints reviewable, and verification repeatable. The final section describes a controlled task you can use to test whether the changes help in your own repository.

1. Put the repo map at the root

Agents start by searching. If your repository does not explain its own shape, the agent will infer the map from filenames. That works until it finds three plausible folders and chooses the wrong one.

Add a short root-level map in AGENTS.md, README.md, or REPO_MAP.md:

# Repo Map

- src/pages: route-level pages and page-specific styles.
- src/components: shared Astro components.
- src/content/blog: markdown posts loaded by content collections.
- src/data: typed resource lists and reusable page data.
- public: static assets plus Cloudflare Pages headers and redirects.

## Common Commands

- npm run dev: local development server.
- npm run build: production build and content validation.

Keep it short enough that a human will maintain it. A stale repo map is worse than no repo map because it gives wrong answers with authority.

2. Name the risky surfaces

Every repo has areas where casual edits are expensive: auth, billing, migrations, public API contracts, security policy, analytics, SEO metadata, deploy scripts, data deletion, and anything with customer-visible side effects.

Do not make the agent discover those by accident. Name them.

## Risky Surfaces

- Authentication and session behavior require explicit approval.
- Public URL changes require redirects and sitemap review.
- Billing, invoices, and entitlement logic require test evidence.
- Database migrations must not be generated without a task brief.

This is not a substitute for code review. It is a speed bump before the agent creates a diff you immediately have to reject.

3. Write down the verification commands

Agents need to know what counts as done. If the test command is tribal knowledge, the agent may skip it, run the wrong command, or run the entire suite when a narrow test would have found the issue in ten seconds.

Put commands near the top of the repo instructions:

## Verification

- Content, route, or Astro component changes: `npm run build`.
- Unit-level TypeScript changes: `npm test -- <affected area>`.
- Formatting-only changes: name the formatter used.
- If a command cannot run locally, summarize the blocker and remaining risk.

The last bullet matters. Agents are very good at sounding finished. Make them distinguish “passed” from “not run.”

4. Add feature notes where the code has invariants

Some behavior needs local context. A root repo map cannot explain every invariant without becoming unreadable. For that, add small, ordinary Markdown notes beside important modules. FEATURE.md is a local convention, not a cross-tool standard; use a name your contributors can discover and document it from the root map.

src/features/billing/
  FEATURE.md
  billing-policy.ts
  billing-policy.test.ts

The note can be simple:

# Billing Feature Notes

Purpose: Subscription state, invoices, and entitlement checks.

Invariants:

- Never grant paid access from cached entitlement data alone.
- Trial extension changes require an audit log event.
- Provider webhooks must be idempotent.

Fast checks:

- npm run build
- npm test -- billing-policy

Agents read nearby files. Put the context near the code you expect them to change.

5. Collapse duplicate entry points

Agents are drawn to names. If your repo has auth.ts, auth-utils.ts, session.ts, session-helper.ts, and new-auth.ts, the model has to guess which one is canonical.

You do not always need a refactor. Sometimes a short comment, README note, or deprecation marker is enough:

// Canonical session validation entry point. Do not call legacy session helpers from new code.
export async function validateSession() {
  // ...
}

Better yet, delete old helpers when they are truly dead. Agent readiness is often just codebase hygiene with a brighter flashlight.

Search for duplicate nouns as well as duplicate code. Files named utils.ts, helpers.ts, common.ts, and shared.ts may all be legitimate, but they give an unfamiliar worker several plausible homes for the next helper. Domain terms such as user, account, member, and profile need explicit boundaries when they are not interchangeable.

A short glossary or module-level note can be enough:

## Domain terms

- Account: the billing and authentication boundary.
- Member: a person's role inside one workspace.
- Profile: editable display information for a person.

The goal is not to remove every synonym. It is to explain distinctions that the code alone does not make obvious.

6. Make contracts executable

Prose helps, but executable contracts help more. Agents can follow types, schemas, tests, and examples with less ambiguity than they can follow a paragraph in a wiki.

Useful contracts include:

• Zod schemas for API request and response shapes.
• TypeScript interfaces exported from canonical modules.
• Snapshot-free tests that name behavior clearly.
• Example fixtures stored near the behavior they prove.
• Route tests that lock down public URLs and redirects.

These executable boundaries serve dual duty. They block agents from guessing incorrectly, and many of them can be exposed directly to the agents through an MCP schema inspector later.

For example:

export const createWorkspaceResponse = z.object({
  workspaceId: z.string(),
  slug: z.string(),
  defaultRole: z.enum(["viewer", "developer", "admin"]),
});

That schema tells the agent more than “return the workspace data” ever will.

Test names are part of this contract. A test called works contributes almost no context. A test called preserves_return_url_when_session_refreshes tells a contributor which behavior must survive the edit. Improve names around the behavior you touch rather than launching a repository-wide rename.

7. Replace vague rules with observable rules

Bad instruction:

- Be careful with production code.

Better instruction:

- Do not change public API response shapes unless the task explicitly asks for it.
- For auth, billing, and migrations, ask before expanding scope.
- Preserve existing redirects when changing page URLs.

Agents cannot execute vibes. They can execute boundaries.

8. Keep examples close to patterns

If every new page should follow a specific structure, point at an existing page. If every setup guide has the same frontmatter shape, link the canonical example. If every job needs a test beside it, show where one already exists.

## Local Patterns

- New Astro pages should follow `src/pages/about.astro` for document structure.
- New blog posts must match the schema in `src/content.config.ts` and a current article in `src/content/blog/`.
- New resource entries should be added in `src/data/resources.ts`.

This is more useful than explaining the entire style guide. Agents are pattern matchers. Give them the pattern you actually want copied.

9. Add a final-summary contract

Review gets easier when the agent tells you what happened in a consistent shape.

## Final Summary

When done, include:

- What changed.
- Files touched.
- Commands run and whether they passed.
- Anything not verified.
- Risks or follow-up work.

That summary is not ceremony. It is review compression. A good summary lets the human decide where to inspect first.

10. Test the instructions with a real task

Do not judge repo readiness by how polished the docs look. Run a bounded task and watch the behavior.

Ask these questions afterward:

• Did the agent inspect the right area first?
• Did it stay inside the requested scope?
• Did it reuse existing patterns?
• Did it run the right checks?
• Did it summarize uncertainty honestly?
• Did the diff surprise you in a bad way?

Record the result instead of deciding from one impression. Note whether the agent found the intended module, changed only allowed files, reused the canonical entry point, and ran the expected check. Repeat the same task shape before and after the repository changes if you want a meaningful comparison.

One task is not a benchmark, and a successful run does not prove every agent will behave the same way. It does reveal obvious discovery and verification failures that documentation can address.

The minimum viable checklist

If you only have an hour, do this:

1. Add AGENTS.md with repo map, risky surfaces, commands, and summary expectations.
2. Add one FEATURE.md beside the riskiest active feature.
3. Mark the canonical entry point for one confusing module.
4. Add or document the fastest relevant test command.
5. Run one small agent task and update the instructions from what failed.

That hour will not make the repo perfect. It will make the next agent run less dependent on luck.

Agent-ready is human-ready

The funny thing about agent-ready repositories is that they rarely contain anything exotic. They contain maps, commands, boundaries, contracts, examples, and tests. That is the same material a human needs to move safely.

Agents expose ambiguity because they do not have your team’s private memory. That can be annoying, but it is also useful. Every time an agent guesses wrong, ask what signal would have helped a new developer guess right.

Then put that signal in the repo.