自定义指令该写什么：给编码智能体的仓库规则清单

A custom instructions file should hold repository facts an agent cannot infer: the repo map, scope rules, verification commands, the expected shape of a final answer, and the shortcuts that are forbidden. It should not hold personality, policy, or one-off task detail.

Custom instructions are where good agent workflows either become repeatable or turn into a junk drawer.

The idea is simple: write down the rules you want the coding agent to follow every time. The trap is also simple: once the file exists, everyone starts adding preferences, warnings, slogans, and one-off scars from the last bad pull request. The instructions get longer. The agent follows less of them. The team concludes that instructions do not work. If you are deciding which file should hold those rules, start with AGENTS.md vs copilot-instructions.md vs CLAUDE.md.

They can work, but only when they are short, specific, and attached to behavior the agent can actually perform.

What makes an instruction worth keeping?

Before adding a line, ask three questions:

1. Is this rule true for many tasks?
2. Can the agent observe whether it followed the rule?
3. Would a new developer benefit from the same guidance?

If the answer is no, the rule probably belongs somewhere else. Put one-off constraints in the task brief. Put broad architecture explanations in docs. Put formatting preferences in tooling. Put only durable operating rules in custom instructions.

Start with repo facts, not personality

Bad instruction:

- You are a senior engineer who writes clean, maintainable code.

Better instruction:

- Inspect existing patterns before adding new abstractions.
- Keep changes scoped to the files and behavior requested.
- Prefer feature-local helpers unless two or more features already need the same logic.

The first line flatters the model. The second set changes behavior.

Agents do not need to be told to be smart. They need to be told what matters in this codebase.

Include the repo map

The first useful section is a tiny map. Keep it factual.

## Repo Map

- src/pages: Astro page routes.
- src/components: shared UI components.
- src/content/blog: markdown posts loaded by Astro content collections.
- src/data: reusable typed content used by resource pages.
- public: static assets and Cloudflare Pages config files.

This prevents the agent from treating every file as equally likely. It also reduces the number of questions a human has to answer at the beginning of each task.

Include scope rules

Scope rules are more valuable than style rules. Most bad agent diffs are not bad because the function name was ugly. They are bad because the agent changed too much.

Good scope rules look like this:

## Scope

- Fix the requested problem at its root cause, but keep edits focused.
- Do not refactor unrelated modules while implementing a feature.
- Do not change public URLs, response shapes, or data models unless explicitly requested.
- Ask before expanding into auth, billing, migrations, or deployment behavior.

These rules tell the agent where freedom ends.

Include verification expectations

The agent needs to know what evidence you expect before it says the task is done.

## Verification

- Run the narrowest relevant test or build command after edits.
- For Astro content, route, and component changes, run `npm run build`.
- If a command fails, diagnose the failure before trying unrelated fixes.
- If verification cannot run, say exactly what was not verified.

This section prevents a common pattern: a cheerful final answer attached to untested code.

Include final-answer shape

A consistent final summary makes review faster.

## Final Response

Summarize:

- What changed.
- Commands run and results.
- Any remaining risk or skipped verification.

Do not ask for a novel. Ask for review evidence. The human can inspect the diff from there.

Include local style only when tooling cannot

Custom instructions are a poor replacement for formatters and linters. If Prettier, ESLint, TypeScript, tests, or a component library can enforce the rule, let tooling enforce it.

Still, some local style rules are worth writing because they affect architecture rather than whitespace:

## Local Style

- Use existing components before creating new ones.
- Keep page-specific CSS inside the Astro page unless another page already needs it.
- Use structured data helpers or typed data files instead of copying large arrays across pages.

Those rules tell the agent how the codebase wants to grow.

Name the forbidden shortcuts

Agents often take shortcuts that look reasonable in isolation. If your team has learned that a shortcut is dangerous, write it down.

## Do Not Do

- Do not silence TypeScript errors with `any` unless the task is explicitly about a boundary that cannot be typed yet.
- Do not add dependencies for small utilities already available in the platform.
- Do not delete tests to make a build pass.
- Do not change generated files manually.

Each line is concrete. Each line names an action.

Scope rules to where they apply

A single repo-wide instruction file makes everything global, which is usually wrong. A rule about blog frontmatter does not need to fire when an agent is editing a TypeScript helper.

Scoping mechanisms differ by product and surface. GitHub documents .github/instructions/*.instructions.md files with an applyTo glob in supported Copilot surfaces. Cursor documents Project Rules under .cursor/rules/ with rule metadata. Claude Code documents Agent Skills as packages of instructions and optional resources or scripts. Use the mechanism that the target surface currently supports instead of assuming the same discovery rules everywhere.

For example, a scoped Copilot rule for content edits:

---
applyTo: "src/content/blog/**/*.md"
---

- Match the existing frontmatter shape and field order.
- Internal links must use trailing-slash canonical URLs.
- Do not invent new pillars; reuse existing ones from other posts.

That rule is silent during component edits and loud during content edits, which is exactly the behavior you want.

Keep task instructions out

This does not belong in custom instructions:

- For the about page canonical issue, update redirects and JSON-LD.

That is a task brief. It should live in the chat, issue, ticket, or prompt for that specific run. If you put it in durable instructions, future tasks inherit stale context.

Better task brief:

goal: Align about page canonical signals.
allowed_changes:
  - src/components/BaseHead.astro
  - src/pages/about.astro
  - public/_redirects
checks:
  - npm run build

When the task is done, the brief goes away.

Keep policy out unless it guides code

Some teams paste broad policy into instruction files. Security policy, accessibility policy, brand voice, compliance language, architecture principles. Some of that may matter, but most of it is too broad to guide an edit. If you have reference material that agents need to access occasionally, serve it through an MCP server instead of bloating the instruction file.

Bad:

- Follow our security policy.

Better:

- Do not log secrets, tokens, cookies, or authorization headers.
- Do not expose environment variables to client-side code.
- Treat auth and permission checks as security-sensitive; ask before changing their behavior.

Policy becomes useful when it turns into actions the agent can avoid or verify.

A minimum viable custom-instructions file

Here is a compact starting point:

# Agent Instructions

## Repo Map

- src/pages: route-level pages.
- src/components: shared UI components.
- src/content/blog: markdown posts.
- src/data: reusable content data.
- public: static assets and deploy config.

## Working Rules

- Inspect existing patterns before editing.
- Keep changes scoped to the requested behavior.
- Do not change public URLs, API shapes, auth, billing, migrations, or deploy behavior without explicit approval.
- Prefer existing helpers and components before adding new abstractions.

## Verification

- Run the narrowest relevant check after edits.
- For Astro content, route, or component changes, run `npm run build`.
- If a check cannot run, state what remains unverified.

## Final Summary

- Say what changed.
- List checks run and results.
- Name any remaining risk.

That is enough. Add more only after a real agent run proves a rule is missing.

Good instructions age from use

The best instruction files are not written in one heroic sitting. They are grown from repeated mistakes.

When an agent makes a bad change, ask:

• Was the correct rule already written?
• Was it specific enough?
• Was it in the file this tool actually reads?
• Was this a durable rule or only a task-specific constraint?

If the rule was missing and likely to matter again, add it. If the rule existed and the agent ignored it, make it more observable. If the rule mattered only once, leave it out.

Custom instructions are not there to make agents perfect. They are there to make the predictable mistakes less predictable. That is a humble goal, but it is the one that pays rent in real repositories.

When you are ready to turn this into a file, use the custom instruction templates and keep the first version shorter than you think it needs to be.