Split View: AGENT.md, CLAUDE.md, Skills 완전 활용 가이드: AI 코딩 어시스턴트 마스터하기

AGENT.md, CLAUDE.md & Skills Complete Guide: Mastering AI Coding Assistants

Table of Contents

1. What Are CLAUDE.md and AGENT.md?
2. Writing an Effective CLAUDE.md
3. The Core of Forbidden Patterns and Rule Configuration
4. Mastering Skills Files
5. Real-World CLAUDE.md Examples by Project Type
6. Prompt Strategies to 10x Your AI Coding Productivity
7. AI Coding Workflow in Practice
8. Establishing Team AI Usage Principles
9. Multi-Agent Coding (The Future)
10. Quiz

1. What Are CLAUDE.md and AGENT.md?

The Memory Problem with AI Coding Assistants

AI coding assistants are incredibly powerful, but they have a fundamental limitation: when a conversation session ends, they forget everything from before. Having to re-explain "our project uses TypeScript, functions should be under 50 lines, and console.log must not appear in production code" every single new session creates enormous inefficiency.

CLAUDE.md and AGENT.md were created precisely to solve this problem.

The Difference Between the Two Files

CLAUDE.md is a configuration file exclusive to Anthropic's Claude Code. When Claude Code opens a project, it automatically reads this file to understand the project context. It is deeply integrated with all Claude Code features and connects with the memory system, allowed/forbidden command settings, custom commands (Skills), and more.

AGENT.md is a general-purpose agent configuration file. It is designed as a standard format that can be shared across a variety of AI coding tools beyond Claude Code — including Cursor, GitHub Copilot Workspace, Devin, and OpenHands. For teams that use multiple AI tools together, a solid strategy is to use AGENT.md as the baseline and separate tool-specific settings into dedicated files.

File Location and Hierarchy

Files are placed at the project root.

my-project/
  CLAUDE.md          # Project-wide settings
  src/
    CLAUDE.md        # src-specific settings
    components/
      CLAUDE.md      # Component-specific settings
  backend/
    CLAUDE.md        # Backend-specific settings

Claude Code reads upward from the current file's location to the root, merging all CLAUDE.md files it encounters. This enables hierarchical configuration.

• Root CLAUDE.md: Common rules for the entire project (coding standards, commit message format, etc.)
• Subdirectory CLAUDE.md: Rules specific to that area (e.g., "always update the OpenAPI spec when modifying backend API routes")

Why This Matters

When given appropriate context, AI assistants produce noticeably higher-quality code. Without CLAUDE.md, an AI follows generic best practices but cannot know a project's unique conventions or architectural decisions. As a result, it repeatedly makes mistakes: generating code that doesn't match the team's style, using forbidden patterns, or reinventing utilities that already exist.

A well-written CLAUDE.md makes the AI behave like a senior developer on your team — one who deeply understands the team's decisions and conventions and generates code that aligns with them.

2. Writing an Effective CLAUDE.md

Basic Structure

An effective CLAUDE.md consists of the following sections.

# Project Overview

Project purpose, tech stack, architecture overview

# Tech Stack

- Language: TypeScript 5.x
- Framework: Next.js 15 (App Router)
- Database: PostgreSQL + Prisma ORM
- Testing: Vitest + Testing Library

# Project Structure

src/
app/ # Next.js App Router
components/ # React components
lib/ # Utility functions
types/ # TypeScript types

# Coding Standards

- Functions max 50 lines
- No `any` type
- JSDoc required for all functions
- Components use named exports only

# Testing Requirements

- All utility functions: unit tests required
- API routes: integration tests required
- Coverage 80% or higher

# Git Conventions

- Follow Conventional Commits
- Max 200 lines per PR

# Forbidden Patterns

- No console.log in production code
- No any type
- No hardcoded URLs

The Project Overview Section

The first section helps the AI understand the big picture. Include the following:

Project Purpose: Describe in 2–3 sentences what is being built, who uses it, and what the core value is.

Domain Concepts: Explain terminology and domain concepts unique to the project. Information like "An Order goes through states: Draft, Pending, Confirmed, Shipped, Delivered — each transition governed by business rules" is critical for the AI to generate correct code.

Architectural Decisions: Record major architectural choices — monorepo vs. multi-repo, microservices vs. monolith, layered architecture vs. hexagonal architecture.

The Tech Stack Section

Including versions matters. Specifying "React 19" instead of just "React" ensures the AI uses features and patterns from that specific version. The code patterns for Next.js 14's Pages Router and Next.js 15's App Router are completely different.

The Project Structure Section

Rather than simply listing directories, annotating each with its role is far more effective.

# Project Structure

src/
app/ # Next.js App Router - pages and layouts
(auth)/ # Route group requiring authentication
(public)/ # Public route group
api/ # API Route Handlers
components/ # Reusable React components
ui/ # Base UI components (shadcn/ui)
features/ # Feature components (auth, dashboard, etc.)
lib/ # Pure utility functions (no framework deps)
hooks/ # Custom React Hooks
stores/ # Zustand state management
types/ # TypeScript type definitions
server/ # Server-only code (DB, external APIs)

The Coding Standards Section

Specific rules work far better than abstract principles.

Bad: "Write clean code" Good: "Functions max 50 lines, max 4 parameters, max 2 levels of nested if statements"

Bad: "Handle errors well" Good: "All async functions wrapped in try-catch; errors logged with logger.error(); user-facing error messages tagged with 'USER_FACING_ERROR'"

Keeping It Current

CLAUDE.md should be a living document. When you add a new library, add it to the Tech Stack. When you discover a new forbidden pattern, add it to Forbidden Patterns. Recurring code review feedback belongs in Coding Standards so the AI generates correct code from the start.

3. The Core of Forbidden Patterns and Rule Configuration

Why Specifying "Don'ts" Matters

Working with AI coding assistants, you start to notice certain mistakes repeat. For example:

• Using any when TypeScript types get complex
• Leaving temporary console.log debug code behind
• Hardcoding URLs instead of using environment variables
• Reinventing utility functions instead of finding existing ones

Listing these patterns explicitly in the Forbidden Patterns section of CLAUDE.md prevents the AI from making them in the first place.

Real-World Forbidden Pattern List

# Forbidden Patterns

## Types

- No `any` type → use `unknown` or a specific type
- No `@ts-ignore` → fix the root cause of the type error
- No `as any` type casting

## Code Quality

- No `console.log` or `console.debug` in production code → use logger
- No incomplete code left with TODO comments (TODOs require issue links)
- No magic numbers → extract to named constants

## Architecture

- No direct fetch calls in components → use custom hooks or server actions
- No direct DB queries in client components
- No hardcoded URLs → use environment variables

## Security

- No raw user input in SQL → use Prisma ORM
- No secrets exposed on the client
- No admin API endpoints without authentication

## Performance

- No useEffect dependency arrays that cause infinite loops
- No client-side filtering of large datasets → filter at DB level

Instructing to Reuse Existing Patterns

Telling the AI to "look before you create" is also important.

# Before Creating New Code

Before writing new code, always check:

1. Is there already an implementation in src/lib/?
2. Is there a similar custom hook in src/hooks/?
3. Is there a reusable component in src/components/ui/?
4. Is there a reusable server action in src/server/?

Duplicate implementations severely degrade codebase maintainability.

4. Mastering Skills Files

What Skills (Custom Commands) Are

Skills are reusable AI prompt templates. You save frequently-used prompts as files and execute them quickly with slash (/) commands. In Claude Code, they are stored as Markdown files in the .claude/commands/ directory, enabling the entire team to consistently use the same high-quality prompts.

.claude/
  commands/
    commit.md
    pr-description.md
    test.md
    review.md
    docs.md
    refactor.md
    security-check.md
    performance-check.md

Essential Skills in Detail

/commit - Intelligent Commit Message Generation

Analyze the current staged changes and write a commit message
in Conventional Commits format. Write in English.

Format:
type(scope): subject

body (optional, explains why and what impact)

footer (optional, Breaking Change or issue number)

Type selection guide:

- feat: new feature
- fix: bug fix
- refactor: code improvement without behavior change
- test: add/modify tests
- docs: documentation changes
- chore: build/config changes
- perf: performance improvement

Use the changed module/component name as scope.
Subject: 50 chars or less, imperative mood.

/pr-description - Auto-Generate PR Description

Analyze the changes in the current branch and write a PR description.

## Summary

- (key changes as bullet points)

## Motivation

(explain why this change is needed)

## How to Test

- [ ] (verification checklist)

## Screenshots

(indicate if screenshots needed for UI changes)

## Notes

(anything reviewers should know)

/test - Auto-Generate Test Code

Write unit tests for the selected code.
Use Vitest + Testing Library.

Include:

1. Happy path (normal case)
2. Boundary value tests
3. Error cases (exception handling)
4. Edge cases (null, undefined, empty arrays, etc.)

Test naming: "should [expected behavior] when [condition]" format
Minimize mocks; stay as close to the real implementation as possible.

/review - Automated Code Review

Review this code. Analyze from the following perspectives
and label each item with severity (Critical/Major/Minor):

1. Bug potential
   - Logic errors, unhandled edge cases, race conditions

2. Security vulnerabilities
   - Auth/authz errors, injection vulnerabilities, sensitive data exposure

3. Performance issues
   - Unnecessary re-renders, N+1 queries, memory leaks

4. Readability improvements
   - Complex logic, unclear variable names, duplicate code

5. Testability
   - Dependency injection, pure function usage, ease of mocking

Include improved code examples for each issue found.

/docs - Auto-Generate Documentation

Write JSDoc documentation for this code.

For each function/class/type:

- @description: Feature description (2-3 sentences)
- @param: Type, description, and example value for each parameter
- @returns: Return value type and description
- @throws: Possible exceptions
- @example: Real usage code example

Include algorithm explanations for complex business logic.

/refactor - Refactoring Suggestions

Refactor this code.

Goals:

- Eliminate duplication (DRY principle)
- Improve readability (reduce complexity)
- Apply SOLID principles
- Improve testability

Constraints:

- Do not change existing behavior
- Maintain public API (function signatures, module interfaces)
- Refactor incrementally (don't change too much at once)

Show before/after comparisons and explain the reason for each change.

/security-check - Security Vulnerability Audit

Audit this code for security vulnerabilities using OWASP Top 10 as the baseline.

Check specifically for:

1. Injection (SQL, Command, XSS)
2. Authentication/authorization errors
3. Sensitive data exposure
4. Security misconfiguration
5. Use of components with known vulnerabilities

For each vulnerability:

- Risk level (High/Medium/Low)
- Attack scenario description
- Fix method and code example

/performance-check - Performance Analysis

Analyze performance issues in this code.

Check:

1. Algorithm complexity (time/space)
2. Unnecessary recomputation (memoization candidates)
3. Database query optimization (N+1, index usage)
4. Network request optimization (batching, caching)
5. Rendering optimization (for React components)

Include improved example code for each issue.

Tips for Writing Good Skills

Characteristics of a good Skill file:

1. Specify a clear output format: "Analyze it" produces inconsistent results; "Write analysis results in the following format" ensures consistency.

2. State constraints explicitly: What not to do is just as important as what to do.

3. Auto-include context: Use variables like $SELECTION, $FILE, $PROJECT to automatically include current context.

4. Iterate gradually: Don't try to make a Skill perfect from the start — improve it continuously as you use it.

5. Real-World CLAUDE.md Examples by Project Type

Next.js Full-Stack App

# E-Commerce Platform

## Overview

B2C e-commerce platform. Consists of customer shopping,
order management, and admin dashboard.
500K MAU, processing 5K orders per day.

## Tech Stack

- Next.js 15 (App Router, RSC)
- TypeScript 5.x (strict mode)
- PostgreSQL 16 + Prisma ORM
- Redis (sessions, cache)
- Stripe (payments)
- Vercel (deployment)

## Domain Model

- User: customer account, supports multiple shipping addresses
- Product: SKU-based inventory management, category tree
- Order: Draft → Pending → Confirmed → Shipped → Delivered → Cancelled
- Cart: Redis-based, supports unauthenticated users (session-based)

## Architecture Rules

- Server components query DB directly (Prisma)
- Client-side API calls go through /api routes
- Complex business logic lives in src/server/services/
- Payment-related code must be server-side only

## Forbidden

- Using Prisma directly in client components
- Calculating payment amounts on the client (must be server-side)
- any type
- Hardcoded prices or discount rates

Go Microservice

# Order Service

## Overview

Order processing microservice. gRPC for internal communication,
REST for external exposure. Target: 500 TPS.

## Tech Stack

- Go 1.23
- Fiber (HTTP), gRPC (internal)
- PostgreSQL + sqlc (type-safe queries)
- Redis (distributed lock, cache)
- OpenTelemetry (distributed tracing)

## Code Style

- Errors must propagate upward (use errors.Wrap)
- All DB queries include context (ctx param required)
- Logging: zerolog structured logs only
- Define interfaces first, implement later

## Project Layout (Standard Go Layout)

cmd/ # main packages
internal/ # code not exported externally
domain/ # domain models and interfaces
service/ # business logic
repository/ # DB access layer
handler/ # HTTP/gRPC handlers
pkg/ # utilities that can be exported

## Forbidden

- No panics without recover
- No context.Background() directly in handlers
- No global state
- No goroutine leak patterns

Java Spring Boot

# Payment Service

## Overview

Payment processing service. PCI-DSS compliance required.
Kafka event-driven async processing.

## Tech Stack

- Java 21 (leveraging Virtual Threads)
- Spring Boot 3.x
- Spring Data JPA + Hibernate
- Apache Kafka (event streaming)
- Vault (secret management)

## Architecture

Hexagonal Architecture (Ports & Adapters):

- domain/: pure domain models (no dependencies)
- application/: use cases, port interfaces
- infrastructure/: adapters (DB, Kafka, external APIs)
- interfaces/: controllers, DTOs

## Rules

- Domain layer must have zero Spring dependencies
- All monetary values use BigDecimal (never double or float)
- Apply Circuit Breaker pattern for external payment API calls
- Saga pattern with compensating transactions for distributed transactions

## Forbidden

- Using double instead of BigDecimal for monetary calculations
- Logging payment information without masking
- Missing timeouts on synchronous payment API calls

6. Prompt Strategies to 10x Your AI Coding Productivity

Context-First Prompting

When making requests to AI, structuring your prompt as Background → Constraints → Request yields far better results.

Bad example:

Write a payment processing function

Good example:

[Background] This is an e-commerce platform that processes payments with Stripe.
Payment-related logic currently lives in src/server/services/payment.ts.

[Constraints]
- Amounts must always be calculated server-side (never trust client input)
- On payment failure, retry up to 3 times with exponential backoff
- All payment events must be saved to an audit log

[Request]
Write a processCheckout function that creates a Stripe Payment Intent
during cart checkout. Use TypeScript and async/await.

Breaking Down Requests Step by Step

Asking the AI to tackle a complex feature all at once risks missing important details or picking the wrong design. Break large features into smaller units and request them step by step.

Step 1: "Design the database schema for the user authentication system"
Step 2: "Write the Prisma model based on this schema"
Step 3: "Implement the login business logic in a service layer"
Step 4: "Create the API route handler that uses this service"
Step 5: "Write tests for each layer"

Few-Shot Prompting (Showing Examples)

Providing existing code patterns as examples gets the AI to generate code that matches your team's style.

Our project writes API routes with this pattern:

[Example]
export async function GET(req: NextRequest) {
  try {
    const session = await getServerSession(authOptions)
    if (!session) return unauthorized()

    const data = await getUserData(session.user.id)
    return ok(data)
  } catch (error) {
    logger.error('Failed to get user data', { error })
    return internalError()
  }
}

Using this pattern, write an API route that retrieves a list of orders.

Specifying Hard "Don'ts"

Explicitly stating what not to do in your prompt prevents the AI from going off the rails.

Implement a product search feature.

Never:
- Fetch all data on the client side and filter it there (performance issue)
- Insert search terms directly into SQL (injection vulnerability)
- Perform a full DB scan on every request without caching search results

Inducing Chain-of-Thought

For complex problems, prompting the AI to think step-by-step produces more accurate results.

Analyze whether this code has performance issues.
Before starting the analysis, proceed in this order:
1. Explain what the code is doing
2. Analyze time/space complexity
3. Identify potential bottlenecks
4. Suggest improvements

7. AI Coding Workflow in Practice

Morning Routine

An effective way to start an AI-coding day:

1. Check CLAUDE.md: See if the team added new rules yesterday
2. Understand the issue: Clearly grasp requirements before asking the AI to implement
3. Request an implementation plan from the AI: Review the approach before writing code
4. Implement step by step: Ask the AI to implement in the planned order
5. Review: AI first review with /review skill, human second review

Code Review Workflow

Combining AI code review with human code review:

AI First-Pass Review (automated):

• Automatically run /review skill on PR creation from CI
• Auto-detect bugs, security, and performance issues
• Verify coding standard compliance

Human Second-Pass Review (focused):

• Technical issues already caught by AI
• Focus on whether business logic is appropriate
• Evaluate long-term impact of architectural decisions
• Team knowledge sharing and mentoring

Debugging Workflow

Error occurs → Collect context → Ask AI for analysis → Validate solution

Context collection checklist:
- Full error message (with stack trace)
- Input values at the time of the error
- Recently changed code (git diff)
- Relevant logs (30 lines before/after the error)
- Environment info (dev/staging/prod)

When requesting AI help:
"This error occurred. Analyze 3 possible causes
and tell me how to debug each one."

Documentation Workflow

Automate documentation with AI after code is complete:

1. Feature implementation complete
2. Auto-generate JSDoc with /docs skill
3. Review auto-generated docs and add business context
4. Update README (for new features)
5. Auto-generate API docs (update OpenAPI spec)

8. Establishing Team AI Usage Principles

Document Your AI Usage Guidelines

The team needs clear guidelines to use AI consistently and safely.

# Team AI Usage Guidelines

## Permitted Use

- Code generation and refactoring
- Writing test code
- Documentation and comments
- Debugging assistance
- Code review assistance

## Areas Always Requiring Human Review

- Security-related code (auth, authz, encryption)
- Payment and financial processing logic
- Personal data handling code
- Architecture-level decisions

## Managing AI-Generated Code

- All AI-generated code must be reviewed and understood before committing
- "The AI made it so it must be correct" is forbidden
- Ask the AI to explain code you don't understand

Managing AI Dependency

Over-reliance on AI tools can erode a developer's core competencies. How to maintain a healthy balance:

Code every day without AI: Keep practicing solving small features or bugs entirely on your own. This prepares you for emergencies (AI tool outages, no internet) and maintains foundational skills.

Understand AI output: Don't just copy AI-generated code — understand why it was written that way. Ask the AI to explain parts you don't understand; this process becomes a learning opportunity.

Maintain judgment: AI is a tool. Critical decisions around architecture, business logic correctness, and security reviews must always be made by humans.

AI Guidelines for Junior Developers

If junior developers misuse AI, their growth can be stunted.

Recommended approach:

• Generate code with AI and use that code as study material
• Ask AI to explain concepts, then try to implement on your own
• Think of alternatives to AI-generated code yourself

Approach to avoid:

• Copying AI code without understanding it
• Immediately handing errors to the AI (try to solve it yourself for at least 30 minutes first)
• Delegating all design thinking to AI

9. Multi-Agent Coding (The Future)

The Era of Multiple AI Agents Coding Simultaneously

In 2026, a shift has begun — from a single AI agent handling one task at a time to multiple agents developing different features in parallel simultaneously.

For example:

• Agent A: Implement new payment API (feature/payment-v2 branch)
• Agent B: Write tests for the payment API (feature/payment-v2-tests branch)
• Agent C: Fix an existing bug (fix/order-status-bug branch)
• Human: Review and decide to merge agents' PRs

Strategies to Prevent Agent Conflicts

When multiple agents work simultaneously, code conflicts are inevitable. Strategies to prevent them:

Separate Work Territories: Assign each agent a clearly isolated file/module domain. Coordinate so that only one agent at a time modifies shared files (config files, type definitions, etc.).

Frequent Rebasing: Rebase each agent's branch onto main often to discover and resolve conflicts early.

Interface-First Contracts: Finalize interfaces shared among agents (API specs, type definitions) first, then let each agent implement independently.

Worktree-Based Parallel Development

Using Git Worktree, you can check out multiple branches from the same repository simultaneously, enabling parallel development.

# First workspace
git worktree add ../project-feature-a feature/payment-v2

# Second workspace (different directory, different branch)
git worktree add ../project-feature-b feature/user-profile-v2

# List worktrees
git worktree list

Claude Code recognizes this worktree pattern and can operate independently in each worktree. In the future, each worktree will have its own AI agent assigned, and team development speed will scale proportionally with the number of agents.

The Future of CLAUDE.md

In the multi-agent era, CLAUDE.md becomes even more important. It is the only "common language" ensuring multiple agents write code in a consistent way. In the future, CLAUDE.md will transcend being a configuration file and become a team constitution for your AI agent team.

10. Quiz

Closing Thoughts

CLAUDE.md, AGENT.md, and Skills are not merely configuration files. They are your team's AI collaboration contract — defining how humans and AI work together.

With a well-written CLAUDE.md, the AI behaves like a senior developer on the team. With well-designed Skills, the entire team produces consistent, high-quality code. As AI tools continue to evolve, the importance of these configuration files will only grow.

Start today: create a CLAUDE.md for your project and turn your most-used prompt into a Skill. Start small and improve it gradually as you use it — that's the best approach.