Split View: 2026년 AI 코딩 워크플로 베스트 프랙티스 — CLAUDE.md, AGENTS.md, .cursorrules, Skills, 서브에이전트, MCP 깊게 보기

AI Coding Workflow Best Practices in 2026 — CLAUDE.md, AGENTS.md, .cursorrules, Skills, Subagents, MCP Deep Dive

"Agents take on the shape of the environment you build for them. Building a good environment is building a good agent."

Prologue — Context Before Code

In May 2026, a senior developer's day looks different than it did in 2022. The first thing you open in the morning is not your IDE but an agent session. More than half of all PRs contain more lines written by an agent than typed by a human. And the variable that most decides PR quality is not the agent's model version — it is the context you prepared.

This post starts from a single proposition.

Agents read the markdown and config files sitting next to your code as if they were a compiler. Those files are your agent.

The last two years have been an explosion of tooling. Claude Code's CLAUDE.md, Cursor's .cursorrules and .cursor/rules, GitHub Copilot's .github/copilot-instructions.md, and the cross-tool AGENTS.md standard that OpenAI Codex has been pushing — different names, same essence. They are shared instructions saying "when you work in this repo, behave this way."

On top of that sit tool-specific advanced features. Claude Code's Skills (.claude/skills/), subagents (.claude/agents/), hooks (.claude/hooks/), MCP server config (.mcp.json), Cursor's agent definitions (agents.json) and permission systems. Each looks small. Stacked together, they create a 10x difference in personal productivity.

The problem is that few guides cover all of this in one place. Official docs exist per tool, but how those tools coexist in a single repo is rarely written down. This post tries to fill that gap.

What you'll find:

1. The Context-File Family

A well-set-up 2026 repo typically has the files below. Names differ per tool, but roles are clearly divided.

1.1 The Map

1.2 The Layering Principle

You do not need all of these in one repo. But three axes help you decide where to put a given rule.

1. Tool generality — One-tool-only goes in that tool's file. Cross-tool goes in AGENTS.md or README.md.
2. Scope — Repo-wide goes in the root. Folder-specific goes in another CLAUDE.md or AGENTS.md in that folder. Claude Code walks parent directories and merges every CLAUDE.md it finds.
3. Volatility — Frequently changing things (an ongoing migration note, recent decisions) go in a separate file or a short section. Rarely changing rules (code style, security principles) belong in the main body.

One-line summary: shared rules in AGENTS.md, tool-specific details in their own files, folder-specific details in the folder.

2. Writing CLAUDE.md Well

Claude Code auto-loads CLAUDE.md from the working directory at session start and merges it into the system prompt. It also walks the parents of the file you're editing, finds more CLAUDE.md files, and merges them with the global ~/.claude/CLAUDE.md. A well-written file visibly improves results with the same model.

2.1 The Shape of a Good CLAUDE.md

# Project: Acme Web

## Stack
- Next.js 15 (App Router), TypeScript strict, Tailwind v4
- Drizzle ORM + Postgres 16
- Vitest + Playwright

## Conventions
- All server actions live in `app/_actions/` and import zod schemas from `lib/schemas/`.
- Database access goes through `lib/db/repositories/`. Do NOT import drizzle directly in components.
- Error type: throw `AppError` (see `lib/errors.ts`); the global handler converts to JSON.

## Verification (do this before reporting "done")
- `pnpm typecheck`
- `pnpm test --run`
- `pnpm lint`

## Permissions
- You may run: pnpm scripts, git read commands, gh CLI for issues/PRs.
- You may NOT run: git push, gh pr merge, anything that mutates production.

The point is that it is short and action-oriented. Only the things "this repo does differently."

2.2 Length — Cap at 200 Lines

A 1000-line CLAUDE.md causes two problems at once. First, you pay tokens for it every turn. Second, the model cannot uniformly follow that many rules — the middle gets watered down as length grows.

Rule of thumb: split at 200 lines. Two patterns:

• Per-folder CLAUDE.md — backend rules in apps/api/CLAUDE.md, frontend in apps/web/CLAUDE.md. Claude Code merges them automatically.
• Separate docs — long, rarely-referenced policies (security ops, data retention) go in their own markdown; CLAUDE.md just says "read docs/security.md when needed."

2.3 What to Include, What to Exclude

Include:

• Non-standard conventions of this repo (don't restate universal rules — "TypeScript is strict" is the default almost everywhere, no need to spell it out)
• Common pitfalls ("In this repo we use date-fns, never dayjs")
• The verification procedure — which commands count as "done"
• Prohibitions — no force-push, no auto-running migrations, etc.

Exclude:

• Generalities the model already knows ("write clean code" is noise)
• Volatile temporary notes (those belong in tickets or PRs)
• Secrets (this file is committed; never put tokens or keys here)

2.4 A Per-Folder CLAUDE.md Example

Keeping apps/api/CLAUDE.md separately means its rules merge only when working on backend code.

# apps/api

## Boundaries
- Controllers in `routes/` — only HTTP concerns.
- Business logic in `services/`.
- DB access in `repositories/` (Drizzle).

## Tests
- Unit tests next to the file (`*.test.ts`).
- Integration tests in `tests/integration/` — they spin up testcontainers Postgres.

3. AGENTS.md — The Cross-Tool Standard

Starting in late 2025, OpenAI Codex began promoting AGENTS.md, a movement to "let every coding agent read the same markdown placed in the repo." As of 2026, Codex, some Cursor modes, and several OSS agents recognize this file. The format is free-form markdown.

3.1 A Typical AGENTS.md

# AGENTS.md

This file gives AI coding agents the context they need to work in this repository.

## What this repo is
A pnpm monorepo with `apps/web` (Next.js), `apps/api` (Fastify), and `packages/*` shared libs.

## Setup
- Node 20.18+, pnpm 9.
- `pnpm install` from root.
- `pnpm dev` runs all apps in parallel.

## Test
- `pnpm test` — unit tests across the workspace.
- `pnpm test:e2e` — Playwright; requires Docker for testcontainers.

## Coding rules
- TypeScript only. No JS files in `src/`.
- Public APIs go in `packages/*/src/index.ts` re-exports.
- New endpoints need a zod request schema and 1+ test.

## Don't
- Don't commit secrets. `.env.local` is gitignored on purpose.
- Don't change `pnpm-lock.yaml` without running `pnpm install`.

3.2 Relationship to CLAUDE.md

When two tools don't read the same file, you don't want to write the same content twice. Two common patterns:

• AGENTS.md as the single source — All shared rules go in AGENTS.md. CLAUDE.md keeps one line.

  # CLAUDE.md
  Read AGENTS.md first. Anything below is Claude-specific addenda.
  
  ## Claude-only
  - When running shell commands, prefer pnpm over npm here.
  

• CLAUDE.md as the single source — If you only use Claude, skip AGENTS.md or symlink it. The downside is no guarantee when another agent shows up.

How to choose: one tool only? Single file. Two or more? Treat AGENTS.md as the single source of truth and keep tool files thin.

3.3 Real Examples

There are good public examples. Vercel's OSS repos (vercel/next.js, vercel/ai) tend to keep a relatively short, direct AGENTS.md focused on build/test commands and a "before you PR" checklist. Anthropic's SDK repos (anthropics/anthropic-sdk-python etc.) use CLAUDE.md, often with a temporary "this season's changes" block at the top during migrations. Take these patterns directly.

4. Cursor Rules

Cursor maintains two rule systems — legacy and modern. As of 2026, both still work.

4.1 Legacy — .cursorrules

A single flat markdown at the repo root.

# Cursor Rules

- Use TypeScript strict mode and avoid `any`.
- Prefer named exports.
- React components: function components with explicit prop types.
- All API handlers must validate input with zod.

## When generating tests
- Use Vitest.
- Place test files adjacent to source as `*.test.ts`.

Pro: simple. Con: no branching. The same rules apply to every file.

4.2 Modern — .cursor/rules/*.mdc

Several *.mdc files under .cursor/rules/, each declaring its application conditions in a header.

---
description: "Backend API rules — Fastify routes"
globs:
  - "apps/api/src/routes/**/*.ts"
alwaysApply: false
---

# Backend API rules

- Every route declares its zod schema via `schema:` option.
- Use `app.log` not `console.log`.
- Error handling: throw `AppError` (see lib/errors.ts).

Conditions usually split two ways. Either the file matches a globs pattern of the open file, or the user invokes the rule explicitly via a slash command. This modular approach is cleaner than .cursorrules, so for new repos prefer .cursor/rules/ from the start.

4.3 Cursor Agents — agents.json

Cursor's "agent mode" can have its own agent definitions. The root agents.json declares which tools are allowed, which mode to run in, etc. Details shift quickly between Cursor versions, so follow official docs. For this post, knowing "this file exists" is enough.

5. GitHub Copilot, README.dev, CONTRIBUTING

5.1 .github/copilot-instructions.md

GitHub Copilot Chat automatically merges this file into its system prompt when present. The usage pattern resembles CLAUDE.md, but shorter is better — Copilot models usually work with a tighter context window.

# Copilot Instructions

- This repo uses pnpm, Next.js 15, Drizzle, Vitest.
- Always type API responses (no `any`).
- For React components, prefer server components unless interactivity is required.
- New endpoints must validate input with zod.

5.2 README.dev.md

If README.md is the face shown to the outside, README.dev.md (or docs/dev.md) is the face shown to internal developers and agents. Typical contents:

• First-time local setup (deps, env, DB seeding)
• A list of frequently used commands (pnpm dev, pnpm db:reset, pnpm e2e:headed)
• One directory tree
• "Common stumbling blocks for newcomers"

This file helps both agents and new hires, which makes it one of the highest-ROI docs you can write.

5.3 CONTRIBUTING.md

In OSS repos it's for external contributors, but in internal repos writing down "how do we open a PR, how do we review" still pays off — agents follow it. If it overlaps with AGENTS.md, put it on one side and link from the other.

6. Claude Code Skills — Reusable Workflows

Skills are a powerful Claude Code feature. A markdown bundle of a procedure you repeat often, callable by name. Location: .claude/skills/<name>/SKILL.md (repo-local) or ~/.claude/skills/ (global).

6.1 The Shape of a SKILL.md

---
name: release-blog-post
description: Write, validate, and commit a trilingual blog post under data/blog/
when_to_use: User says "write a blog post" with a topic.
---

# Release Blog Post

1. Confirm filename slug: `data/blog/<category>/<YYYY-MM-DD>-<slug>.mdx`
2. Draft Korean version first.
3. Translate to en.mdx and ja.mdx, preserving structure.
4. Validate:
   ```bash
   npx tsx val.ts data/blog/.../<slug>.mdx data/blog/.../<slug>.en.mdx data/blog/.../<slug>.ja.mdx
   ```
5. Fix any reported issues, re-run until clean.
6. Stage and commit with message: `post: <topic> (ko/en/ja)`.

6.2 How to Write Skills Well

• Make the trigger (when_to_use) crisp — the model decides when to call this Skill.
• Procedure as a short numbered list. One step = one sentence = one action.
• Verification at the end. If that step fails, the spec must tell the model to go back and fix.
• Skills don't call other Skills — dependencies make them hard to debug.

6.3 Skill vs CLAUDE.md vs Subagent

Keeping the three distinct yields a clean design.

7. Subagents and Hooks

7.1 Subagents (.claude/agents/)

A subagent is what you delegate to when a task should run in a different context with a different toolset. Code review, security scans, large searches. The definition is markdown.

---
name: security-review
description: Reviews code for security issues — secrets, injection, auth bypass.
tools: [Read, Grep, Bash]
---

You are a security reviewer.

Process:
1. Search for hardcoded secrets (regex on common patterns).
2. Look for SQL/command injection in user-input paths.
3. Check authn/authz boundaries.

Output: a markdown report with severity tags (P0/P1/P2).

The biggest value of a subagent is context isolation. 100k tokens of search results don't dump into the main session.

7.2 Hooks (.claude/hooks/)

A hook is a small script that fires on session events. Common patterns:

• pre_tool_use — Warn on dangerous commands (rm -rf, git push --force)
• post_tool_use — Auto-run a formatter after a file edit
• session_start — Print environment info so the model gets fresh context
• notification — Push status to an external system (Slack, an alarm)

A typical definition:

[[hooks]]
event = "post_tool_use"
matcher.tool = "Edit"
matcher.path = "*.ts"
command = "pnpm prettier --write"

Because hooks touch your environment, design them to fire only in this repo.

8. MCP Server Config — The Agent's Toolbox

MCP (Model Context Protocol) is the standard protocol for attaching tools to a model. Claude Code reads .mcp.json to decide which MCP servers to start for a given repo.

8.1 .mcp.json Example

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_URL": "postgres://app:app@localhost:5432/app"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
      }
    }
  }
}

With this file, the model gets the postgres MCP's query tool and the github MCP's issue/PR tools exposed. It can write SQL on the fly or open and close GitHub issues itself.

8.2 Which MCPs to Install

The rule is "tool-ify the external calls your team makes most." Candidates:

• Databases (Postgres, MySQL) — infinitely useful for ad-hoc debugging queries
• GitHub/GitLab — issues, PRs, comments
• Observability (Sentry, Datadog, Grafana) — pulls error context automatically
• A slim MCP wrapping your internal API — wiki, design system, RBAC lookups

Too many MCPs make context heavy. Aim for under 5 per session. Turn the rare-use ones off and on as needed.

8.3 Handling Secrets

.mcp.json is usually committed, but you never put env values there. Use ${env:VAR} syntax, or keep secret-bearing entries in a .mcp.local.json (gitignored). Claude Code merges the two automatically.

9. Permissions and Sandboxing

The biggest risk of an autonomous agent is "unexpected behavior." 2026 tools provide two mechanisms.

9.1 Claude Code Permission Modes

Claude Code supports modes like these (names vary slightly across versions; meaning is similar).

• default — Asks for confirmation on every dangerous command.
• acceptEdits — File edits auto-approve, external commands (shell, network) still confirm.
• plan — Read-only. Plans but does not change anything.
• bypassPermissions — Skips all confirmations. Only inside isolated environments.

To pin the permission mode at the repo level, drop this in .claude/settings.json.

{
  "permissions": {
    "allow": [
      "Bash(pnpm test*)",
      "Bash(pnpm typecheck)",
      "Bash(git status)",
      "Bash(git diff*)"
    ],
    "deny": [
      "Bash(git push*)",
      "Bash(gh pr merge*)"
    ]
  }
}

Core idea: reads and builds/tests auto-allow, anything that changes the outside world always asks. This rule alone removes a huge class of accidents.

9.2 Cursor Agent Allowlists

Cursor agents have similar allow/deny lists. The common recommendation is "tests and lint and typecheck unlimited, package install confirm, git push block."

9.3 Sandboxes — Worktrees, Containers, Dev Containers

Separately from permissions, isolating the work itself is becoming standard.

• git worktree — A feature that checks out multiple branches of one repo into separate directories at once. Restrict the agent to a worktree and it cannot collide with your main work.
• dev container / Docker — The agent runs in a container with controlled dependencies and network. Claude Code has an official Docker image; using it isolates the host OS.
• Cloud sandboxes — Some modes (OpenAI Codex, others) run in cloud VMs. The host is never touched.

The more autonomy you want, the stronger the sandbox. The two dials are not the same axis — they are orthogonal.

10. What Makes a Codebase Agent-Friendly

Even with perfect config files, the code itself has to cooperate. There is such a thing as "code that's pleasant for agents to work in."

10.1 Five Traits

1. Strong types — TypeScript strict, Python typing fully on, Rust. The model has to infer intent from signatures alone.
2. Clear boundaries — A simple import graph between modules, and the responsibility of each module is one sentence.
3. Fast tests — Unit tests need to finish in under 10 seconds for the agent to verify at every step. If tests take minutes, the agent will skip verification.
4. Good error messages — A message like Error: invalid input gives the model nothing. Error: 'email' must be a valid RFC 5322 address (got "foo@") is a debugging clue.
5. Naming consistency — Similar things should be named similarly so the model's generalization works. Mixing userService.findById with OrderRepository.get confuses it.

10.2 "Tests as the Agent's Verifier"

The single strongest pattern is "pre-decide how the agent verifies its own change." The "Verification" section in CLAUDE.md/AGENTS.md plays this role. The model changes code, runs tests, fixes on failure, loops — internally. The more closed that loop is, the less human intervention is needed.

10.3 Small Units = Small PRs = Good Agent Output

Agents do their best work when not asked to change too much at once. So the codebase itself needs to be shaped so that "small PRs come naturally." If modules are too large, an agent's one task automatically becomes huge. This is just good engineering — but it pays double in the agent era.

11. Anti-Patterns — How to Ruin It

11.1 Over-Long Context Files

The most common mistake. A 2000-line CLAUDE.md burns that many tokens every turn while the model forgets the rules in the middle. Self-restraint at 200 lines is essential.

11.2 Conflicting Instructions

CLAUDE.md says "use pnpm," AGENTS.md says "use npm." The model picks one at random. Designate a single source of truth and have the other files reference it.

11.3 Empty Placeholders, Stale Commands

A CLAUDE.md still containing "This file is a stub — fill in your project details" — the model takes that seriously. Or a command from six months ago that no longer works — the agent runs it and fails. Ideally, lint context files in CI (detect empty placeholders).

11.4 Leaked Secrets

API keys typed directly into MCP config, or tokens hard-coded into a hook script and committed. Never. Inject through env vars, OS keychain, or a secrets manager.

11.5 "The Agent Will Handle It" Permissions

bypassPermissions as the default plus git push auto-allowed. One accident wrecks the main branch. Default conservative, full autonomy only inside an isolated worktree/container.

11.6 Skills Too Small or Too Large

A 5-line Skill should just live in the system prompt; a 200-line Skill is no longer a Skill but a separate doc. One Skill = one screen (50–80 lines).

11.7 Updating Context Files Only by Humans

The deploy procedure or CI command changed but CLAUDE.md still holds the old command — the agent wastes effort. The cheapest fix is a checkbox in the PR template: "related context files updated."

Epilogue — Time Invested in the Environment Compounds

The essence of a good agent setup is one thing. Make humans and tools work off the same page. Good guides for humans are good for agents; good procedures for agents are good for new hires. There is barely a separate standard between the two.

Investing time in context files can feel heavy. But this isn't time spent on a single PR. It is time that accumulates across every future session. A well-written 200-line CLAUDE.md gets read hundreds of times a year. An extra hour spent on those 200 lines is an hour multiplied by a thousand.

Best-Practice Checklist

1. AGENTS.md — a cross-tool single source of truth exists
2. CLAUDE.md — under 200 lines, non-standard conventions and verification
3. Per-folder CLAUDE.md — in a monorepo, split per app/package
4. .cursor/rules/ — modular, glob-branched rules
5. .github/copilot-instructions.md — a short summary for Copilot
6. README.dev.md — local setup and frequent commands
7. .claude/skills/ — bundled recurring workflows (name-triggered)
8. .claude/agents/ — delegated tasks needing context isolation
9. .claude/hooks/ — automation like formatters and alerts
10. .mcp.json — frequently called external systems tool-ified (committed); secrets in .mcp.local.json
11. permissions — auto-allow read/build/test, confirm anything mutating
12. sandboxes — autonomous mode only inside a worktree or container
13. CI lint on context files — detect empty placeholders and stale commands
14. PR template — "related context files updated" checkbox
15. Quarterly review — context files live like code

Anti-Patterns Recap

• 2000-line CLAUDE.md — the model forgets the middle; cap at 200
• Conflicting instructions — designate a single source of truth
• Direct secrets — use env vars and .mcp.local.json
• Full autonomy default — always conservative defaults + explicit opt-in
• Empty placeholders — detect in CI, block in PR
• No context update on infra change — enforce via PR-template checkbox
• Too many MCPs — keep under 5 per session, off the rest
• Skills sliced too thin — 5-line ones belong in the system prompt

Next Post

The next post is "AI Code Review Workflow — Using Human and Agent Reviewers Together." If good context files help authoring, a good review process secures output quality. What humans should review, what agents catch best, how to weave both into PR templates and CI — and how to arrive at a system where "the agent writes the PR and the human only reviews."

Tools change every year. Standards change more slowly. Environments, set up once, last a year. Don't spend your next hour on the most expensive code — spend it on the environment that produces that code.

References

• Anthropic Claude Code docs
• Claude Code — Memory & CLAUDE.md
• Claude Code — Skills
• Claude Code — Subagents
• Claude Code — Hooks
• Claude Code — Settings & Permissions
• Claude Code — MCP servers
• AGENTS.md site
• OpenAI Codex CLI — GitHub
• Cursor — Rules for AI
• Cursor — .cursor/rules format
• GitHub Copilot — Repository custom instructions
• Model Context Protocol
• MCP server catalog
• Vercel Next.js repo
• Vercel AI SDK repo
• Anthropic SDK Python
• Anthropic Engineering — Building agents
• Devin / Cognition — Agent design lessons
• git worktree official docs
• GitHub Actions — copilot-instructions examples