Two Courses, One Mental Model: GitHub Copilot Chat and Claude Code Compared

in Blog

A practitioner’s reference built from two Udemy courses by Tom Phillips, one on GitHub Copilot Chat and one on Claude Code. Rather than treating them as two unrelated tools, this post maps both onto five underlying mechanisms, then preserves the full working reference for each, and closes with a combined workflow for using either one on a team.

I went through Tom Phillips’s two Udemy courses back to back, one on GitHub Copilot Chat, one on Claude Code, mostly because I wanted a working reference I could hand to my own team rather than a vague sense of “yeah, AI coding tools are good now.” I’ve been documenting both in our wiki as I go, and the more notes I took, the more obvious it became that the two tools aren’t really as different as their separate marketing pages suggest.

Once you strip away the product-specific names, both Copilot Chat and Claude Code are solving the same five problems: how do you give the assistant standing context it doesn’t have to be told twice, how do you save yourself from retyping the same instruction, how do you let it act more autonomously without losing control of the blast radius, how do you give it specialized knowledge without bloating every single request, and how do you let it reach into a live external system instead of working off static training knowledge alone.

This post is organized around that idea. First, the five mechanisms and how each tool instantiates them, side by side. Then a complete deep-dive reference for each tool on its own, since I didn’t want to lose any of the detail from either course by trying to merge everything into one unified structure. Last, a combined workflow for a team that wants to use either tool (or both) without reinventing the process from scratch.

The Five Mechanisms Underneath the Vocabulary

1. Standing project context

Both tools have a file that gets loaded into every single request automatically, no invocation needed. For Copilot, that’s .github/copilot-instructions.md, always included for the whole repo, plus AGENTS.md at the repo root, which is a cross-tool convention other AI assistants (Cursor, etc.) also look for, making it the better pick if your team uses more than one AI tool. For Claude Code, that’s CLAUDE.md, generated by running /init against your codebase and then hand-edited over time.

Both also have a conditional, second tier of the same idea: content that’s only loaded when it’s actually relevant, rather than on every turn. Copilot’s version is .github/instructions/*.instructions.md, scoped to specific files or folders via an applyTo glob pattern in the frontmatter, so it’s not “everything under this folder is always in context,” only the files that match get it. Claude Code’s version is a /docs directory of standards files, but with an important caveat from the course notes: Claude may not automatically consult a docs file just because CLAUDE.md vaguely references “docs.” You often need to state the exact file path explicitly, or it may not read it before generating new code.

2. Reusable task templates

Anything you find yourself typing more than twice becomes a saved template you invoke by name instead. Copilot calls this a Custom Prompt File (.github/prompts/*.prompt.md), invoked as a slash command or attached to a chat via “Attach context → Prompt.” Claude Code calls it a custom slash command (.claude/commands/*.md), which can be project-scoped (shared with the team) or user-scoped (personal, living in ~/.claude/commands/), and supports $ARGUMENTS for everything after the command name, or $1/$2 for positional arguments when you need more than one distinct value.

Claude Code’s notes also cover a naming-conflict rule that’s worth knowing: if a user-scoped command shares a name with a project-scoped one, only the user-scoped version gets recognized. The fix is to put personal versions inside a personal/ subdirectory, which then shows a distinguishing prefix in the command picker.

3. Autonomous, scoped agents

This is the mechanism with the most internal structure, really two related but distinct ideas in both tools.

The first idea is a restricted persona: a named, invokable version of the assistant with a defined, narrower set of tools/instructions/MCP servers it’s allowed to use. Copilot calls this a Custom Agent (.github/agents/*.agent.md), created via “Create new agent” in the UI and invoked as a slash command through the agent: frontmatter field. Claude Code’s equivalent is a Sub-agent, managed via /agents, but framed slightly differently in the course notes: it’s trigger-based rather than purely on-demand, e.g. “whenever a new file is added to /docs, update CLAUDE.md to reference it.” Sub-agents run isolated, with their own context window, and report back a result rather than pausing for feedback mid-task. Both tools let you invoke these either automatically (the assistant decides based on task description) or directly (you name the agent explicitly).

The second idea is a fire-and-forget cloud task: sending a well-defined piece of work off to run unsupervised, on its own branch, so you can keep working interactively elsewhere. Copilot’s version is Background/Cloud Agents, triggered via the right-arrow icon in chat, or by installing the GitHub Copilot app and assigning a GitHub issue directly to Copilot. Claude Code’s version is the GitHub Actions integration: comment @claude on an issue, and it works the issue in the background and pushes a new branch. Both explicitly recommend reviewing the resulting diff/branch with the same rigor you’d apply to a human contributor’s PR.

4. On-demand specialized knowledge (Skills)

This is the cleanest match of the five. Both tools use the literal term “Skills,” and both use the same mechanic: only a short description is front-loaded into context up front. The model itself decides, mid-task, whether a skill is relevant, and only then reads the full SKILL.md file (plus any supporting scripts or reference files) into context. Both course notes explicitly contrast this with MCP’s always-front-loaded tool definitions as the reason Skills scale better to a large library of narrow capabilities, both mention skill-creator as the official Anthropic-provided skill for scaffolding new skills, and both point at skills.sh as a community directory, with the same caution to review or scan any third-party skill before installing it.

Claude Code’s notes add one extra idea worth calling out: you can wrap something that would normally require front-loaded MCP context, like a Neon database MCP server, as a skill instead, so its details are only read into context when actually queried.

5. Live external system access (MCP)

Identical concept, same protocol, in both tools. Model Context Protocol connects the assistant to an external tool or data source, database, ticketing system, design tool, whatever, and its tools become available for the model to call directly once configured. Copilot’s notes use Jira or internal APIs as the illustrative example; Claude Code’s notes use Neon’s hosted Postgres MCP server. In both cases, the tradeoff is the same one that motivates Skills: MCP tool/resource definitions are typically front-loaded into context as soon as the server is connected, whether or not a given task actually ends up using them.

Once you see mechanisms 4 and 5 side by side, the design tension in both tools becomes obvious: Skills are the “pay only when used” end of the spectrum, MCP servers are the “pay upfront, always available” end, and the standing context files sit in the middle, always loaded but meant to be kept lean by design.

With the five mechanisms as an orientation map, here’s the complete reference for each tool on its own. I’ve kept every detail from the original course notes, just reorganized under consistent headers.

Full Reference: GitHub Copilot Chat

Chat Modes

Copilot Chat offers a mode dropdown at the bottom of the chat view. Available modes vary slightly by IDE (VS Code vs. Visual Studio), but the general set is:

Mode Purpose
Ask Answers coding questions using your current editor context. No code is changed. Good for explanations, refreshers on syntax/libraries, or “how do I…” questions.
Edit You select the files to change, describe the update in natural language, and Copilot applies inline, review-ready edits across just those files.
Agent Give a high-level goal. Copilot autonomously plans steps, picks files, runs terminal commands/tools, and iterates until the task is done. Most powerful, least predictable, review before accepting.
Plan Copilot explores the codebase, asks clarifying questions, and produces a reviewable implementation plan before any code changes happen. Useful when you want to sanity-check the approach before letting Agent mode loose.

Practical tips:

  • Pick the effort/mode level according to task complexity, don’t default to Agent mode for a one-line question.
  • You can inspect and selectively keep or discard individual changes rather than accepting everything at once.
  • Use a separate chat session per task/feature to avoid context pollution from unrelated earlier conversation.
  • Tackle one feature at a time rather than five at once, smaller scope is easier to review and verify.
  • There’s a small context-usage indicator (pie-chart-style icon) in the chat view showing how much of the context window has been consumed.
  • You can restore a checkpoint to undo a change if Copilot’s edit isn’t what you wanted.

Adding Context to a Prompt

Ways to bring relevant context into a chat request:

  • # references, attach a specific file, e.g. #index.html, or use #file: and pick from a list. #selection references the currently selected code.
  • @ domain selectors, scope the question to a specific context provider, e.g. @workspace (whole project structure), @vscode (editor settings/commands), @terminal (terminal output/commands).
  • Inline chat, highlight a code snippet directly in the editor and ask a question or request a change without opening the full chat panel.
  • Terminal selection, you can also highlight text in the integrated terminal and ask about it.
  • Image attachments, attach a screenshot or mockup as context, useful for asking Copilot to match or update a UI design.
  • Browser mode, in VS Code you can open a browser preview and highlight specific rendered UI components to reference them in chat.
  • Slash commands, see below.

Slash Commands

Slash commands (/command) trigger pre-built prompts for common tasks without retyping instructions each time (e.g. setup, generating unit tests, /explain on selected code).

  • Commands can be scoped, the same command name may exist under different domains/tools, so check which one is being invoked.
  • You can combine a slash command with a highlighted code selection (e.g. select a function, then run /explain).

Custom Instructions

Custom instructions let Copilot automatically apply context/preferences to every request without you retyping them.

File Scope Auto-applied?
.github/copilot-instructions.md Whole repository, all requests Yes, always included automatically in every chat request for that repo.
.github/instructions/*.instructions.md Specific files/folders, defined via an applyTo glob pattern in the file’s frontmatter Yes, but only when the files being worked on match the applyTo pattern, it is not “everything under .github/instructions is always in context.” Unmatched instruction files are ignored.
AGENTS.md (repo root) Cross-tool convention (also recognized by VS Code) Yes, similar to copilot-instructions.md, but not GitHub Copilot specific, other AI coding tools (Copilot, Cursor, etc.) also look for this file, making it a good choice if your team uses more than one AI tool.

Two conventions for organizing instructions across multiple AI tools:

  • Unofficial (cross-tool): keep instruction content in separate Markdown files under a /docs directory, and reference them explicitly (e.g. via #docs/api-standards.md) since not every tool auto-loads arbitrary folders.
  • Official (GitHub Copilot specific): use the structured .github/agents and .github/prompts folders described below.

You can either write instruction files by hand or ask Copilot Chat to generate one for you from your existing codebase conventions.

Custom Agents and Prompt Files (GitHub Copilot specific)

  Custom Agents Custom Prompt Files
What it is A specialized, named version of Copilot with a restricted/defined set of tools, instructions, and MCP servers it’s allowed to use. A reusable prompt template for a specific, repeatable task.
File location .github/agents/*.agent.md .github/prompts/*.prompt.md
How it’s created “Create new agent” in the Copilot UI, then name it. Create the .prompt.md file directly, or ask Copilot Chat to generate one.
How it’s invoked As a slash command, via the agent: field set in its frontmatter. As a slash command, or by attaching the prompt file to a chat request (Attach context → Prompt…).
Best for Tasks where you want to constrain what the agent is allowed to touch or use, e.g. a “docs-only” agent, a “refactor-specialist” agent. Tasks where the instructions themselves are what you keep repeating, e.g. “generate a create-instructions prompt,” “scaffold a new test file.”

Bootstrapping pattern: create a create-instructions custom prompt/agent whose job is to generate new *.instructions.md files under .github/instructions (or /docs) whenever you need a new standard captured. Reference the resulting file with #filename.md in future prompts.

Sample references (community example repo):

Source Control Integration

In the Source Control tab in VS Code, there’s a “magic” icon next to the commit message box that generates a commit message from your staged changes automatically.

Background / Cloud Agents

  • The right-arrow icon in the chat view sends a task to run in the background/cloud rather than interactively in your editor.
  • This creates a new branch and works on the change independently, it can take longer than an interactive Agent-mode session, but multiple background tasks can run in parallel, so you can queue up several independent pieces of work at once.
  • You can also trigger cloud tasks by installing the GitHub Copilot app and assigning a GitHub issue directly to Copilot, or asking it to open a pull request.
  • Review the diff on the resulting branch/PR before merging, same as you would a human contributor’s PR.

Model Context Protocol (MCP)

MCP is a standard that lets Copilot Chat connect to external tools and services (databases, ticketing systems, design tools, etc.) and call them as part of a conversation. Once an MCP server is configured, its tools become available for Copilot to invoke directly in Agent mode, useful for integrating your team’s existing systems (Jira, internal APIs, etc.) into the AI workflow.

Hooks

Hooks live under the .github folder and let you extend/customize agent behavior by running custom shell commands at defined points in the agent’s execution lifecycle.

  • Example: a postToolUse hook that runs after every code-generation step, automatically invoking your code formatter/linter so all Copilot-generated code conforms to your formatting rules without manual cleanup.

Sub-agents / Orchestration

  • Sub-agents are isolated agent instances with their own context window, spun up to handle a delegated piece of work (e.g. research, a specific refactor, writing tests for one module) without cluttering the main chat session.
  • They run independently and report back a result/status to the main session rather than pausing for feedback mid-task.
  • Sub-agents can be invoked automatically (Copilot decides based on the task description and available custom agents) or directly (e.g. “use the testing subagent to write unit tests for the authentication module”).
  • Useful for orchestrating multiple pieces of a larger task in parallel, each sub-agent tackles one slice and reports success/failure.

Agent Skills

Agent Skills are folders of instructions, scripts, and resources that Copilot can pull into context only when relevant to the task at hand.

  • Key difference from MCP: MCP tools are front-loaded into context at the start of a session (all tool definitions are always present). Skills instead expose only a short description up front, the model decides whether a skill is relevant, and only then pulls in the fuller instructions/scripts/resources.
  • This makes skills more context-efficient for narrow, specialized capabilities that aren’t needed on every request.
  • Reference: skills.sh for browsing available skills.
  • Prefer skills from reliable providers (e.g. Anthropic) for quality and safety. For building your own, a skill-creator skill is available to scaffold new custom skills.

Choosing the Right Customization Mechanism

Mechanism When to use it
Custom Agents When you need to restrict or manage which tools an agent has access to for a specific type of task.
Custom Prompts When you find yourself typing the same prompt over and over, turn it into a reusable, invokable template.
Agent Skills When you want a determined, repeatable outcome/output for a specialized task, loaded only on demand.
Custom Instructions When you want to influence style/standards generally (e.g. coding conventions with example snippets), without requiring one fixed output.

Other Notes

  • For web app / frontend UI work, shadcn/ui is a commonly paired component library when prompting Copilot to scaffold UI.
  • Separate the different architectural layers of your application clearly (e.g. API, service, data access), this makes it much easier for Copilot Chat to understand where a change belongs and to follow your coding standards consistently.

Tips and a Good Corporate Workflow

General tips:

  • Start new tasks in Ask or Plan mode to explore/clarify before switching to Agent mode to execute, cheaper to catch a wrong approach before code changes start.
  • Keep tasks scoped to one feature or bug per chat session. Large, multi-concern prompts are harder to review and more likely to produce unwanted side effects.
  • Treat Agent-mode output like a junior developer’s PR: review the diff, run tests, don’t blindly accept.
  • Use checkpoints/restore liberally when experimenting, it’s cheaper to roll back than to untangle a bad multi-file edit manually.
  • Watch the context-usage indicator; if it’s climbing fast, start a new session rather than letting quality degrade from context dilution.
  • Use background/cloud agents for well-defined, lower-risk tasks (dependency bumps, boilerplate, test scaffolding) so you can keep working interactively on higher-judgment tasks in parallel.

A workflow that works well inside a corporate/team setting:

  1. Establish shared standards first, not ad hoc. Before teams start relying on Copilot day-to-day, commit a baseline .github/copilot-instructions.md (or AGENTS.md if the team also uses other AI tools) with architecture conventions, layering rules, and testing expectations. Store it in version control so it’s reviewed like any other code and stays in sync with the codebase.
  2. Layer in path-specific instructions as the codebase diversifies. Add .github/instructions/*.instructions.md files scoped with applyTo for language- or module-specific rules (e.g. Python service layer vs. frontend components) rather than growing one giant instructions file.
  3. Turn repeated prompts into custom prompt files or custom agents and commit them alongside the code. This turns “how we ask Copilot to do X” into a shared, reviewable team asset instead of tribal knowledge in someone’s head.
  4. Gate risky or destructive actions with hooks and custom agent tool restrictions, especially for agents that might run in less-supervised background/cloud mode, e.g. auto-format on every generation, or restrict a “docs-only” agent from touching source files.
  5. Use Plan mode (or Ask mode plus manual review) for anything touching shared infrastructure, security, or public APIs, and reserve autonomous Agent/cloud mode for lower-blast-radius, well-tested areas of the codebase.
  6. Review AI-authored PRs with the same rigor as human PRs, use Copilot code review as a first pass, but treat it as a supplement to, not a replacement for, human sign-off, particularly early on while trust in the workflow is being established.
  7. Iterate on the instructions/skills library as a living asset. When Copilot repeatedly gets something wrong in the same way, that’s a signal to add or refine an instruction file, prompt, or skill, treat it the same way you’d treat updating a team style guide after a recurring code review comment.
  8. Keep an internal “customization library” page (this wiki is a good place) listing which custom agents, prompts, and skills exist, what they’re for, and who owns them, so the tooling doesn’t sprawl into duplicated, inconsistent instructions across repos.

Full Reference: Claude Code

What is Claude Code

Claude Code is Anthropic’s agentic coding tool that runs in your terminal (or VS Code’s integrated terminal). Instead of copy-pasting snippets into a chat window, it can read your codebase, edit files directly, run commands, and iterate on tasks with your project as live context.

Project Setup Example

Example scaffold using Next.js, from the course’s sample app (a Lifting Diary):

npx create-next-app@latest liftingdiarycourse

Recommended options when prompted:

  • Use “customize settings”
  • TypeScript: yes
  • Linter: ESLint
  • React Compiler: no
  • Styling: Tailwind CSS
  • Source directory: src/
  • Routing: App Router
  • Import alias: keep default (no customization)

Installing and Configuring Claude Code

  1. Install Claude Code and make sure it’s on your PATH environment variable.
  2. Open your project in VS Code, open the integrated terminal, and run: 
    claude
  3. Log in with your Claude/Anthropic account when prompted.

Useful setup commands:

Command Purpose
/terminal-setup Configures terminal integration (keybindings, rendering)
/theme Change the color theme of the CLI
/config View/edit Claude Code configuration
/model Select which model Claude Code uses
/init Scans the codebase and generates a CLAUDE.md file documenting the project. This file is automatically attached as context to every chat in that project.
/context Shows how much of the context window is currently used
/clear Clears the current context window (starts a fresh session)
/install-github-app Sets up Claude’s GitHub Actions integration
/agents Lists existing sub-agents in the project, or creates a new one

Modes:

  • Shift+Tab, toggles between Plan Mode (Claude proposes an approach before touching any files) and Implementation Mode (Claude executes changes directly). Plan mode is useful for reviewing an approach before letting Claude edit code.
  • Extended thinking mode, when enabled, Claude spends more tokens reasoning before responding. This generally produces higher-quality output and is best reserved for complex, multi-step, or ambiguous tasks (not simple edits, since it costs more tokens/time).

Custom Slash Commands

If you find yourself repeating the same prompt, you can save it as a reusable slash command.

Project-scoped commands live in .claude/commands/. Example:

.claude/commands/merge-and-create-branch.md:

Commit any changes in the current branch with a suitable commit message
based on the code change. Then merge the current branch into main and
resolve any issues from that merge. Finally create a new branch called $ARGUMENTS.

Usage:

/merge-and-create-branch edit-workout-page
  • $ARGUMENTS captures everything passed after the command name.
  • If you need to reference more than one distinct argument, use $1, $2, etc. for positional arguments.

Another example, for generating documentation on demand:

create-docs.md:

Create a new documentation file at docs/$1.md to highlight the coding
standards for this layer of the app. Specifically cover: $2

User-scoped commands live in ~/.claude/commands/ (create the directory with mkdir -p ~/.claude/commands). These are personal to you and won’t affect other contributors on the same project.

Naming conflicts: if a user-scoped command has the same name as a project-scoped one, Claude Code will only recognize the user-scoped command. To avoid ambiguity, place personal versions inside a personal/ subdirectory, Claude Code will then show a prefix in the command picker to distinguish the two.

Skills

Skills are reusable, filesystem-based resources that give Claude domain-specific expertise: workflows, context, and best practices.

How they differ from prompts: prompts are one-off, conversation-level instructions. Skills persist across conversations and load on demand, so you don’t have to repeat the same guidance every time.

How they differ from MCP servers: with an MCP server, its full tool/resource definitions typically have to be front-loaded into context, whether or not you end up using them. Skills use progressive disclosure instead, only the skill’s short description is loaded upfront. If Claude decides mid-task that a skill is relevant, it then reads the skill’s full SKILL.md file, and pulls in any additional referenced resources only as needed. This means you can have a large library of skills (e.g. 100+) without bloating the context window.

This also means you can wrap something that would normally require front-loaded MCP context, e.g. a Neon database MCP server, as a skill instead, so its details are only read into context when actually queried.

Installing / creating a skill:

  1. Install the skill-creator skill (Anthropic’s official one) into your project. There are also community sites (e.g. skills.sh) with pre-made skills, though you should review/scan any third-party skill before installing.
  2. This creates .claude/skills/skill-creator/ containing:
    • SKILL.md, explains explicitly what the skill does
    • supporting scripts
    • reference files for specific information the skill needs
  3. From there, you can ask Claude Code to build a new skill for you, e.g.:

    “Create a new skill that queries the database for all workout entries from the past year using the database URL connection string in the .env file. Plot this data as a bar chart with a Python script (x-axis: month, y-axis: number of workouts), and export the chart as an image.”

Sub-agents

Sub-agents (managed via /agents) let you define focused, automated helpers scoped to a specific trigger and task, each with its own allowed tools and model.

Example: a docs-reference-updater agent:

  • Trigger: whenever a new file is added to the /docs directory
  • Task: update CLAUDE.md to reference the new file under the ## Code Generation Guideline section
  • Setup: when creating the agent, you choose which tools it’s allowed to access, and which model runs it.

Feature Comparison: Skills vs Commands vs Sub-agents vs Prompts vs MCP

These features overlap conceptually, they’re all ways of getting Claude to do something in a repeatable way, but they solve different problems. This table is meant to remove the guesswork on “which one should I reach for.”

Feature What it actually is Persists across sessions? How it’s invoked Context cost Best for Example
Prompt (regular chat message) A one-off instruction typed directly into the conversation No, gone once the conversation/context is cleared Manually, every time Only costs tokens for that one turn Ad hoc, one-time tasks you won’t repeat “Refactor this function to use async/await”
Custom slash command A saved prompt template stored as a file (.claude/commands/*.md), optionally parameterized with $ARGUMENTS/$1/$2 Yes, saved to disk, reused across sessions Explicitly, by typing /command-name args Only loads when called A repeated instruction with a fixed shape/wording that you (or your team) trigger by hand /merge-and-create-branch edit-workout-page
Skill A folder-based package (SKILL.md + optional scripts/references) describing domain-specific expertise or a workflow Yes, lives in .claude/skills/ Automatically, Claude decides on its own whether a skill is relevant to the current task, based on its short description Very low until triggered; only the description is front-loaded, full contents load on demand (progressive disclosure) Reusable expertise/workflows you want Claude to pull in without you having to remember to ask (e.g. “how we do database migrations here”) A skill that knows how to query the DB and generate a workout chart
Sub-agent A named, scoped agent (via /agents) with its own trigger condition, allowed tools, and model Yes, configured once, runs repeatedly Automatically, based on its defined trigger (e.g. “a file is added to /docs”) Isolated, runs its own focused task/context, separate from your main session Automating a specific recurring housekeeping task that should happen without manual prompting docs-reference-updater: auto-updates CLAUDE.md when a new file lands in /docs
MCP server An external tool/data source (e.g. a database, a ticketing system) exposed to Claude Code over the Model Context Protocol Yes, configured once as a connection Claude calls its exposed tools as needed during a task Higher, tool/resource definitions are typically front-loaded into context as soon as the server is connected Giving Claude live access to an external system (a real database, an API) rather than static knowledge Neon’s MCP server, letting Claude query your Postgres DB directly
CLAUDE.md A standing project-level context file, auto-attached to every chat in the project Yes, one file per project Always active, no invocation needed Loaded on every single turn, so keep it lean Persistent project-wide ground rules and pointers (e.g. “always check /docs before generating code”) Generated via /init, then hand-edited to reference /docs files
/docs standards files Plain markdown files describing team/project conventions (UI rules, data-fetching rules, etc.) Yes, version-controlled like any other file Only read when explicitly pointed to (usually via CLAUDE.md, or @docs/file.md) Only loaded when referenced Detailed, topic-specific rules that would bloat CLAUDE.md if inlined docs/ui.md, docs/data-fetching.md

GitHub Actions Integration

After running /install-github-app and completing the setup steps:

  1. Create a new issue in your GitHub repo describing the work.
  2. Comment on the issue tagging @claude, e.g. “implement this.”
  3. Claude Code works the issue in the background and pushes a new branch.
  4. Review the diff/branch, then create a pull request.

This pairs well with Vercel, which is free for web deployment: connect it to your GitHub repo and it will spin up a preview deployment for every branch, including the branches Claude’s GitHub Action creates, so you can review changes live before merging.

Working with Files and Context

  • Referencing code: highlight code in your editor (auto-selected as Claude Code input), drag files into the chat, or use @ to point directly to a relevant file.
  • Context hygiene: once you finish a piece of work, run /clear to reset the context window before starting the next task. This avoids polluting future prompts with irrelevant history and helps you avoid running out of context.
  • Inline bash commands: prefix a command with ! to run it directly, this doesn’t cost tokens itself, but its output is added to context.
  • Long-running/background jobs: for something like npm run dev, press Ctrl+B to send it to the background. Use /tasks to check on background jobs. Since background task output can be pulled into context, if an error appears in the logs you can simply prompt: “fix the error being emitted from the dev server in the background task.”

Documentation-Driven Development

A useful pattern is to keep a /docs directory of standards documents, and have CLAUDE.md explicitly point to them, so Claude Code consults them before generating code.

Example prompts used to build this out:

“Create a docs/ui.md file outlining the coding standard for the UI throughout this project. The document should state that ONLY shadcn/ui components should be used, ABSOLUTELY NO custom components. Dates should be formatted via date-fns, styled like 1st Sep 2025.”

“Create a docs/data-fetching.md file stating that ALL data fetching in this app must be done via server components, NOT route handlers, NOT client components. Database queries must always go through helper functions in /data, using Drizzle ORM, DO NOT USE RAW SQL. A logged-in user should only ever be able to access their own data.”

“Update CLAUDE.md to state that all generated code should ALWAYS first refer to the relevant docs file within the /docs directory.”

Practical notes:

  • Using CAPITAL WORDS for the non-negotiable constraints (e.g. “ABSOLUTELY NO”, “DO NOT USE RAW SQL”) helps emphasize hard rules.
  • Claude may not automatically consult a docs file just because CLAUDE.md vaguely references “docs,” you often need to state the exact file path explicitly (e.g. docs/ui.md), otherwise it may not read it before generating new code.
  • Test this by clearing context and prompting for new code, then check whether the output conforms to your documented standards.
  • If Claude repeats the same mistake across sessions, the fix is to explicitly add a note about it into the relevant documentation file, this “closes the loop” so future generations don’t repeat it.

Third-Party Tooling Referenced

Tool Role
Clerk Authentication-as-a-service. After creating a project on their site, Clerk gives you a setup prompt you can hand to Claude Code to wire up auth in your project.
Neon (console.neon.tech) Free hosted Postgres database. Also ships an MCP server, so Claude Code can query/manage the database directly as a tool.
Drizzle Open-source, TypeScript-first ORM for relational databases (used here instead of raw SQL).
shadcn/ui (ui.shadcn.com) A library of composable, copy-into-your-project UI components. Constraining Claude Code to only use these components (rather than inventing custom ones) keeps the UI consistent.
Vercel Free hosting/deployment platform, tightly integrated with GitHub, deploys a preview for every branch.

Running Multiple Claude Code Instances

You don’t have to wait for one Claude Code session to finish before starting another, multiple instances can run concurrently on the same project. However, be aware that if two instances touch the same files, they can conflict and produce a broken result. Best used when tasks are scoped to clearly separate files/areas of the codebase.

Local Models (Ollama)

Claude Code can also be pointed at a local, free, open-source model via Ollama instead of Anthropic’s hosted models. As of these notes, local model output quality is noticeably behind Claude’s hosted models, useful for experimentation or offline use, but not yet a like-for-like substitute for production work.

Reference Example

A full working example of the CLAUDE.md setup described above: github.com/tomphill/liftingdiarycourse/blob/main/CLAUDE.md

General tips:

  • Treat CLAUDE.md as your project’s onboarding doc for Claude, keep it current, and explicitly enumerate which /docs files must be consulted for which kind of change.
  • Split standards into focused docs (docs/ui.md, docs/data-fetching.md, docs/security.md, etc.) rather than one giant file, this keeps each reference short and Claude more reliably reads the one relevant file.
  • Use CAPITALIZED constraints sparingly, only for genuinely hard rules (security boundaries, forbidden patterns), overusing emphasis dilutes it.
  • When Claude repeats a mistake, don’t just correct it in chat, encode the fix into the relevant docs file so it’s caught earlier next time.
  • Use /clear between unrelated tasks. Long, accumulated context degrades output quality and wastes tokens.
  • Use Plan Mode (Shift+Tab) for any change with meaningful blast radius (schema changes, auth, data access) so you can review the approach before Claude edits files.
  • Reserve extended thinking mode for genuinely complex/ambiguous tasks, it’s slower and costs more tokens, so it’s wasteful for small, well-defined edits.

Suggested corporate workflow:

  1. Bootstrap the project context
    • Run /init to generate a baseline CLAUDE.md.
    • Add a /docs directory with standards docs for UI, data access, security, and any team-specific conventions.
    • Update CLAUDE.md to explicitly point to each relevant doc.
  2. Scope the task
    • Pull the ticket/issue into context (via @file, drag-and-drop, or by referencing the GitHub issue).
    • For non-trivial changes, start in Plan Mode so you and Claude agree on the approach before code is touched.
  3. Implement
    • Switch to Implementation Mode (Shift+Tab) once the plan looks right.
    • Run dev servers or test suites as background tasks (Ctrl+B) so you can keep iterating while watching for errors.
    • Use inline ! bash commands for quick checks (lint, type-check, git status) without burning extra turns.
  4. Review before merge
    • Treat Claude’s output like a junior engineer’s PR: read the diff, don’t just trust it.
    • For access-control or data-layer changes especially, manually verify the constraints in docs/data-fetching.md (or equivalent) were actually followed.
    • If using GitHub Actions integration, review the auto-created branch’s diff on its Vercel preview deployment before opening a PR.
  5. Automate repetitive asks
    • Once you notice yourself typing the same instruction more than twice, turn it into a project-scoped slash command (.claude/commands/) so the whole team benefits, or a user-scoped one if it’s personal.
    • Turn recurring “go do X and report back” tasks into a sub-agent with a clear trigger, so it runs automatically rather than needing to be invoked by hand.
  6. Parallelize carefully
    • When running multiple Claude Code instances at once, split work across files/modules that don’t overlap, to avoid two instances editing the same file and producing conflicting or broken changes.
  7. Close the loop
    • After each significant task, ask: did Claude make a mistake that a documentation update could have prevented? If so, update the doc immediately rather than relying on remembering to correct it verbally next time.
    • Periodically /clear and re-run /init (or manually refresh CLAUDE.md) as the codebase evolves, so the generated documentation doesn’t drift from the real project structure.

A Combined Team Workflow

Read the two “tips and workflow” sections above next to each other and you’ll notice they’re really the same seven or eight beats, described from two different tools’ vantage points. Here’s the merged version I’ve actually started proposing internally.

A few things stood out to me putting these two side by side:

  • Both tools converge on “standards before scale.” Neither course recommends letting a team loose on Copilot or Claude Code before a baseline instructions file exists in version control. That ordering matters more than which tool you pick.
  • Both tools converge on “review like a junior engineer’s PR,” verbatim in spirit if not in wording. Neither treats agent output, background or interactive, as trustworthy by default. That’s worth repeating to a team the first time someone’s tempted to merge an AI-authored PR without reading the diff.
  • The “close the loop” step is the one people skip in practice. Both course notes call out the same fix for repeated mistakes: don’t correct it verbally, write it into the standing docs. It’s the least glamorous step and the one that compounds the most over a few months of daily use.
  • Where they genuinely diverge is the cloud/background story. Copilot’s background agents and Claude’s GitHub Actions integration solve the same problem (well-defined, lower-risk work running unsupervised) but the trigger mechanics differ enough that a team standardizing on one tool needs to actually read that tool’s specific docs rather than assuming the other tool’s pattern transfers directly.

Closing Thought

None of this settles a “which tool is better” argument, and I don’t think that’s actually the useful question. What surprised me going through both courses close together is how much of the hard-won process (standards first, review everything, encode mistakes into docs rather than memory) is tool-agnostic. The vocabulary differs, Custom Agents vs Sub-agents, Background Agents vs GitHub Actions, but the underlying five mechanisms and the discipline around using them responsibly are close to identical.

For my own day-to-day, that’s actually reassuring. I split time between VS Code with Copilot and the terminal with Claude Code depending on the task, and knowing the concepts map onto each other means I’m not relearning a mental model every time I switch, just the specific file paths and slash commands.

© 2018. All rights reserved.

Powered by Hydejack v8.2.0