--- title: "The complete AI coding agent setup for Claude Code and Copilot" slug: "ai-coding-agent-setup-guide" publishedAt: "2026-07-28T16:59:42.559Z" dateModified: "2026-07-28T16:59:51.039Z" canonical: "https://www.notesof.dev/ai-coding-agent-setup-guide" author: "Hieu (Chris) Pham" tags: ["ai-agents", "claude-code", "context-engineering", "github-copilot"] excerpt: "The files, context, and workflow that turn an AI coding agent into consistent, reviewable output — set up once, for both Claude Code and Copilot." --- # The complete AI coding agent setup for Claude Code and Copilot **TL;DR:** Hand an AI coding agent to fifteen engineers with no shared setup and you get fifteen ways of working, and output no reviewer fully trusts. **A shared instruction file, a layered context the agent loads on demand, and a workflow with a human check at every risky step turn that into consistent, reviewable output** — built once, and shown here for both Claude Code and GitHub Copilot, where the ideas are the same even when the file names are not. ## Why one shared setup beats fifteen private ones Drop an agent into a repository with no setup, and every engineer fills the gap their own way. One pastes the architecture into the chat each morning. Another lets the model guess and cleans up after it. A third keeps a private prompt nobody else has. None of it is wrong on its own — but together it means no two people get the same help from the same tool. That gap has a name and a fix. > **Instruction file** — a plain text file at the root of your repository that the agent reads automatically at the start of every session, so it begins each task already knowing your conventions instead of guessing. Share one instruction file and three things change at once. The agent gives consistent answers, so a teammate can trust a result they did not write themselves. New joiners inherit the team's hard-won knowledge on day one instead of month three. And you can finally judge the tool honestly — a number only means something when the thing you measure behaves the same way twice. **Write the setup once, and the whole team gets the same agent.** The first file you write, then, is less about the AI than about the team — it turns private experiments into one shared way of working. ### The same ideas in Claude Code and Copilot Claude Code and Copilot look different up close but are nearly the same shape from a step back. Both read a main instruction file. Both attach extra rules to certain folders. Both let you save a prompt so nobody types it twice. Learn the idea once, and the file name is just a lookup. The map — one idea, two homes: - **Main instructions** — Claude Code reads `CLAUDE.md` at the repository root; Copilot reads `.github/copilot-instructions.md`. Both load automatically, every session. - **Personal notes** — Claude Code reads an untracked `CLAUDE.local.md` for machine-specific settings; Copilot keeps personal instructions in user settings. Neither belongs in a client's repository. - **Folder-specific rules** — Claude Code puts a smaller `CLAUDE.md` inside a subfolder; Copilot uses `*.instructions.md` files with an `applyTo` pattern, read from `.github/instructions/` and `.claude/rules/` by default. - **Saved workflows** — Claude Code has skills under `.claude/skills/`; Copilot has prompt files under `.github/prompts/`, run by name with a leading `/`. - **Specialist roles** — Claude Code defines subagents under `.claude/agents/`; Copilot sets an `agent` value in a prompt file's header (`ask`, `agent`, `plan`, or a custom role). - **Enforcement** — Claude Code runs hooks that can stop an action before it happens; Copilot relies on continuous-integration and pull-request checks to do the same job. - **Outside knowledge** — both speak MCP, a shared standard for connecting an agent to live sources. > **MCP (Model Context Protocol)** — a shared standard that lets an AI tool read from live sources, such as a documentation server, a database, or an issue tracker, instead of only static files. The two are drawing closer than the folder names suggest. VS Code Copilot can now read `CLAUDE.md` and `AGENTS.md` directly — turn on `chat.useClaudeMdFile` or `chat.useAgentsMdFile` — and it already checks `.claude/rules/` for folder-specific rules. Write the context once, and both tools read most of it. Enforcement is the one place they still part ways, so plan that piece for each tool on its own. Each idea below is explained once, then shown in both forms. ### Give the agent the right context, not all of it The most common mistake is treating the instruction file as a dumping ground for everything the agent might ever need. It feels safe — surely more context means better answers. It's the opposite. The agent rereads that file on every task, so anything parked there competes with the real work for attention, and you pay for every word in tokens. A bloated instruction file is a slower, pricier, less focused agent. Choosing what to load, and when, is a skill with a name. > **Context engineering** — deciding what information the agent sees, when it sees it, and in what order, so it has exactly what the task needs and nothing that gets in the way. The pattern that works is plain: a small core that always loads, and everything else kept within reach for the moment a task calls for it. > **Progressive disclosure** — keep the always-loaded file short, and link to detailed notes the agent opens only when the current task needs them. Picture your context as four tiers, from "read every time" down to "read only when it matters." **Tier 1 — the always-loaded core.** This is the main instruction file. It holds only what every task needs: six to ten core rules, plus pointers to everything else. Keep it under roughly a hundred lines. Past that, every request pays for detail most tasks never use. **Tier 2 — notes the agent opens on demand.** The detail your core points to, split up by topic. Keep it somewhere stable — a `docs/rules/` folder works well — and refer to each file by its path, so the agent opens it only when the task matches: - **`docs/rules/development-rules.md`** — how to write, test, and check a change. - **`docs/rules/workflow.md`** — the shape of the feature and bug-fix pipeline. - **`docs/rules/orchestration.md`** — how to run subagents or parallel work. - **`docs/rules/review-standards.md`** — the review bar and the rules for cutting scope. **Tier 3 — the knowledge base.** The documents that describe how your system actually works. Keep them at one exact path so they resolve on every machine — `docs/kb/`: - **`docs/kb/architecture.md`** — the system, its boundaries, how data flows. - **`docs/kb/conventions.md`** — naming, error handling, the patterns you use. - **`docs/kb/gotchas.md`** — the traps: the auth quirk, the flaky test. - **`docs/kb/codebase-summary.md`** — the map: what lives where, and why. **Tier 4 — folder-specific rules.** Rules that apply to one part of the codebase, loaded only when the agent touches it — the frontend rules load for frontend files, and nowhere else. Build the tiers in this order: 1. **Draft the knowledge base first.** Point the agent at your existing documents and the code, and ask it to write the `docs/kb/` set for you: ```text Read the documents at and this codebase. Draft docs/kb/architecture.md, docs/kb/conventions.md, docs/kb/gotchas.md, and docs/kb/codebase-summary.md. Take architecture and conventions from the documents and the real patterns in the code. For gotchas, look for the workarounds, the TODO comments, and the tests that check for something strange. ``` 2. **Read what it wrote, then cut half.** An agent will confidently document a rule you dropped two years ago. **You own the truth; the agent only drafts it.** A knowledge base full of confident wrong answers is worse than none, because every later task trusts it blindly. 3. **Write the short core file** (the next section) and point it at the knowledge base and the on-demand notes. 4. **Move any rule longer than a paragraph into a Tier 2 file** and link to it. The core names the rule in one line; the linked file holds the detail. 5. **Add folder-specific rules** for any part of the codebase with its own standards. Static files come first. When part of your architecture changes by the hour — a live database schema, an open issue tracker — that is where MCP earns its place, wiring the agent to the source instead of a copy already going stale. That retrieval is a topic of its own, covered in the [Context Engineering](/posts/context-engineering-is-a-team-sport) series. For most teams, a handful of well-trimmed markdown files beat any clever pipeline — and this layered context is the common ground the whole team stands on. ![Layered mountain ridges fading from a sharp sunlit foreground into pale haze in the distance.](https://a.storyblok.com/f/288495199849781/1024x576/891d3c784a/ai-coding-agent-setup-guide-context-layers.webp) ### Writing the instruction file The main instruction file does two jobs: it states the core rules, and it points at everything else. Keep it short — every line competes for the model's attention on every task. The same content works in either tool — the only thing that changes is where it lives. Switch tabs to see the file for each: ```markdown title="CLAUDE.md" ### Core rules - Read `docs/kb/` before planning. Use the project's existing patterns before inventing new ones. - Keep secrets and private files out of commits. Never commit credentials. - Prefer small, focused changes. Add new structure only when it removes real complexity. - Before asking me to choose between options, show the options and your reasoning first. ### Open these only when the task needs them - Writing and testing code: `docs/rules/development-rules.md` - The feature or bug-fix workflow: `docs/rules/workflow.md` - Running subagents or parallel work: `docs/rules/orchestration.md` - Review and audit standards: `docs/rules/review-standards.md` ### The workflow — do NOT skip steps 1. Explore and brainstorm. Ask me questions. Do not write code yet. 2. I answer. Wait for my review. 3. Write a brainstorm file to `plans//brainstorm.md`. I review it. 4. Turn it into `plans//plan.md`. I review that too. 5. I clear the context to free up the window. 6. In a fresh session, implement ONLY the plan file. 7. Run the review checklist. Run the Playwright tests. 8. I review and approve. 9. Commit, push, and write a short report to `summary/.md`. ``` ```markdown title=".github/copilot-instructions.md" ### Core rules - Read `docs/kb/` before planning. Use the project's existing patterns before inventing new ones. - Keep secrets and private files out of commits. Never commit credentials. - Prefer small, focused changes. Add new structure only when it removes real complexity. - Before asking me to choose between options, show the options and your reasoning first. ### Open these only when the task needs them - Writing and testing code: `docs/rules/development-rules.md` - The feature or bug-fix workflow: `docs/rules/workflow.md` - Running subagents or parallel work: `docs/rules/orchestration.md` - Review and audit standards: `docs/rules/review-standards.md` ### The workflow — do NOT skip steps 1. Explore and brainstorm. Ask me questions. Do not write code yet. 2. I answer. Wait for my review. 3. Write a brainstorm file to `plans//brainstorm.md`. I review it. 4. Turn it into `plans//plan.md`. I review that too. 5. I clear the context to free up the window. 6. In a fresh session, implement ONLY the plan file. 7. Run the review checklist. Run the Playwright tests. 8. I review and approve. 9. Commit, push, and write a short report to `summary/.md`. ``` When a rule applies to just one corner of the codebase, scope it there. The rules are the same; each tool wires them to the folder differently — Claude Code by where the file sits, Copilot by an `applyTo` glob: ```plaintext title="src/frontend/CLAUDE.md" - Every component gets a test. No exceptions. - Clean any value before it reaches innerHTML. Treat all input as unsafe. - No inline styles. Use the design tokens in `src/frontend/tokens.ts`. ``` ```markdown title=".github/instructions/frontend.instructions.md" --- applyTo: "src/frontend/**" --- - Every component gets a test. No exceptions. - Clean any value before it reaches innerHTML. Treat all input as unsafe. - No inline styles. Use the design tokens in `src/frontend/tokens.ts`. ``` > **Folder-specific instructions** — extra rules the agent loads only when it works on matching files, so frontend rules stay out of backend work and the other way around. One habit saves real trouble on client work: read the customer's own standard before you write a word of yours. Many repositories already ship with a coding standard or an instruction file. Read it first, then ask one question — may we add a layer on top? If yes, put your additions in an untracked `CLAUDE.local.md` (or Copilot's user settings) that joins their rules to yours, kept out of their repository if they prefer. You build on a customer's standard; you never paint over it. ### The workflow the agent must follow A good instruction file never says "write good code." It lays out the steps, with a human check at every point where the agent could do the wrong thing with full confidence. That fixed set of steps has a name. > **Harness** — the fixed set of steps and safeguards you wrap around an agent, so it works the same safe way every time instead of improvising a new one each task. The workflow block above is that harness in short form. Here is each step — what it produces, and what it saves you from. 1. **Explore and brainstorm, no code yet.** The agent reads the knowledge base and restates the problem in its own words. Saves you from an agent that solves the wrong problem quickly. 2. **Answer, then review.** You answer its questions and confirm the direction before anything is written down. Stops a misunderstanding from becoming the foundation. 3. **Write the brainstorm file.** The agent records the approach and the trade-offs in `plans//brainstorm.md`, and a person reads it. Catches a shaky idea before it turns into code. 4. **Write the plan file.** The agent turns the approved brainstorm into `plans//plan.md` — the checklist below — and a person reviews it. The cheapest place to catch a bad approach. 5. **Clear the context.** The step almost everyone skips. Planning fills the working memory with a long conversation; clearing it hands the next session a clean slate and a tight plan. > **Context window** — the working memory an AI holds in a single session. Fill it with a long planning conversation and there's less room left for the code — quality slips without warning. 6. **Implement in a fresh session.** The agent builds only what the plan describes, and nothing else. 7. **Run the review and the tests.** The review checklist runs, then the Playwright tests — proof the change works from end to end. > **Playwright** — a tool that drives a real browser through your app the way a user would, so "it works" means the flow ran, not just that the code compiled. 8. **Review and approve.** A person reads the change and the test results and signs off. 9. **Commit, push, and summarize.** The agent writes a short report of what it changed to `summary/.md`. ### What the plan file must contain Step 4 is where quality stops being a hope and becomes a requirement — anything not written into the plan will not happen. Before a line of code, the plan names: - **The tests** — the unit tests it will add and the Playwright flows it will run. - **The review bar** — a clean pass from your linters (for example ESLint and SonarLint), no obvious security holes such as cross-site scripting or injection on anything a user can reach, and a short note on speed and load. - **The scope** — what it is deliberately not touching this time. - **The rollback** — how to undo the change if it misbehaves during review. ### Making the workflow non-optional A workflow written in an instruction file is a strong suggestion. Two things turn a suggestion into a guarantee. The first is a hook. > **Hook** — a small script that runs by itself at a set moment, such as just before a file is saved or a commit is made, and can allow, block, or change the action. In Claude Code, three hooks carry most of the weight. One blocks code edits until the agent has actually explored the repository. One blocks the build until an approved `plan.md` exists. One blocks any read of a secrets file and asks you first. With hooks in place, the workflow no longer relies on the agent choosing to follow it. The second is a specialist role. > **Subagent** — a smaller agent with its own instructions and a narrow job, such as planner, reviewer, or tester, brought in for one step so it does not have to hold the whole task in its head. Rather than one generalist doing everything, you hand each step to the right specialist. A planner writes the plan file. A reviewer runs the checklist against the change. A tester runs Playwright and reports what broke. Each one starts fresh and focused, which holds quality higher than a single agent juggling all three. Copilot runs the same workflow with a different enforcement surface. With fewer built-in blocks, the discipline moves to two places: prompt files under `.github/prompts/` that save each step as a named command, and continuous-integration checks that stop a merge when the plan's tests or the review bar go unmet. Same steps; the gate simply sits at the pull request instead of the moment of action. This is the layer that keeps "done" honest. The agent cannot close a ticket by producing a pile of code, because "done" now means passing tests, a clean checklist, and a person's approval. ### Turn good prompts into shared skills The first time someone works out the exact prompt that reliably bumps an API version in one file, that knowledge is trapped in a single chat history. The reuse layer pries it loose and hands it to everyone. > **Skill** — a saved, version-controlled prompt and its instructions that the whole team installs and runs by name, instead of copying a clever prompt around in chat. Writing skills from scratch is its own subject, covered end to end in the [complete guide to building skills](/posts/complete-guide-claude-notebooklm-obsidian). What matters here is the habit: when a prompt proves itself on real work, promote it from one person's history to a shared asset — a skill under `.claude/skills/` in Claude Code, a prompt file under `.github/prompts/` in Copilot. The drill that turns grind into a lasting asset fits inside a single sprint. Say a tedious change is spread across fifty files: 1. Do one file by hand. 2. Hand the agent the before and after of that file: ```text Here is file A, before and after I changed it by hand. Write a prompt that makes the exact same change for any file with this structure — the same imports, the same call pattern, the same error handling. ``` 3. Test the prompt it writes on two more files. 4. If it holds up, add it to your skills library. Now the grind that would have crawled through fifty files by hand is a skill the agent runs on its own next time. The first agent you set up is the most expensive one — it carries all the setup and the trial and error. Every one after costs less, because you are adding to a shared library the whole team draws from. A stack of tool licenses loses value as it ages; a shared skills library gains value as it grows. ### Capture what the team learns Two folders cost almost nothing and, a year on, hold the most useful context you own. When the agent or a developer hits a wall, write it down — one short file per problem in a `lessons-learned/` folder, so the next person and the next agent walk around it. At the end of a ticket, the agent drops a short report of what it did into a `summary/` folder. Neither takes more than a minute, and both feed straight back into the setup: today's trap becomes tomorrow's line in `docs/kb/gotchas.md`, and the summaries are raw material for onboarding. An agent is only as good as the last thing you taught it, and this loop is how the team keeps teaching it instead of hitting the same wall every sprint. It is also the quiet reason some teams get new hires productive in a third of the usual time: their agent already knows every trap, because someone spent a minute writing it down. ### How this setup makes the numbers real Every layer above is more than housekeeping. Each one is what lets a number about the tool actually mean something. Take a simple health check — how many steps the agent takes to finish a task. That figure only tells you something if the task is framed the same way each time. The harness frames it the same way, so a jump from three steps to eight reads as real drift, not a differently worded request. Take another — how often the agent stops to ask a human for help. It only reads clearly against steady context, and the knowledge base is what holds the context steady; a sudden rise means the context ran thin, not that today's task was odd. Or sorting genuine feature work from routine busywork: that needs consistent commit messages, and the harness's commit-and-summary step is exactly what produces them. Pull the setup away and every one of those numbers wobbles for reasons that have nothing to do with the agent getting better or worse. **A measurement is only as steady as the setup beneath it.** That is the real payoff: the groundwork is not just how you get good work out of the agent, it is what lets you prove the work is good. For the full set of metrics and formulas, that is what the [ROI guide](/posts/how-to-measure-ai-agent-roi) is for. ### The setup checklist, in order Here is the whole build, start to finish, for either tool: 1. **Draft the knowledge base.** Point an agent at your documents and the code, and have it write the `docs/kb/` set. Read it and cut half — you own the truth. 2. **Fix one path.** Keep the knowledge base at `docs/kb/`, the same for everyone, so the instruction file finds it on every machine. 3. **Write the short core file.** Core rules plus pointers, under a hundred lines, in `CLAUDE.md` or `.github/copilot-instructions.md`. 4. **Move the detail into on-demand notes and folder-specific rules.** The core names each rule; the linked file holds it. 5. **Set up the workflow.** The steps in the instruction file, the plan-file checklist, and the enforcement — hooks and subagents in Claude Code, prompt files and continuous-integration checks in Copilot. 6. **Read the client's standard.** Read theirs first, ask to add your own layer, and join the two — never replace. 7. **Run one real ticket through it yourself,** all the way, before anyone else. Fix whatever felt clumsy. Then show the team. Now it is a shared way of working, not a memo. None of these files is complicated on its own — some layered markdown, a short workflow, a few safeguards, two folders that start out empty. The value is not in the syntax. It is in the shared discipline they hold. The team that writes them ships faster and can prove it. The team that skips them buys the same model and measures a feeling. The model will keep improving on its own, with no help from you. The setup around it is the part that is yours to build. Build it first — before you spend another hour arguing over which agent to buy.