Repo-wide instructions with copilot-instructions.md

Start with the bluntest instrument, because it’s also the one that’s supported everywhere. A single file, .github/copilot-instructions.md, sitting at the root of the repo. It’s always on — Copilot reads it on every request in that repo, in every mode, with no setting to flip and no glob to match. One file, repo-wide, no ceremony. It’s supported across every surface Copilot runs in, from VS Code to JetBrains to GitHub.com to the cloud agent, which makes it the natural place for the conventions that should never be guessed.

Write down what Copilot kept getting wrong

Open orders-service and think back to the corrections you kept re-typing. That’s your raw material — not a style guide written from scratch, but the specific things Copilot missed that you had to fix by hand. For this repo, that was roughly:

• The sort idiom. When Copilot fixed the recent-orders ordering in chapter one, it reached for a different sort pattern than the rest of the codebase used, and you nudged it back. The repo has a convention; state it.
• How endpoints are structured — where validation runs, where the audit call goes, what an endpoint looks like when your squad writes one.
• That this service consumes shared-lib for validation, auth, and audit, and shouldn’t reinvent those helpers locally.

Create the file at .github/copilot-instructions.md and write those down as plain, direct instructions:

# Copilot instructions — orders-service

This is an order-management API (TypeScript/Node) owned by the Platform squad.
It consumes `shared-lib` for input validation, auth/permission checks, and audit logging.

## Conventions
- Sort collections using the existing sort helper in `src/lib/sort.ts`. Do not
  inline ad-hoc comparators.
- Every endpoint validates its input with the `shared-lib` validation helpers
  before doing any work. Never hand-roll validation.
- Emit audit events through the `shared-lib` audit helper, not by logging directly.
- New endpoints follow the structure in `src/routes/` — validate, authorize,
  act, audit, respond, in that order.

## Don't
- Don't reformat or reorganize files you weren't asked to change.
- Don't duplicate helpers that already exist in `shared-lib`.

Notice what this isn’t. It’s not a restatement of the TypeScript handbook or generic clean-code advice — Copilot already knows that, and padding the file with the obvious only dilutes the parts that matter. It’s the handful of things specific to this repo that Copilot got wrong and a teammate would have caught in review. That’s the bar, and the last lesson is entirely about holding to it.

See it work

With the file in place, give Copilot a task you’d have had to hand-hold before — say, “add an endpoint that lists pending approvals” — and read the first draft. The sort should already use the helper. The validation should already route through shared-lib. The audit call should already be there. You’re not correcting style anymore; you’re reviewing logic, which is where your attention is actually worth something.

When a draft still drifts, that’s not a failure of the mechanism — it’s feedback on the file. Add the missing convention and move on. Over a week the file converges on the handful of rules that actually keep your drafts mergeable.

One file, then what

The repo-wide file is the floor, and for many repos it’s enough. But you have a second repo with its own conventions, and — if you’ve taken another course on this site — you may already have written exactly the convention file Copilot needs, under a different name. That’s the next lesson, and it’s the best part of this chapter. The bridge — AGENTS.md and CLAUDE.md.