Complete Introduction to Claude Code: Automating Codebases with Terminal AI Agents

"How is it different from Copilot or Cursor?" — This is the most frequently asked question from developers encountering Claude Code for the first time. The difference lies in just one point. While existing tools are like autocomplete that suggests a line of code before the cursor, Claude Code is an autonomous agent that directly implements features across multiple files with a single natural language command like, "Add JWT authentication." It reads files, plans, modifies code, runs tests, and if it fails, analyzes the cause and fixes it again — repeating this entire loop without human intervention.

Claude Code is not a tool where "AI writes code for you," but a collaborative system where developers set goals and AI takes charge of execution. Once you understand this shift in perspective, you will understand why the pattern of teaching rules in advance with CLAUDE.md and reviewing plans before execution with Plan Mode is the core of this tool.

If you have backend development experience, I recommend reading through the content in order, starting with the core concepts. If you are already using Copilot or Cursor, you may start with Pros and Cons Analysis. For those considering adoption, the 3-step implementation guide in Conclusion is the fastest entry point.

Key Concepts

What is the Claude Code

Claude Code is an agent-based coding CLI (Command Line Interface) tool developed by Anthropic. It was beta-launched in February 2025 and officially released (GA) in May 2025, and its core philosophy is clear: given a goal in natural language via the terminal, it understands the codebase, plans, and executes it on its own.

What is an Agent? It refers to an AI system that goes beyond simply answering questions to make decisions autonomously by sequentially using various tools to achieve a goal. Claude Code repeats a loop of reading files → planning modifications → writing code → running tests → fixing errors.

Agent Loop

This loop is the biggest difference between Claude Code and typical code autocomplete tools. When the user enters a goal, the next cycle runs automatically.

css

[목표 입력]
    ↓
[코드베이스 분석 — 관련 파일 탐색 및 이해]
    ↓
[계획 수립 — 어떤 파일을 어떻게 수정할지 결정]
    ↓
[실행 — 코드 작성, 파일 수정]
    ↓
[테스트 실행 — 결과 검증]
    ↓
[실패 시 오류 분석 → 수정 반복]
    ↓
[완료 보고]

The technical foundation enabling this loop is the large context window supported by the Claude Sonnet 4.6 / Opus 4.6 model family. It allows you to grasp an entire monorepo of tens of thousands of lines at once. Since the exact token limit varies depending on the usage model and plan, it is most accurate to check the latest specifications in the official documentation.

CLAUDE.md — Project Constitution

Claude Code reads the CLAUDE.md file in the project root whenever it starts a conversation. This file serves as a "constitution" that teaches the AI project rules. Once written correctly, it ensures consistent quality results in all subsequent sessions.

yaml

# 프로젝트 규칙
 
- 패키지 매니저: pnpm만 사용 (npm, yarn 금지)
- 코드 스타일: TypeScript strict mode
- 테스트: 반드시 실제 DB 사용 (mock 금지)
- 커밋 메시지: 한국어 허용, imperative mood
 
# 빌드 & 테스트 명령어
- Build: `pnpm build`
- Test: `pnpm test`
 
# 아키텍처 규칙
- 비즈니스 로직은 Service에, Controller는 thin하게 유지

The reason for specifying "Tests: Must use actual DB (no mocks)": AI tools, including Claude Code, tend to select mocks by default when writing tests. However, mock tests fail to capture actual DB schema changes, migration errors, or differences in transaction behavior. This single rule ensures reliability at the integration level.

Tip: CLAUDE.md is a file shared by the entire team. If you explicitly ban patterns that team members have made mistakes with in the past or that the AI has incorrectly selected, such as "use pnpm only" or "no mock DB," the quality of results in subsequent sessions will improve noticeably.

Plan Mode — An Essential Safety Net for Beginners

Plan Mode is a mode where Claude Code shows only a plan before actually modifying the code and waits for approval. It is effective in preventing unexpected modifications because you can receive a plan stating, "I will change these files in this way," before making changes. You can enter this mode by pressing Shift+Tab during a conversation or by using the --plan flag when running.

Permission Management — Conservative Design

Operations that affect the system, such as modifying files or executing shell commands, request explicit permission from the user by default. This is a design intended to prevent unintended destructive changes. You can adjust settings to always allow or deny specific operations.

Practical Application

Example 1: From Installation to Implementing the First Feature

The official installation method is global package installation via npm. Node.js 18 or higher is required.

bash

# 공식 설치
npm install -g @anthropic-ai/claude-code
 
# 프로젝트 디렉토리에서 실행
cd my-project
claude
 
# 자연어로 기능 구현 요청
claude "로그인 API에 JWT 인증을 추가해줘. \
  액세스 토큰 만료는 15분, 리프레시 토큰은 7일로 설정해줘"

Claude Code automatically performs the following tasks with this single command.

Step	Action
1. Analysis	Exploration of Existing Authentication-Related Files and Understanding of Structure
2. Planning	List of files requiring modification and determination of how to change them
3. Execution	Install JWT library, write middleware, modify router
4. Verification	Automatic correction upon failure after running existing tests

Example 2: Safely Refactoring Large Scale with Plan Mode

# --plan 플래그로 Plan Mode 진입 (또는 대화 중 Shift+Tab)
claude --plan "전체 코드베이스에서 콜백 패턴을 async/await으로 변환해줘"

In Plan Mode, Claude Code outputs the plan before actual modifications. Below is an example response (the actual output format may differ).

bash

수정 계획:
1. src/utils/fileHelper.js — readFile 콜백 → async/await 변환 (3곳)
2. src/api/userRouter.js — 미들웨어 체인 재구성 (5곳)
3. src/services/emailService.js — 전체 재작성 필요 (12곳)
총 20개 파일, 약 87곳 수정 예정
실행할까요? [y/n]

Once the plan is reviewed and approved, actual revisions begin. If the scope of the revisions is larger than expected or if the direction differs from the intent, the course can be changed at this stage.

Example 3: Autonomous Test Loop

# 테스트를 통과할 때까지 자동으로 수정 반복
claude "현재 실패하는 테스트를 모두 통과시켜줘. \
  단, 테스트 코드 자체는 수정하지 말고 구현 코드만 수정해"

This pattern is particularly powerful. Claude Code repeats the loop of executing pnpm test → analyzing failure logs → fixing the cause code → re-executing without human intervention. If test commands are specified in CLAUDE.md, it works identically in any project.

Example 4: Checking for Security Vulnerabilities in a Python Project

Claude Code is not exclusive to TypeScript or Node.js. It works the same way in projects based on any language, such as Python or Go.

# Python FastAPI 프로젝트에서 보안 취약점 점검
claude "@app/api/routes.py @app/models/user.py \
  이 엔드포인트들에서 SQL injection 취약점이나 \
  인증 우회 가능한 부분을 찾아서 수정해줘"

python

# 수정 전 — 취약한 문자열 포맷 쿼리
@app.get("/users/{user_id}")
async def get_user(user_id: str):
    query = f"SELECT * FROM users WHERE id = {user_id}"  # SQL injection 위험
    result = await db.execute(query)
    ...
 
# Claude Code가 파라미터 바인딩 방식으로 자동 교체한 결과
@app.get("/users/{user_id}")
async def get_user(user_id: int, db: AsyncSession = Depends(get_db)):
    result = await db.execute(select(User).where(User.id == user_id))
    user = result.scalar_one_or_none()
    ...

Example 5: Fix a specific file as context

# @멘션으로 특정 파일을 명시적으로 컨텍스트에 포함
claude "@src/types/user.ts @src/api/userRouter.ts \
  이 타입 정의를 기반으로 유저 CRUD API를 완성해줘"

It is an effective pattern for reducing the waste of analyzing irrelevant files in large codebases and increasing accuracy.

Pros and Cons Analysis

Advantages

Claude Code shines brightest in medium-difficulty tasks within an environment where CLAUDE.md is well-configured. The perceived improvement in productivity is greatest in tasks with clear goals and verification criteria, such as writing repetitive boilerplate, applying consistent patterns, and test modification loops (based on user reports).

Item	Content
Understanding Large Contexts	Enables a holistic view of complex monorepos or legacy codebases
Autonomous Execution	Repeats the Test → Error Correction → Re-execution loop without human intervention
Terminal Native	Seamlessly integrates with existing workflows such as vim, tmux, zsh, etc.
Multilingual Support	Works without language restrictions including TypeScript, Python, Go, Rust, etc.
Scalability	Customizable for teams and projects with MCP, Skills, and Hooks

Disadvantages and Precautions

Item	Content	Response Plan
Pricing	The practical entry point for professional use is the Max Plan ($100/month)	Costs are spread across team accounts, and effectiveness can be measured with a free trial before implementation
Usage Limits	Rate limits exist depending on the plan (Check Official Rates Page for the latest standards)	Focus on important tasks or consider a higher-tier plan
Dependence on Prompt Quality	Vague Instructions Lead to Inconsistent Results	Specify Rules in CLAUDE.md and Make Specific Instructions a Habit
Editor Integration Limitations	Official extensions only support VS Code and JetBrains	Use Terminal + Editor in parallel or switch to a supported editor
Risk of Direct Production Deployment	Risk of deploying to production without review	Must maintain PR review process, do not enter automated deployment pipelines alone

What is MCP (Model Context Protocol)? It is a protocol that allows Claude Code to connect with external services (databases, monitoring tools, internal APIs, etc.) in a standardized manner. By connecting an MCP server, Claude Code can significantly expand the scope of its tools, such as directly querying the DB or reading Slack messages.

The Most Common Mistakes in Practice

Using without CLAUDE.md: Project rules must be explained in every conversation, and the results vary from session to session. If you invest 30 minutes on the first day to write CLAUDE.md, the quality of all subsequent work changes.
Skip Plan Mode and Run Immediately: Running without a plan review, especially during large-scale refactoring or with an unfamiliar codebase, can result in an unexpected range of files being modified. Always activate Plan Mode using the --plan flag or Shift+Tab before starting.
Infinite looping with vague instructions: Abstract instructions like "improve this code" lead to inconsistent results. Specific goals and constraints must be presented together, such as "reduce the time complexity of this function from O(n²) to O(n log n)."

In Conclusion

Claude Code is not a tool where "AI writes code for you," but a collaborative system where developers set goals and AI takes charge of execution. This shift in perspective is the key to making the most of this tool. If you develop the habit of clearly defining goals, teaching rules in advance with CLAUDE.md, and reviewing before execution using Plan Mode, you can experience productivity incomparable to simple code auto-completion tools.

3 Steps to Start Right Now:

Run in an existing project after installation: Run npm install -g @anthropic-ai/claude-code followed by claude from the project root (refer to Example 1 above for detailed installation steps)
Write CLAUDE.md: Summarize package manager, code style, testing practices, and prohibitions in 5–10 lines and save it in the project root.
Attempt first task in Plan Mode: Activate Plan Mode using the --plan flag or Shift+Tab, then request a bug or feature you want to fix using natural language and review the plan.

Next Series

Advanced CLAUDE.md Usage — Covers how to standardize the entire team's AI workflow by combining Skills, Hooks, and MCP. It is a practical guide to designing a Claude Code environment so that all team members achieve the same quality of results.

Reference Materials

Claude

Complete Introduction to Claude Code: Automating Codebases with Terminal AI Agents

Key Concepts

What is the Claude Code

Agent Loop

This loop is the biggest difference between Claude Code and typical code autocomplete tools. When the user enters a goal, the next cycle runs automatically.

css

[목표 입력]
    ↓
[코드베이스 분석 — 관련 파일 탐색 및 이해]
    ↓
[계획 수립 — 어떤 파일을 어떻게 수정할지 결정]
    ↓
[실행 — 코드 작성, 파일 수정]
    ↓
[테스트 실행 — 결과 검증]
    ↓
[실패 시 오류 분석 → 수정 반복]
    ↓
[완료 보고]

CLAUDE.md — Project Constitution

yaml

# 프로젝트 규칙
 
- 패키지 매니저: pnpm만 사용 (npm, yarn 금지)
- 코드 스타일: TypeScript strict mode
- 테스트: 반드시 실제 DB 사용 (mock 금지)
- 커밋 메시지: 한국어 허용, imperative mood
 
# 빌드 & 테스트 명령어
- Build: `pnpm build`
- Test: `pnpm test`
 
# 아키텍처 규칙
- 비즈니스 로직은 Service에, Controller는 thin하게 유지

Plan Mode — An Essential Safety Net for Beginners

Permission Management — Conservative Design

Practical Application

Example 1: From Installation to Implementing the First Feature

The official installation method is global package installation via npm. Node.js 18 or higher is required.

bash

# 공식 설치
npm install -g @anthropic-ai/claude-code
 
# 프로젝트 디렉토리에서 실행
cd my-project
claude
 
# 자연어로 기능 구현 요청
claude "로그인 API에 JWT 인증을 추가해줘. \
  액세스 토큰 만료는 15분, 리프레시 토큰은 7일로 설정해줘"

Claude Code automatically performs the following tasks with this single command.

Step	Action
1. Analysis	Exploration of Existing Authentication-Related Files and Understanding of Structure
2. Planning	List of files requiring modification and determination of how to change them
3. Execution	Install JWT library, write middleware, modify router
4. Verification	Automatic correction upon failure after running existing tests

Example 2: Safely Refactoring Large Scale with Plan Mode

# --plan 플래그로 Plan Mode 진입 (또는 대화 중 Shift+Tab)
claude --plan "전체 코드베이스에서 콜백 패턴을 async/await으로 변환해줘"

In Plan Mode, Claude Code outputs the plan before actual modifications. Below is an example response (the actual output format may differ).

bash

수정 계획:
1. src/utils/fileHelper.js — readFile 콜백 → async/await 변환 (3곳)
2. src/api/userRouter.js — 미들웨어 체인 재구성 (5곳)
3. src/services/emailService.js — 전체 재작성 필요 (12곳)
총 20개 파일, 약 87곳 수정 예정
실행할까요? [y/n]

Example 3: Autonomous Test Loop

# 테스트를 통과할 때까지 자동으로 수정 반복
claude "현재 실패하는 테스트를 모두 통과시켜줘. \
  단, 테스트 코드 자체는 수정하지 말고 구현 코드만 수정해"

Example 4: Checking for Security Vulnerabilities in a Python Project

Claude Code is not exclusive to TypeScript or Node.js. It works the same way in projects based on any language, such as Python or Go.

# Python FastAPI 프로젝트에서 보안 취약점 점검
claude "@app/api/routes.py @app/models/user.py \
  이 엔드포인트들에서 SQL injection 취약점이나 \
  인증 우회 가능한 부분을 찾아서 수정해줘"

python

# 수정 전 — 취약한 문자열 포맷 쿼리
@app.get("/users/{user_id}")
async def get_user(user_id: str):
    query = f"SELECT * FROM users WHERE id = {user_id}"  # SQL injection 위험
    result = await db.execute(query)
    ...
 
# Claude Code가 파라미터 바인딩 방식으로 자동 교체한 결과
@app.get("/users/{user_id}")
async def get_user(user_id: int, db: AsyncSession = Depends(get_db)):
    result = await db.execute(select(User).where(User.id == user_id))
    user = result.scalar_one_or_none()
    ...

Example 5: Fix a specific file as context

# @멘션으로 특정 파일을 명시적으로 컨텍스트에 포함
claude "@src/types/user.ts @src/api/userRouter.ts \
  이 타입 정의를 기반으로 유저 CRUD API를 완성해줘"

It is an effective pattern for reducing the waste of analyzing irrelevant files in large codebases and increasing accuracy.

Pros and Cons Analysis

Advantages

Item	Content
Understanding Large Contexts	Enables a holistic view of complex monorepos or legacy codebases
Autonomous Execution	Repeats the Test → Error Correction → Re-execution loop without human intervention
Terminal Native	Seamlessly integrates with existing workflows such as vim, tmux, zsh, etc.
Multilingual Support	Works without language restrictions including TypeScript, Python, Go, Rust, etc.
Scalability	Customizable for teams and projects with MCP, Skills, and Hooks

Disadvantages and Precautions

Item	Content	Response Plan
Pricing	The practical entry point for professional use is the Max Plan ($100/month)	Costs are spread across team accounts, and effectiveness can be measured with a free trial before implementation
Usage Limits	Rate limits exist depending on the plan (Check Official Rates Page for the latest standards)	Focus on important tasks or consider a higher-tier plan
Dependence on Prompt Quality	Vague Instructions Lead to Inconsistent Results	Specify Rules in CLAUDE.md and Make Specific Instructions a Habit
Editor Integration Limitations	Official extensions only support VS Code and JetBrains	Use Terminal + Editor in parallel or switch to a supported editor
Risk of Direct Production Deployment	Risk of deploying to production without review	Must maintain PR review process, do not enter automated deployment pipelines alone

The Most Common Mistakes in Practice

Using without CLAUDE.md: Project rules must be explained in every conversation, and the results vary from session to session. If you invest 30 minutes on the first day to write CLAUDE.md, the quality of all subsequent work changes.
Skip Plan Mode and Run Immediately: Running without a plan review, especially during large-scale refactoring or with an unfamiliar codebase, can result in an unexpected range of files being modified. Always activate Plan Mode using the --plan flag or Shift+Tab before starting.
Infinite looping with vague instructions: Abstract instructions like "improve this code" lead to inconsistent results. Specific goals and constraints must be presented together, such as "reduce the time complexity of this function from O(n²) to O(n log n)."

In Conclusion

3 Steps to Start Right Now:

Run in an existing project after installation: Run npm install -g @anthropic-ai/claude-code followed by claude from the project root (refer to Example 1 above for detailed installation steps)
Write CLAUDE.md: Summarize package manager, code style, testing practices, and prohibitions in 5–10 lines and save it in the project root.
Attempt first task in Plan Mode: Activate Plan Mode using the --plan flag or Shift+Tab, then request a bug or feature you want to fix using natural language and review the plan.