Notebase

AGENTS.md란? Codex·Claude Code·Cursor에서 프로젝트 지침 파일을 쓰는 이유

notebase — Fri, 5 Jun 2026 11:23:55 +0900

AGENTS.md가 무엇인지, Codex·Claude Code·Cursor에서 프로젝트 지침 파일을 어떻게 쓰는지 정리합니다. Claude Code의 CLAUDE.md, Cursor Rules와 .mdc 파일 구조, 실제 작성 예시와 주의사항까지 초보자 기준으로 설명합니다.

AGENTS.md는 AI 코딩 에이전트에게 “이 프로젝트에서는 이렇게 작업해라”라고 알려주는 지침 파일이다. Codex를 쓰다 보면 자주 보이고, Claude Code나 Cursor까지 같이 쓰면 파일명이 달라서 헷갈리기 쉽다.

먼저 결론부터 정리하면 이렇다.

도구	기본 프로젝트 지침 파일	동작 방식
Codex	`AGENTS.md`	작업 전 프로젝트 지침으로 참고
Claude Code	`CLAUDE.md`	Claude Code 메모리/프로젝트 지침으로 참고
Cursor	`.cursor/rules`, Cursor Rules, `AGENTS.md` 관련 지원	규칙 파일과 범위별 Rules를 통해 적용
공통 목적	프로젝트 구조, 명령어, 코드 스타일, 작업 규칙 전달	AI가 작업 전 참고할 기준 제공

여기서 중요한 점은 **모든 AI 코딩 도구가 AGENTS.md 하나만 공통으로 읽는 것은 아니라는 점**이다.

특히 Claude Code는 AGENTS.md가 아니라 CLAUDE.md가 기본이다. 2026년 6월 기준 Anthropic 공식 문서에서는 Claude Code의 프로젝트 메모리 파일로 CLAUDE.md를 안내한다. 이미 AGENTS.md를 쓰는 프로젝트라면 CLAUDE.md 안에서 @AGENTS.md로 가져오거나, 심볼릭 링크를 만들어 공통 지침을 공유하는 식으로 구성할 수 있다.

AGENTS.md는 AI 코딩 에이전트용 프로젝트 설명서다

개발자가 새 프로젝트에 들어오면 보통 README.md를 먼저 읽는다.

AI 코딩 에이전트도 비슷하다. 다만 AI에게는 사람이 읽는 설명서보다 조금 더 직접적인 지시가 필요하다.

예를 들면 이런 내용이다.

- 패키지 매니저는 npm이 아니라 pnpm을 사용한다.
- 테스트는 변경 후 pnpm test로 확인한다.
- API 라우터는 src/routes 아래에 둔다.
- DB 스키마를 직접 수정하지 말고 migration 파일을 만든다.
- 보안 관련 파일은 수정하기 전에 먼저 설명한다.

이런 내용을 매번 채팅으로 입력하면 번거롭다.

“이 프로젝트는 FastAPI야. SQLAlchemy 쓰고, 테스트는 pytest로 돌리고, env 파일은 건드리지 말고, 기존 구조 따라줘.”

처음에는 이렇게 말해도, 세션이 바뀌면 다시 설명해야 한다. 작업 도중에도 AI가 프로젝트 규칙을 잊거나, 다른 방식으로 코드를 짤 수 있다.

AGENTS.md나 CLAUDE.md 같은 파일은 이 반복 설명을 줄이기 위한 장치다.

왜 프로젝트 지침 파일이 필요한가

AI 코딩 도구는 코드베이스를 읽을 수 있지만, 프로젝트의 암묵적인 규칙까지 항상 정확히 이해하는 것은 아니다.

예를 들어 같은 React 프로젝트라도 팀마다 구조가 다르다.

src/components
src/features
src/app
src/pages
src/api

어떤 팀은 기능 단위로 묶고, 어떤 팀은 역할 단위로 묶는다. 테스트 파일 위치도 다르고, 상태 관리 방식도 다르다.

AI가 주변 코드를 보고 어느 정도 맞출 수는 있다. 하지만 프로젝트가 커질수록 애매한 선택지가 많아진다.

이때 지침 파일이 있으면 AI가 작업 전에 참고할 기준이 생긴다.

- 새 기능은 src/features/{featureName} 아래에 만든다.
- 공통 UI 컴포넌트는 src/components/ui에 둔다.
- API 호출 코드는 src/lib/api에 둔다.
- 테스트 파일은 원본 파일 옆에 *.test.ts 형식으로 둔다.

이 정도만 있어도 AI가 엉뚱한 위치에 파일을 만들 확률이 줄어든다.

실제로는 지침 파일이 코드 품질을 자동으로 보장한다기보다, AI가 매번 새 프로젝트처럼 행동하지 않게 만드는 기준선에 가깝다.

CLI형 AI 에이전트에서는 명령어 지침이 더 중요하다

Codex나 Claude Code 같은 최근 AI 코딩 도구는 단순히 코드 조각만 추천하는 자동완성 도구와 다르다. 프로젝트 파일을 읽고, 코드를 수정하고, 터미널에서 명령어를 실행하는 에이전트 성격이 강하다.

그래서 지침 파일의 명령어 섹션이 중요하다.

AI가 단순히 텍스트를 생성하는 수준이라면 “실행 명령어”는 참고 정보에 가깝다. 하지만 AI가 직접 테스트, 린트, 빌드 명령어를 실행할 수 있다면 이야기가 달라진다. 이때 명령어 지침은 실제 실행 기준이 된다.

예를 들어 프로젝트는 pnpm을 쓰는데 AI가 습관적으로 npm install을 실행하면 lock 파일이 꼬이거나 의존성 관리 방식이 달라질 수 있다.

## Commands

- Install dependencies: `pnpm install`
- Run dev server: `pnpm dev`
- Run lint: `pnpm lint`
- Run tests: `pnpm test`
- Do not use npm or yarn in this repository.

이런 식으로 적어두면 AI가 프로젝트에서 어떤 명령어를 우선 사용해야 하는지 판단하기 쉬워진다.

여기서 중요한 점은 명령어를 많이 넣는 것이 아니다. 실제로 이 프로젝트에서 써야 하는 명령어만 정확히 넣는 것이다.

잘못된 예시는 다음과 같다.

## Commands

- Run app: `npm run dev`
- Run app: `pnpm dev`
- Run tests: `npm test`
- Run tests: `pnpm test`

이렇게 쓰면 AI 입장에서는 어떤 명령어가 현재 기준인지 헷갈릴 수 있다.

수정하면 이렇게 된다.

## Commands

- Use `pnpm` only.
- Run app: `pnpm dev`
- Run tests: `pnpm test`
- Do not use `npm install` or `yarn install`.

AI가 터미널에서 직접 실행할 수 있는 도구일수록, 명령어 지침은 짧고 명확해야 한다.

Codex는 AGENTS.md를 읽는다

Codex에서는 AGENTS.md가 프로젝트 지침 파일 역할을 한다.

OpenAI 공식 문서 기준으로 Codex는 작업을 시작하기 전에 AGENTS.md 파일을 읽는다. 전역 범위의 지침과 프로젝트별 지침을 계층적으로 적용할 수 있다.

일반적인 위치는 프로젝트 루트다.

my-project/
├── AGENTS.md
├── package.json
├── src/
└── tests/

프로젝트 루트에 AGENTS.md를 두면 Codex가 해당 프로젝트를 작업할 때 참고할 수 있다.

예시는 다음과 같다.

# AGENTS.md

## Project overview

This is a Next.js application using TypeScript and Tailwind CSS.

## Commands

- Install dependencies: `pnpm install`
- Run dev server: `pnpm dev`
- Run tests: `pnpm test`
- Run lint: `pnpm lint`

## Coding rules

- Use TypeScript for all new files.
- Prefer functional components.
- Keep server-side logic out of client components.
- Do not introduce new dependencies without explaining why.

## Before finishing

- Run `pnpm lint` when changing TypeScript files.
- Run related tests when modifying business logic.

여기서 핵심은 “프로젝트를 설명하는 문서”와 “AI에게 시키는 행동 규칙”을 함께 넣는 것이다.

단, 너무 길게 쓰면 오히려 안 좋다. AI가 읽어야 할 컨텍스트가 늘어나고, 중요한 규칙이 묻힐 수 있다.

Claude Code는 CLAUDE.md가 맞다

사용자가 헷갈리기 쉬운 부분이 바로 Claude Code다.

Claude Code는 기본적으로 CLAUDE.md를 사용한다. AGENTS.md가 아니다.

프로젝트 루트에 둘 수 있다.

my-project/
├── CLAUDE.md
├── package.json
├── src/
└── tests/

또는 .claude 디렉터리 안에 둘 수도 있다.

my-project/
├── .claude/
│   └── CLAUDE.md
├── src/
└── package.json

Claude Code의 CLAUDE.md에는 프로젝트 지침, 빌드 명령어, 테스트 명령어, 코드 스타일, 자주 하는 작업 흐름 등을 넣을 수 있다.

예시는 다음과 같다.

# CLAUDE.md

## Project context

This project is a FastAPI backend application.

## Development commands

- Create virtual environment: `python -m venv .venv`
- Install dependencies: `pip install -r requirements.txt`
- Run server: `fastapi dev main.py`
- Run tests: `pytest`

## Rules

- Use Pydantic v2 style.
- Keep route handlers thin.
- Put business logic in service modules.
- Do not commit secrets or `.env` files.
- Explain before changing authentication or database migration logic.

Claude Code에서 이미 AGENTS.md를 쓰고 있는 저장소를 함께 쓰고 싶다면 CLAUDE.md 안에서 가져오는 방식이 현실적이다.

@AGENTS.md

## Claude Code specific rules

- Use Plan Mode before changing authentication logic.
- Ask before running destructive commands.

이렇게 하면 공통 지침은 AGENTS.md에 두고, Claude Code에만 필요한 내용은 CLAUDE.md 아래에 추가할 수 있다.

심볼릭 링크를 쓸 수도 있다.

ln -s AGENTS.md CLAUDE.md

다만 Windows에서는 심볼릭 링크 생성에 권한 문제가 생길 수 있다. 그럴 때는 CLAUDE.md에서 @AGENTS.md로 가져오는 방식이 더 단순하다.

Cursor는 Rules와 AGENTS.md를 함께 봐야 한다

Cursor는 예전부터 프로젝트 지침을 다루는 방식이 여러 번 바뀌었다.

예전에는 .cursorrules 파일을 많이 사용했다. 하지만 현재는 Cursor Rules를 중심으로 보는 것이 더 적합하다. 보통 프로젝트 안의 .cursor/rules 디렉터리에 규칙을 나누어 관리한다.

예시는 다음과 같다.

my-project/
├── .cursor/
│   └── rules/
│       ├── frontend.mdc
│       ├── testing.mdc
│       └── api.mdc
├── src/
└── package.json

Cursor Rules는 특정 파일, 디렉터리, 작업 맥락에 맞는 지침을 나눠서 관리하기 좋다.

예를 들어 프론트엔드 규칙은 frontend.mdc, 테스트 규칙은 testing.mdc처럼 나눌 수 있다.

# frontend.mdc

- Use React functional components.
- Prefer existing UI components before creating new ones.
- Keep component files small and focused.
- Do not add new styling libraries.

Cursor 공식 문서에서는 Project, Team, User Rules와 함께 AGENTS.md도 언급한다. 그래서 Cursor만 단독으로 쓴다면 Cursor Rules를 우선 정리하고, Codex 같은 다른 도구와 함께 쓴다면 AGENTS.md를 공통 지침 파일로 두는 방식도 고려할 수 있다.

실무적으로는 이렇게 나누면 덜 헷갈린다.

상황	추천 방식
Codex만 사용	`AGENTS.md`
Claude Code만 사용	`CLAUDE.md`
Cursor만 사용	`.cursor/rules`
Codex + Claude Code 같이 사용	`AGENTS.md` + `CLAUDE.md`에서 import
Codex + Cursor 같이 사용	`AGENTS.md` + Cursor Rules
세 도구 모두 사용	공통 규칙은 `AGENTS.md`, 도구별 규칙은 각 도구 파일에 분리

README와 AGENTS.md는 어떻게 다를까

README.md와 AGENTS.md는 비슷해 보이지만 목적이 다르다.

파일	주 독자	목적
`README.md`	사람	프로젝트 소개, 설치, 실행 방법 설명
`AGENTS.md`	AI 코딩 에이전트	작업 방식, 코드 수정 규칙, 명령어, 주의사항 전달
`CLAUDE.md`	Claude Code	Claude Code 세션에서 반복 적용할 프로젝트 지침
`.cursor/rules`	Cursor	Cursor Agent가 작업할 때 참고할 규칙

README는 사람이 프로젝트를 이해하기 위한 문서다. 그래서 배경 설명, 설치 방법, 배포 방법, 기능 소개가 들어간다.

반면 AGENTS.md는 AI가 작업할 때 실수하지 않도록 돕는 문서다.

예를 들어 README에는 이렇게 쓸 수 있다.

## Getting started

Run the development server:

pnpm dev

하지만 AGENTS.md에는 조금 더 행동 지침처럼 쓰는 편이 낫다.

## Commands

- Use `pnpm dev` for local development.
- Use `pnpm test` before finishing changes that touch business logic.
- Do not use npm or yarn in this repository.

차이는 작아 보이지만 중요하다.

AI에게는 “설명”보다 “어떤 상황에서 무엇을 해야 하는지”가 더 도움이 된다.

지침 파일에 넣으면 좋은 내용

처음부터 거창하게 쓸 필요는 없다. 실제로 반복해서 설명하게 되는 것부터 넣으면 된다.

1. 프로젝트 개요

AI가 프로젝트의 큰 방향을 이해할 수 있게 짧게 적는다.

## Project overview

This is a FastAPI backend for a personal finance dashboard.
It provides REST APIs for transactions, categories, and monthly reports.

너무 긴 서비스 소개는 필요 없다. AI가 코드 수정 방향을 잡을 정도면 충분하다.

2. 기술 스택과 버전

버전 차이로 코드가 달라지는 경우가 많다.

## Tech stack

- Python 3.12
- FastAPI
- Pydantic v2
- SQLAlchemy 2.x
- PostgreSQL
- pytest

특히 Pydantic v1과 v2, Next.js App Router와 Pages Router, React Server Components 같은 부분은 명시하는 편이 좋다.

3. 실행 명령어

AI가 테스트나 린트를 실행할 때 헷갈리지 않도록 적는다.

## Commands

- Install dependencies: `pnpm install`
- Run dev server: `pnpm dev`
- Run lint: `pnpm lint`
- Run tests: `pnpm test`

Python 프로젝트라면 이렇게 쓸 수 있다.

## Commands

- Create venv: `python -m venv .venv`
- Install dependencies: `pip install -r requirements.txt`
- Run server: `fastapi dev main.py`
- Run tests: `pytest`

여기서 중요한 점은 실제로 프로젝트에서 쓰는 명령어만 넣는 것이다. 언젠가 쓸 수도 있는 명령어까지 다 넣으면 오히려 헷갈린다.

4. 디렉터리 구조 규칙

AI가 파일을 잘못된 위치에 만드는 문제를 줄일 수 있다.

## Project structure

- API routes: `src/routes/`
- Business logic: `src/services/`
- Database models: `src/models/`
- Request and response schemas: `src/schemas/`
- Tests: `tests/`

프론트엔드 프로젝트라면 이렇게 쓸 수 있다.

## Project structure

- Page routes: `src/app/`
- Shared UI components: `src/components/`
- Feature-specific components: `src/features/{feature}/components/`
- API clients: `src/lib/api/`
- Hooks: `src/hooks/`

5. 코드 스타일

막연한 표현보다 검증 가능한 규칙이 좋다.

나쁜 예시는 다음과 같다.

- Write clean code.
- Keep files organized.
- Make good components.

이런 문장은 너무 추상적이다. AI도 사람도 해석이 다를 수 있다.

수정하면 이렇게 된다.

- Keep React components under 150 lines when possible.
- Move reusable logic into hooks.
- Use existing UI components before creating new ones.
- Do not add a new dependency without explaining why.

6. 보안과 위험한 작업 규칙

AI 코딩 도구는 파일을 수정하고 명령어를 실행할 수 있다. 그래서 위험한 작업은 명확히 제한하는 것이 좋다.

## Safety rules

- Do not modify `.env` files.
- Do not print secrets, API keys, or tokens.
- Ask before changing authentication logic.
- Ask before running database migration commands.
- Do not run destructive commands such as `rm -rf`, `DROP TABLE`, or forced git reset.

물론 지침 파일만으로 위험한 작업이 완전히 차단되는 것은 아니다. 도구의 권한 설정, 승인 모드, 훅, 샌드박스 설정도 함께 봐야 한다.

지침 파일은 안전장치라기보다 “작업 전 주의사항”에 가깝다.

지침 파일에 넣으면 안 되는 내용

지침 파일은 길수록 좋은 문서가 아니다.

오히려 너무 길면 AI가 중요한 규칙을 놓칠 수 있다.

1. 오래된 규칙

예를 들어 프로젝트가 npm에서 pnpm으로 바뀌었는데 예전 명령어가 남아 있으면 AI가 잘못된 명령어를 실행할 수 있다.

- Run `npm install`
- Run `pnpm install`

이렇게 충돌하는 규칙은 피해야 한다.

하나만 남기는 편이 낫다.

- Use `pnpm install`. Do not use npm or yarn.

2. 너무 일반적인 원칙

- Write good code.
- Follow best practices.
- Make it scalable.

이런 문장은 거의 도움이 되지 않는다.

대신 프로젝트에서 실제로 반복되는 실수로 바꿔야 한다.

- Do not put business logic inside route handlers.
- Add tests for service functions when changing calculation logic.
- Reuse existing error response format from `src/errors/`.

3. 비밀 정보

지침 파일은 보통 저장소에 커밋된다. 그래서 API 키, 토큰, 내부 비밀번호, 개인 계정 정보는 절대 넣으면 안 된다.

나쁜 예시는 다음과 같다.

- Use production API key: sk-...
- Admin password is ...

대신 이렇게 적어야 한다.

- Read required environment variables from `.env`.
- Do not create or expose real API keys in examples.
- Use placeholder values in documentation and tests.

4. 너무 긴 아키텍처 문서

긴 아키텍처 설명은 별도 문서로 분리하는 편이 낫다.

docs/architecture.md
docs/database.md
docs/api-style.md

그리고 지침 파일에서는 필요한 문서만 짧게 참조한다.

## References

- Architecture overview: `docs/architecture.md`
- API response format: `docs/api-style.md`

AI가 필요할 때 찾아 읽을 수 있도록 길을 알려주는 방식이다.

바로 쓸 수 있는 AGENTS.md 예시

아래 예시는 Codex 기준으로 바로 시작할 수 있는 단순한 AGENTS.md 템플릿이다.

# AGENTS.md

## Project overview

This project is a web application maintained by a small development team.
Follow the existing code style and avoid unnecessary rewrites.

## Tech stack

- TypeScript
- React
- Node.js
- pnpm

## Commands

- Install dependencies: `pnpm install`
- Run development server: `pnpm dev`
- Run lint: `pnpm lint`
- Run tests: `pnpm test`
- Do not use npm or yarn in this repository.

## Project structure

- Application code: `src/`
- Shared components: `src/components/`
- Feature modules: `src/features/`
- Utility functions: `src/lib/`
- Tests: `tests/`

## Coding rules

- Use TypeScript for new files.
- Reuse existing components before creating new ones.
- Do not add new dependencies unless necessary.
- Keep changes focused on the requested task.
- Do not perform broad refactoring unless explicitly requested.

## Safety rules

- Do not modify `.env` files.
- Do not expose secrets, tokens, or API keys.
- Ask before changing authentication, payment, or database migration logic.
- Do not run destructive commands without confirmation.

## Before finishing

- Run lint when changing TypeScript files.
- Run relevant tests when changing business logic.
- Summarize what changed and mention any tests that were not run.

이 정도면 처음 쓰기에는 충분하다.

중요한 건 처음부터 완성형 문서를 만들려고 하지 않는 것이다. AI가 같은 실수를 반복할 때마다 한 줄씩 추가하는 편이 더 현실적이다.

Claude Code용 CLAUDE.md 예시

Claude Code만 쓴다면 CLAUDE.md로 작성한다.

# CLAUDE.md

## Project overview

This is a backend API project.
Keep changes small and explain risky decisions before editing.

## Commands

- Run server: `fastapi dev main.py`
- Run tests: `pytest`
- Run formatter: `ruff format .`
- Run linter: `ruff check .`

## Architecture rules

- Route handlers should stay thin.
- Put business logic in service modules.
- Put request and response models in schema modules.
- Do not mix database models and API schemas.

## Safety rules

- Do not edit `.env` files.
- Do not print secrets or tokens.
- Ask before changing authentication logic.
- Ask before changing migration files.

## Workflow

- First inspect related files.
- Make the smallest change that solves the issue.
- Run relevant tests when possible.
- Explain any skipped tests.

이미 AGENTS.md가 있는 프로젝트에서 Claude Code도 같이 쓰려면 이렇게 구성할 수 있다.

@AGENTS.md

## Claude Code specific rules

- Use Plan Mode before large refactors.
- Ask before running database commands.

이 방식은 중복을 줄이는 데 좋다.

공통 규칙은 AGENTS.md에 두고, Claude Code 전용 규칙만 CLAUDE.md에 남기면 된다.

Cursor Rules 예시

Cursor에서는 .cursor/rules에 주제별 규칙을 나눠 둘 수 있다.

예를 들어 테스트 규칙은 이렇게 분리할 수 있다.

.cursor/rules/testing.mdc

# Testing rules

- Add or update tests when changing business logic.
- Prefer existing test helpers.
- Do not introduce a new testing library.
- If tests are not run, explain why.

API 규칙은 따로 둘 수 있다.

.cursor/rules/api.mdc

# API rules

- Follow the existing error response format.
- Validate input at the boundary.
- Do not return raw database models from API handlers.
- Keep authentication checks explicit.

Cursor만 쓴다면 이 방식이 깔끔하다. 여러 도구를 같이 쓴다면 공통 규칙은 AGENTS.md에 두고, Cursor에서만 필요한 규칙은 .cursor/rules에 분리하는 방식이 좋다.

도구별 추천 구성

AI 코딩 도구를 하나만 쓸 때는 단순하게 가면 된다.

Codex만 쓰는 경우

my-project/
├── AGENTS.md
├── src/
└── package.json

Claude Code만 쓰는 경우

my-project/
├── CLAUDE.md
├── src/
└── package.json

또는 다음처럼 둘 수 있다.

my-project/
├── .claude/
│   └── CLAUDE.md
├── src/
└── package.json

Cursor만 쓰는 경우

my-project/
├── .cursor/
│   └── rules/
│       ├── coding.mdc
│       ├── testing.mdc
│       └── api.mdc
├── src/
└── package.json

Codex와 Claude Code를 같이 쓰는 경우

my-project/
├── AGENTS.md
├── CLAUDE.md
├── src/
└── package.json

CLAUDE.md는 이렇게 작성한다.

@AGENTS.md

## Claude Code specific rules

- Use Plan Mode before large refactors.
- Ask before running destructive commands.

세 도구를 모두 쓰는 경우

my-project/
├── AGENTS.md
├── CLAUDE.md
├── .cursor/
│   └── rules/
│       ├── coding.mdc
│       └── testing.mdc
├── src/
└── package.json

이 구성에서는 AGENTS.md를 공통 기준으로 사용한다.

CLAUDE.md는 Claude Code가 AGENTS.md를 가져오게 만들고, .cursor/rules에는 Cursor에서만 세밀하게 적용할 규칙을 둔다.

예를 들어 공통 규칙은 AGENTS.md에 둔다.

# AGENTS.md

## Common rules

- Use pnpm only.
- Do not edit `.env` files.
- Keep changes focused.
- Run relevant tests after changing business logic.

Claude Code 전용 규칙은 CLAUDE.md에 둔다.

@AGENTS.md

## Claude Code specific rules

- Ask before running database commands.
- Explain skipped tests before finishing.

Cursor 전용 규칙은 .cursor/rules에 둔다.

# .cursor/rules/testing.mdc

- Prefer existing test helpers.
- Add tests near the changed feature.
- Do not introduce a new testing library.

이렇게 나누면 세 도구를 같이 쓰더라도 같은 규칙을 여러 파일에 반복해서 쓰지 않아도 된다.

자주 하는 오해

1. AGENTS.md를 만들면 AI가 무조건 그대로 따를까?

아니다.

지침 파일은 강제 설정이 아니라 컨텍스트에 가깝다. AI가 참고할 가능성을 높여주는 문서이지, 보안 정책처럼 무조건 차단하는 장치는 아니다.

정말 막아야 하는 작업이 있다면 도구의 권한 설정, 승인 모드, 훅, CI, 브랜치 보호 규칙 같은 실제 제어 장치가 필요하다.

예를 들어 “DB migration은 확인 없이 실행하지 마”라고 적는 것은 도움이 된다. 하지만 실제 운영 DB 접근 권한을 막는 것은 지침 파일이 아니라 권한 관리에서 해야 한다.

2. README 내용을 그대로 복사하면 될까?

일부는 가능하지만 그대로 복사하는 것은 별로 좋지 않다.

README는 사람을 위한 문서다. AI 지침 파일은 작업을 위한 문서다.

README의 긴 소개보다 다음 같은 짧은 규칙이 더 효과적이다.

- Use existing service patterns from `src/services/`.
- Do not create a new architecture for small changes.
- Run `pnpm test` after changing business logic.

3. 규칙을 많이 넣을수록 좋을까?

아니다.

규칙이 많아질수록 중요한 지침이 묻힌다. 서로 충돌하는 규칙이 생길 가능성도 커진다.

처음에는 30~80줄 정도로 시작하는 편이 좋다. 이후 AI가 반복해서 실수하는 부분만 추가한다.

4. 개인 취향도 커밋해야 할까?

팀 공통 규칙과 개인 취향은 분리하는 편이 좋다.

예를 들어 팀 전체가 따라야 하는 규칙은 커밋해도 된다.

- Use pnpm.
- Run tests before finishing backend changes.
- Follow the existing API response format.

하지만 개인 로컬 서버 주소, 개인 테스트 계정, 개인 선호 명령어는 커밋하지 않는 편이 안전하다.

Claude Code라면 CLAUDE.local.md 같은 로컬 파일을 쓸 수 있고, Cursor나 Codex도 개인 설정과 팀 공유 파일을 구분하는 방식으로 운영하는 것이 좋다.

지침 파일은 한 번에 완성하지 않는 편이 낫다

처음부터 완벽한 AGENTS.md를 만들려고 하면 대부분 너무 길어진다.

더 좋은 방식은 실제로 AI가 실수한 지점을 기준으로 업데이트하는 것이다.

예를 들어 AI가 npm을 사용했다면 이렇게 추가한다.

- Use pnpm in this repository. Do not use npm or yarn.

AI가 라우터 안에 비즈니스 로직을 길게 넣었다면 이렇게 추가한다.

- Keep route handlers thin. Move business logic into service modules.

AI가 테스트 없이 작업을 끝냈다면 이렇게 추가한다.

- Run relevant tests when changing business logic. If tests cannot be run, explain why.

이런 식으로 작성하면 지침 파일이 실제 프로젝트의 문제를 반영하게 된다.

반대로 인터넷에서 복사한 긴 템플릿을 그대로 넣으면 프로젝트와 맞지 않는 규칙이 섞일 수 있다. 이 부분을 오해하기 쉽다. 지침 파일은 많을수록 좋은 게 아니라, 현재 프로젝트에서 반복되는 실수를 줄일수록 좋은 문서다.

정리

AGENTS.md는 AI 코딩 에이전트에게 프로젝트의 작업 규칙을 알려주는 파일이다. Codex에서는 핵심 지침 파일로 쓰이며, 프로젝트 구조, 실행 명령어, 코드 스타일, 주의사항을 적어두는 데 적합하다.

다만 Claude Code는 AGENTS.md가 아니라 CLAUDE.md가 기본이다. 이미 AGENTS.md를 쓰는 프로젝트라면 CLAUDE.md에서 @AGENTS.md로 가져오는 방식이 좋다.

Cursor는 Cursor Rules를 중심으로 보는 것이 좋다. .cursor/rules에 규칙을 나눠두면 작업 범위별로 관리하기 쉽다. 여러 도구를 함께 쓴다면 공통 규칙은 AGENTS.md, Claude 전용 규칙은 CLAUDE.md, Cursor 전용 규칙은 .cursor/rules에 나누는 구성이 현실적이다.

지침 파일에 모든 것을 넣을 필요는 없다.

가장 먼저 넣을 내용은 반복해서 설명하게 되는 것들이다.

어떤 명령어를 쓰는지
파일을 어디에 만들어야 하는지
어떤 코드 스타일을 따라야 하는지
어떤 작업은 확인 후 진행해야 하는지
어떤 파일은 건드리면 안 되는지

특히 Codex나 Claude Code처럼 터미널에서 명령어를 직접 실행할 수 있는 도구를 쓴다면, 실행 명령어와 금지 명령어를 더 명확하게 적어두는 편이 좋다.

결국 좋은 지침 파일은 긴 문서가 아니라, AI가 같은 실수를 반복하지 않게 만드는 짧고 정확한 작업 기준이다.

FastAPI 환경변수 설정: .env로 DB 주소와 비밀키 분리하기

notebase — Thu, 4 Jun 2026 13:45:34 +0900

FastAPI에서 .env와 pydantic-settings를 사용해 DB 주소, SECRET_KEY, 디버그 설정을 코드와 분리하는 방법을 예제로 정리합니다.

FastAPI 환경변수 설정을 제대로 해두면 DB 주소, JWT 비밀키, 디버그 옵션을 코드에서 분리할 수 있다. 처음에는 main.py에 직접 적는 게 편해 보이지만, GitHub에 올리거나 서버에 배포하는 순간 문제가 될 수 있다.

이 글은 2026년 6월 기준 FastAPI 최신 버전과 Pydantic v2 흐름을 기준으로 작성했다. 설정 관리는 pydantic-settings를 사용하고, 로컬 개발 환경에서는 .env 파일을 함께 사용하는 방식으로 설명한다.

환경변수 설정은 단순히 .env 파일을 하나 만드는 작업이 아니다.
개발 환경과 운영 환경의 설정을 분리하고, 실수로 비밀값이 코드 저장소에 올라가지 않게 막는 구조에 가깝다.

왜 FastAPI에서 환경변수를 분리해야 할까?

예를 들어 아래처럼 DB 주소와 비밀키를 코드에 직접 넣었다고 해보자.

# main.py

DATABASE_URL = "sqlite:///./app.db"
SECRET_KEY = "my-secret-key"

로컬 테스트만 할 때는 문제없어 보인다.
하지만 실제 프로젝트에서는 다음 문제가 생긴다.

개발 DB와 운영 DB 주소를 바꾸기 어렵다.
JWT 비밀키가 코드에 그대로 노출된다.
GitHub에 올렸을 때 민감한 값이 함께 올라갈 수 있다.
Docker, 배포 서버, CI/CD 환경에서 설정을 바꾸기 불편하다.
팀원이 프로젝트를 실행할 때 필요한 설정값을 파악하기 어렵다.

여기서 중요한 점은 .env가 보안을 완성해 주는 도구는 아니라는 것이다.

.env는 주로 로컬 개발 환경에서 설정값을 분리하기 위한 파일이다.
운영 환경에서는 서버 환경변수, Docker secret, AWS Secrets Manager, GCP Secret Manager 같은 별도 비밀값 관리 방식을 쓰는 경우가 많다.

이 글에서 만들 구조

예시는 FastAPI 프로젝트에서 자주 쓰는 형태로 구성한다.

fastapi-env-example/
├── app/
│   ├── main.py
│   ├── config.py
│   └── database.py
├── .env
├── .env.example
├── .gitignore
└── requirements.txt

역할은 다음과 같다.

파일	역할
`.env`	실제 로컬 환경변수 값 저장
`.env.example`	필요한 환경변수 이름만 공유
`.gitignore`	`.env`가 Git에 올라가지 않도록 차단
`app/config.py`	환경변수를 읽는 설정 클래스
`app/database.py`	DB 연결 설정
`app/main.py`	FastAPI 앱에서 설정값 사용

실제로는 auth.py, routers/, schemas/, models/ 같은 파일이 더 생길 수 있다.
하지만 환경변수 흐름을 이해하는 데는 위 구조가 가장 단순하다.

1. 필요한 패키지 설치하기

먼저 FastAPI와 설정 관리에 필요한 패키지를 설치한다.

pip install fastapi uvicorn pydantic-settings python-dotenv

각 패키지의 역할은 다음과 같다.

패키지	역할
`fastapi`	FastAPI 웹 프레임워크
`uvicorn`	FastAPI 앱 실행 서버
`pydantic-settings`	환경변수 기반 설정 클래스 관리
`python-dotenv`	`.env` 파일 로드 지원

pydantic-settings는 Pydantic v2 흐름에서 설정 관리를 담당한다.
과거 Pydantic v1 예제를 보면 pydantic.BaseSettings를 사용하는 경우가 있는데, 최신 흐름에서는 pydantic_settings.BaseSettings를 사용하는 방식으로 이해하면 된다.

requirements.txt로 관리한다면 아래처럼 적을 수 있다.

fastapi
uvicorn
pydantic-settings
python-dotenv

JWT 예시 코드까지 직접 실행할 계획이라면 pyjwt도 추가한다.

fastapi
uvicorn
pydantic-settings
python-dotenv
pyjwt

주의할 점이 있다.

파이썬에서 JWT를 사용할 때는 보통 PyJWT 패키지를 설치한다.
설치 명령어는 아래처럼 작성한다.

pip install pyjwt

초보자들이 실수로 pip install jwt를 실행하는 경우가 있다.
그러면 예제에서 import jwt는 되는 것처럼 보여도, 실제로 jwt.encode()를 호출할 때 문제가 생길 수 있다.

2. .env 파일 만들기

프로젝트 루트에 .env 파일을 만든다.

DATABASE_URL=sqlite:///./app.db
SECRET_KEY=local-dev-secret-key
ACCESS_TOKEN_EXPIRE_MINUTES=30
DEBUG=true

여기서는 설명을 위해 SQLite 주소를 넣었다.
PostgreSQL을 사용한다면 이런 형태가 될 수 있다.

DATABASE_URL=postgresql://user:password@localhost:5432/mydb
SECRET_KEY=local-dev-secret-key
ACCESS_TOKEN_EXPIRE_MINUTES=30
DEBUG=true

주의할 점이 있다.

.env 파일 안의 값은 기본적으로 문자열 형태로 읽힌다.
그래서 30, true처럼 적어도 코드에서 숫자나 불리언으로 안전하게 쓰려면 변환 과정이 필요하다.

Pydantic Settings를 쓰면 이 변환과 검증을 설정 클래스에서 처리할 수 있다.

3. .env.example 파일 만들기

.env는 Git에 올리면 안 된다.
대신 어떤 환경변수가 필요한지 알려주는 .env.example 파일을 만든다.

DATABASE_URL=
SECRET_KEY=
ACCESS_TOKEN_EXPIRE_MINUTES=30
DEBUG=false

이 파일에는 실제 비밀번호나 비밀키를 넣지 않는다.

팀 프로젝트라면 새로 합류한 사람이 .env.example을 보고 .env를 직접 만들 수 있다.

cp .env.example .env

Windows PowerShell에서는 아래처럼 복사할 수 있다.

Copy-Item .env.example .env

이 방식은 블로그 예제뿐 아니라 실제 프로젝트에서도 자주 쓰인다.

4. .gitignore에 .env 추가하기

.env 파일이 Git에 올라가지 않도록 .gitignore에 추가한다.

.env
.venv/
__pycache__/
*.pyc

여기서 가장 중요한 줄은 .env다.

이미 .env를 Git에 커밋한 적이 있다면 .gitignore에 추가하는 것만으로는 부족하다.
Git 추적 대상에서 제거해야 한다.

git rm --cached .env

그다음 커밋한다.

git commit -m "Remove .env from tracking"

단, 이미 GitHub 같은 원격 저장소에 비밀키가 올라갔다면 단순 삭제로 끝내면 안 된다.
노출된 키는 폐기하고 새 키로 교체해야 한다.

예를 들어 JWT SECRET_KEY가 올라갔다면 새 키를 만들어 교체해야 한다.
외부 API Key나 DB 비밀번호가 올라갔다면 해당 서비스에서 키를 재발급하거나 비밀번호를 바꾸는 게 안전하다.

5. config.py에서 환경변수 읽기

이제 app/config.py 파일을 만든다.

# app/config.py

from functools import lru_cache

from pydantic_settings import BaseSettings, SettingsConfigDict


class Settings(BaseSettings):
    database_url: str
    secret_key: str
    access_token_expire_minutes: int = 30
    debug: bool = False

    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
    )


@lru_cache
def get_settings() -> Settings:
    return Settings()

여기서 핵심은 Settings 클래스다.

class Settings(BaseSettings):
    database_url: str
    secret_key: str

이렇게 적으면 Pydantic Settings가 환경변수에서 값을 읽는다.

.env 파일에는 대문자로 적었다.

DATABASE_URL=sqlite:///./app.db
SECRET_KEY=local-dev-secret-key

코드에서는 소문자 필드로 썼다.

database_url: str
secret_key: str

일반적으로 .env에는 대문자, Python 코드에는 소문자 필드를 쓰면 읽기 좋다.

6. @lru_cache는 왜 사용할까?

get_settings() 함수 위에 @lru_cache를 붙였다.

@lru_cache
def get_settings() -> Settings:
    return Settings()

이렇게 하면 설정 객체를 매번 새로 만들지 않고 재사용한다.

FastAPI 앱은 요청이 들어올 때마다 여러 의존성을 실행할 수 있다.
설정 파일을 매 요청마다 다시 읽을 필요는 없다.

@lru_cache를 붙이면 처음 한 번 생성한 설정 객체를 캐시해서 사용한다.
개발자가 보기에도 get_settings()를 통해 설정을 가져오는 흐름이 명확해진다.

7. main.py에서 설정값 사용하기

이제 FastAPI 앱에서 설정값을 사용해보자.

# app/main.py

from fastapi import Depends, FastAPI

from app.config import Settings, get_settings

app = FastAPI()


@app.get("/")
def read_root(settings: Settings = Depends(get_settings)):
    return {
        "message": "FastAPI environment settings example",
        "database_url": settings.database_url,
        "debug": settings.debug,
    }

서버를 실행한다.

uvicorn app.main:app --reload

브라우저에서 아래 주소로 접속한다.

http://127.0.0.1:8000

응답 예시는 다음과 비슷하다.

{
  "message": "FastAPI environment settings example",
  "database_url": "sqlite:///./app.db",
  "debug": true
}

여기서는 동작 확인을 위해 database_url을 응답에 포함했다.
하지만 실제 서비스에서는 DB 주소도 내부 정보에 가까우므로 외부 API 응답에 노출하지 않는 편이 좋다.

secret_key는 절대 응답으로 반환하면 안 된다.

8. SECRET_KEY는 어디에 사용할까?

SECRET_KEY는 보통 JWT 토큰 서명에 사용한다.

JWT 예시를 실행하려면 PyJWT를 설치해야 한다.

pip install pyjwt

pip install jwt가 아니라 pip install pyjwt다.
패키지 이름은 pyjwt지만, 코드에서는 아래처럼 import jwt로 사용한다.

# 예시 코드

from datetime import datetime, timedelta, timezone

import jwt

from app.config import get_settings


def create_access_token(data: dict) -> str:
    settings = get_settings()

    expire = datetime.now(timezone.utc) + timedelta(
        minutes=settings.access_token_expire_minutes
    )

    payload = data.copy()
    payload.update({"exp": expire})

    token = jwt.encode(
        payload,
        settings.secret_key,
        algorithm="HS256",
    )

    return token

이 코드는 JWT 흐름을 보여주기 위한 예시다.
실제 운영에서는 토큰 만료 시간, 알고리즘, refresh token, 비밀번호 해싱, HTTPS 적용까지 함께 고려해야 한다.

여기서 중요한 점은 settings.secret_key를 코드에 직접 적지 않는다는 것이다.

나쁜 예시는 아래와 같다.

token = jwt.encode(payload, "my-secret-key", algorithm="HS256")

수정한 예시는 아래와 같다.

settings = get_settings()

token = jwt.encode(
    payload,
    settings.secret_key,
    algorithm="HS256",
)

작은 차이처럼 보이지만, 배포 환경에서는 큰 차이가 된다.

9. DB 연결 코드에서 DATABASE_URL 사용하기

SQLAlchemy나 SQLModel을 사용할 때도 DB 주소를 환경변수에서 가져올 수 있다.

예시는 SQLAlchemy 기준이다.

# app/database.py

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

from app.config import get_settings

settings = get_settings()

engine = create_engine(
    settings.database_url,
    connect_args={"check_same_thread": False},
)

SessionLocal = sessionmaker(
    autocommit=False,
    autoflush=False,
    bind=engine,
)

SQLite를 사용할 때는 connect_args={"check_same_thread": False}를 자주 사용한다.
하지만 PostgreSQL 같은 DB에서는 이 옵션이 필요하지 않다.

PostgreSQL로 바꾸면 예시는 이렇게 달라질 수 있다.

engine = create_engine(settings.database_url)

즉, 환경변수로 DB 주소를 분리하면 코드 전체를 크게 바꾸지 않고 DB 연결 대상을 바꿀 수 있다.

10. 흔한 오류 1: .env 파일을 찾지 못하는 경우

가장 자주 만나는 문제는 .env 파일 위치다.

예를 들어 프로젝트 구조가 아래와 같다고 해보자.

fastapi-env-example/
├── app/
│   ├── main.py
│   └── config.py
└── .env

env_file=".env"는 보통 서버를 실행하는 현재 작업 디렉터리를 기준으로 찾는다.
프로젝트 루트에서 실행하면 정상이다.

uvicorn app.main:app --reload

하지만 다른 위치에서 실행하면 .env를 못 찾을 수 있다.

이럴 때는 먼저 현재 위치를 확인한다.

pwd

Windows PowerShell이라면 다음 명령어를 쓸 수 있다.

Get-Location

가장 단순한 해결 방법은 프로젝트 루트에서 서버를 실행하는 것이다.

cd fastapi-env-example
uvicorn app.main:app --reload

Tip. 실행 위치와 상관없이 루트의 .env를 읽고 싶다면

프로젝트가 커지면 실행 위치가 바뀌어도 항상 프로젝트 루트의 .env를 읽고 싶을 수 있다.
이럴 때는 config.py에서 절대 경로를 계산해 넣을 수 있다.

# app/config.py

from functools import lru_cache
from pathlib import Path

from pydantic_settings import BaseSettings, SettingsConfigDict

BASE_DIR = Path(__file__).resolve().parent.parent


class Settings(BaseSettings):
    database_url: str
    secret_key: str
    access_token_expire_minutes: int = 30
    debug: bool = False

    model_config = SettingsConfigDict(
        env_file=BASE_DIR / ".env",
        env_file_encoding="utf-8",
    )


@lru_cache
def get_settings() -> Settings:
    return Settings()

여기서 Path(__file__).resolve()는 현재 파일의 실제 경로를 찾는다.
parent.parent는 app/config.py에서 두 단계 위, 즉 프로젝트 루트를 가리킨다.

이 방식은 편리하지만, 프로젝트 구조가 바뀌면 BASE_DIR 계산도 함께 확인해야 한다.

11. 흔한 오류 2: 필수 환경변수가 없을 때

.env에서 SECRET_KEY를 빼고 실행하면 Pydantic 검증 오류가 날 수 있다.

DATABASE_URL=sqlite:///./app.db
ACCESS_TOKEN_EXPIRE_MINUTES=30
DEBUG=true

이 상태에서 Settings를 만들면 secret_key 값이 없기 때문이다.

오류 메시지는 버전에 따라 조금 다를 수 있지만, 대략 이런 형태다.

Field required [type=missing, input_value=..., input_type=dict]

이 오류는 오히려 좋은 신호다.
앱이 잘못된 설정으로 조용히 실행되는 것보다, 시작 단계에서 필요한 값이 없다고 알려주는 편이 안전하다.

해결 방법은 .env에 값을 추가하는 것이다.

SECRET_KEY=local-dev-secret-key

12. 흔한 오류 3: bool 값이 예상과 다르게 동작하는 경우

.env에는 모든 값이 문자열로 들어간다.

DEBUG=false

직접 os.getenv()만 사용하면 "false"라는 문자열이 반환된다.
문자열 "false"는 Python 조건문에서 True처럼 동작할 수 있다.

import os

debug = os.getenv("DEBUG")

if debug:
    print("debug mode")

이 코드는 DEBUG=false여도 "false" 문자열이 비어 있지 않기 때문에 조건문이 실행될 수 있다.

Pydantic Settings를 쓰면 debug: bool 타입으로 선언했을 때 적절히 bool 값으로 변환된다.

class Settings(BaseSettings):
    debug: bool = False

환경변수를 직접 읽는 방식보다 설정 클래스를 쓰는 이유가 여기에 있다.
단순히 값을 가져오는 것이 아니라, 타입 변환과 검증까지 함께 처리할 수 있다.

13. 흔한 오류 4: jwt 패키지를 잘못 설치한 경우

JWT 예제를 따라 하다가 아래 같은 오류를 만날 수 있다.

AttributeError: module 'jwt' has no attribute 'encode'

이 경우 먼저 설치한 패키지를 확인해보는 것이 좋다.

pip list | grep -i jwt

Windows PowerShell에서는 아래처럼 확인할 수 있다.

pip list | findstr /i jwt

jwt라는 다른 패키지를 설치했다면 제거하고 PyJWT를 다시 설치한다.

pip uninstall jwt
pip install pyjwt

코드에서는 그대로 import jwt를 사용한다.

import jwt

헷갈리기 쉬운 부분은 패키지 설치 이름과 import 이름이 다르다는 점이다.

구분	값
설치 명령어	`pip install pyjwt`
코드 import	`import jwt`
주요 사용	`jwt.encode()`, `jwt.decode()`

이 부분은 FastAPI 문제가 아니라 Python 패키지 이름 때문에 생기는 혼동에 가깝다.

14. 운영 환경에서는 .env를 그대로 써도 될까?

로컬 개발에서는 .env를 써도 괜찮다.
하지만 운영 환경에서는 상황에 따라 다르게 접근해야 한다.

환경	권장 방식
로컬 개발	`.env` 파일
개인 테스트 서버	서버 환경변수 또는 제한된 `.env`
Docker	`--env-file`, Docker Compose 환경변수, secret 관리
클라우드 배포	플랫폼 환경변수 또는 Secret Manager
팀/회사 운영	AWS Secrets Manager, GCP Secret Manager, Vault, CI/CD Secret

Secret Manager는 비밀번호, API Key, 토큰 같은 민감한 값을 안전하게 저장하고 접근 권한을 관리하는 서비스다.
AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault 같은 도구가 여기에 해당한다.

운영 서버에 .env를 둘 수는 있다.
다만 권한 관리, 백업, 배포 로그 노출, 서버 접근 권한까지 함께 봐야 한다.

특히 아래 값은 더 조심해야 한다.

DB 비밀번호
JWT SECRET_KEY
OAuth Client Secret
외부 API Key
SMTP 비밀번호
관리자 초기 비밀번호

.env를 쓴다고 해서 비밀값이 자동으로 안전해지는 것은 아니다.
Git에 올리지 않고, 로그에 찍지 않고, 노출되면 즉시 교체할 수 있어야 한다.

15. 환경변수 이름은 어떻게 정하면 좋을까?

작은 프로젝트라면 아래처럼 단순하게 써도 된다.

DATABASE_URL=
SECRET_KEY=
DEBUG=

프로젝트가 커지면 접두사를 붙이는 것도 좋다.

APP_DATABASE_URL=
APP_SECRET_KEY=
APP_DEBUG=

이 경우 설정 클래스도 접두사를 인식하도록 만들 수 있다.

# app/config.py

from functools import lru_cache

from pydantic_settings import BaseSettings, SettingsConfigDict


class Settings(BaseSettings):
    database_url: str
    secret_key: str
    debug: bool = False

    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        env_prefix="APP_",
    )


@lru_cache
def get_settings() -> Settings:
    return Settings()

이렇게 하면 .env의 APP_DATABASE_URL 값이 database_url 필드로 들어간다.

프로젝트 하나만 운영한다면 필수는 아니다.
하지만 여러 앱을 같은 서버에서 실행하거나, 환경변수 이름이 겹칠 가능성이 있다면 접두사를 붙이는 편이 안전하다.

16. 초보자가 자주 하는 실수 정리

FastAPI에서 .env를 쓸 때 자주 하는 실수는 비슷하다.

실수	문제	해결
`.env`를 Git에 올림	비밀값 노출	`.gitignore` 추가, 노출된 키 교체
`SECRET_KEY`를 코드에 직접 작성	배포 후 교체 어려움	환경변수로 분리
`.env.example`을 만들지 않음	협업 시 필요한 값 파악 어려움	변수 이름만 담은 예시 파일 작성
`os.getenv()`만 사용	타입 변환 실수 가능	Pydantic Settings 사용
`.env` 위치를 잘못 둠	설정값 로드 실패	프로젝트 루트 실행 또는 절대 경로 지정
`pip install jwt` 실행	`jwt.encode()` 오류 가능	`pip install pyjwt` 사용
운영 서버에서 로컬 `.env` 그대로 사용	보안/운영 위험	서버 환경변수 또는 Secret Manager 검토

실제로는 .env 파일 하나보다 이 체크리스트가 더 중요하다.
설정값을 어디에 두는지보다, 노출되면 어떤 영향을 주는지 먼저 판단해야 한다.

전체 코드 예시

마지막으로 최소 실행 예시를 한 번에 정리하면 다음과 같다.

`.env`

DATABASE_URL=sqlite:///./app.db
SECRET_KEY=local-dev-secret-key
ACCESS_TOKEN_EXPIRE_MINUTES=30
DEBUG=true

`.env.example`

DATABASE_URL=
SECRET_KEY=
ACCESS_TOKEN_EXPIRE_MINUTES=30
DEBUG=false

`.gitignore`

.env
.venv/
__pycache__/
*.pyc

`requirements.txt`

fastapi
uvicorn
pydantic-settings
python-dotenv
pyjwt

`app/config.py`

from functools import lru_cache
from pathlib import Path

from pydantic_settings import BaseSettings, SettingsConfigDict

BASE_DIR = Path(__file__).resolve().parent.parent


class Settings(BaseSettings):
    database_url: str
    secret_key: str
    access_token_expire_minutes: int = 30
    debug: bool = False

    model_config = SettingsConfigDict(
        env_file=BASE_DIR / ".env",
        env_file_encoding="utf-8",
    )


@lru_cache
def get_settings() -> Settings:
    return Settings()

`app/main.py`

from fastapi import Depends, FastAPI

from app.config import Settings, get_settings

app = FastAPI()


@app.get("/")
def read_root(settings: Settings = Depends(get_settings)):
    return {
        "message": "FastAPI environment settings example",
        "database_url": settings.database_url,
        "debug": settings.debug,
    }

실행 명령어

uvicorn app.main:app --reload

브라우저에서 아래 주소로 접속한다.

http://127.0.0.1:8000

마무리

FastAPI에서 .env를 쓰는 목적은 단순히 파일을 하나 더 만드는 것이 아니다.
DB 주소, 비밀키, 토큰 만료 시간처럼 환경마다 달라지는 값을 코드에서 분리하는 것이다.

입문 단계에서는 아래 기준만 지켜도 충분하다.

실제 값은 .env에 둔다.
.env는 Git에 올리지 않는다.
공유용으로 .env.example을 만든다.
설정값은 pydantic-settings로 읽고 검증한다.
JWT 예제에서는 pip install pyjwt를 사용한다.
비밀키는 API 응답이나 로그에 출력하지 않는다.
운영 환경에서는 서버 환경변수나 Secret Manager 사용을 검토한다.

처음에는 os.getenv()로도 충분해 보일 수 있다.
하지만 DB 주소, JWT 비밀키, 디버그 모드, 토큰 만료 시간처럼 설정값이 늘어나면 Pydantic Settings로 관리하는 편이 훨씬 안정적이다.

파이썬 openpyxl 엑셀 자동화 기초: 파일 만들기부터 수정까지

notebase — Tue, 2 Jun 2026 09:11:57 +0900

파이썬 openpyxl로 엑셀 파일을 만들고, 읽고, 수정하고, 저장하는 기본 흐름을 초보자 기준으로 정리합니다. 자주 발생하는 오류와 사용 시 주의할 점도 함께 다룹니다.

엑셀 파일을 매번 열어서 값을 붙여넣고, 날짜를 바꾸고, 합계를 확인하는 작업이 반복된다면 openpyxl을 써볼 만합니다. 파이썬으로 .xlsx 파일을 만들고, 읽고, 수정하고, 다시 저장할 수 있기 때문입니다.

다만 처음부터 “회사 업무 전체를 자동화하겠다”는 식으로 접근하면 금방 막힙니다. 먼저 엑셀 파일 구조를 파이썬 코드로 어떻게 다루는지 이해하는 게 중요합니다.

이 글은 openpyxl을 처음 쓰는 사람을 기준으로, 가장 기본이 되는 흐름만 정리합니다.

엑셀 파일 새로 만들기
셀에 값 입력하기
기존 엑셀 파일 읽기
기존 파일 수정 후 저장하기
자주 발생하는 오류 확인하기

openpyxl은 버전에 따라 일부 사용법이 달라질 수 있습니다. 이 글은 2026년 6월 기준으로 공개된 openpyxl 문서와 PyPI 정보를 바탕으로 작성했습니다.

openpyxl은 언제 쓰면 좋을까?

openpyxl은 파이썬에서 엑셀 파일을 다룰 때 많이 쓰는 라이브러리입니다. 특히 .xlsx 파일을 직접 만들거나 수정할 때 유용합니다.

예를 들면 이런 작업에 사용할 수 있습니다.

매일 같은 양식의 엑셀 보고서 만들기
기존 엑셀 파일에서 특정 셀 값 읽기
여러 행의 데이터를 자동으로 추가하기
엑셀 파일의 시트 이름, 셀 값, 간단한 스타일 수정하기
반복적인 정산표, 재고표, 목록 파일 생성하기

여기서 중요한 점은 openpyxl이 “엑셀 프로그램을 대신 클릭해주는 도구”는 아니라는 점입니다.

엑셀 앱을 자동으로 실행해서 마우스로 조작하는 방식이 아니라, .xlsx 파일 자체를 파이썬 코드로 읽고 쓰는 방식에 가깝습니다.

그래서 단순한 반복 파일 작업에는 잘 맞지만, 엑셀 화면에서 버튼을 누르거나 매크로를 실행하는 자동화와는 성격이 다릅니다.

openpyxl 설치하기

먼저 터미널에서 openpyxl을 설치합니다.

pip install openpyxl

가상환경을 사용 중이라면 가상환경을 먼저 활성화한 뒤 설치하는 것이 좋습니다.

예를 들어 macOS나 Linux에서는 다음처럼 사용할 수 있습니다.

python -m venv .venv
source .venv/bin/activate
pip install openpyxl

Windows PowerShell에서는 보통 다음 흐름을 사용합니다.

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install openpyxl

설치가 잘 되었는지 확인하려면 파이썬에서 import 해보면 됩니다.

import openpyxl

print(openpyxl.__version__)

이 코드에서 에러가 나지 않으면 기본 설치는 완료된 상태입니다.

openpyxl의 기본 구조 이해하기

openpyxl을 쓰기 전에 엑셀 파일 구조를 간단히 정리하면 이해가 쉬워집니다.

엑셀 파일은 대략 이런 구조입니다.

엑셀 파일 Workbook
 └── 시트 Worksheet
      └── 셀 Cell

예를 들어 sales.xlsx라는 파일 안에 1월매출, 2월매출 같은 시트가 있고, 각 시트 안에 A1, B2 같은 셀이 있는 구조입니다.

openpyxl 코드에서도 이 구조를 그대로 다룹니다.

Workbook: 엑셀 파일 전체
Worksheet: 엑셀 파일 안의 시트
Cell: 시트 안의 개별 셀

이 구조를 알고 있으면 코드가 훨씬 덜 낯설게 보입니다.

새 엑셀 파일 만들기

가장 먼저 새 엑셀 파일을 만들어보겠습니다.

파일명은 create_excel.py로 작성합니다.

# create_excel.py

from openpyxl import Workbook

# 새 엑셀 파일 생성
workbook = Workbook()

# 현재 활성화된 시트 선택
sheet = workbook.active

# 시트 이름 변경
sheet.title = "매출현황"

# 셀에 값 입력
sheet["A1"] = "상품명"
sheet["B1"] = "수량"
sheet["C1"] = "단가"

sheet["A2"] = "키보드"
sheet["B2"] = 3
sheet["C2"] = 50000

sheet["A3"] = "마우스"
sheet["B3"] = 5
sheet["C3"] = 20000

# 엑셀 파일 저장
workbook.save("sales_report.xlsx")

실행합니다.

python create_excel.py

실행 후 같은 폴더에 sales_report.xlsx 파일이 만들어졌다면 성공입니다.

실제로는 여기서부터 엑셀 자동화가 시작됩니다. 사람이 직접 엑셀을 열고 표를 만드는 대신, 파이썬 코드가 정해진 형식으로 파일을 만들어주는 방식입니다.

셀 값 입력 방식: A1 방식과 row/column 방식

openpyxl에서는 셀을 지정하는 방법이 크게 두 가지입니다.

첫 번째는 엑셀에서 익숙한 A1, B2 방식입니다.

sheet["A1"] = "이름"
sheet["B1"] = "점수"

두 번째는 행 번호와 열 번호를 사용하는 방식입니다.

sheet.cell(row=1, column=1).value = "이름"
sheet.cell(row=1, column=2).value = "점수"

처음에는 A1 방식이 더 직관적입니다. 하지만 반복문을 사용할 때는 row, column 방식이 더 편합니다.

예를 들어 여러 명의 점수를 한 번에 입력할 때는 다음처럼 작성할 수 있습니다.

# write_rows.py

from openpyxl import Workbook

workbook = Workbook()
sheet = workbook.active
sheet.title = "점수표"

students = [
    ["이름", "국어", "영어", "수학"],
    ["김민수", 90, 85, 88],
    ["이서연", 78, 92, 81],
    ["박지훈", 88, 76, 95],
]

for row_index, row_data in enumerate(students, start=1):
    for column_index, value in enumerate(row_data, start=1):
        sheet.cell(row=row_index, column=column_index).value = value

workbook.save("score.xlsx")

여기서 enumerate(..., start=1)을 사용한 이유는 엑셀의 행과 열 번호가 1부터 시작하기 때문입니다.

파이썬 리스트 인덱스는 0부터 시작하지만, 엑셀의 첫 번째 행은 1행이고 첫 번째 열은 A열입니다. 이 부분을 헷갈리면 값이 예상과 다른 위치에 들어갈 수 있습니다.

기존 엑셀 파일 읽기

이번에는 이미 존재하는 엑셀 파일을 읽어보겠습니다.

앞에서 만든 sales_report.xlsx 파일을 기준으로 설명합니다.

파일명은 read_excel.py로 작성합니다.

# read_excel.py

from openpyxl import load_workbook

workbook = load_workbook("sales_report.xlsx")
sheet = workbook["매출현황"]

print(sheet["A1"].value)
print(sheet["B2"].value)
print(sheet["C3"].value)

실행합니다.

python read_excel.py

예상 출력은 다음과 비슷합니다.

상품명
3
20000

기존 엑셀 파일을 열 때는 Workbook()이 아니라 load_workbook()을 사용합니다.

이 부분을 자주 헷갈립니다.

새 파일을 만들 때: Workbook()
기존 파일을 읽을 때: load_workbook("파일명.xlsx")

기존 엑셀 파일 수정하기

기존 파일을 읽은 뒤 특정 값을 수정하고 다시 저장할 수도 있습니다.

# update_excel.py

from openpyxl import load_workbook

workbook = load_workbook("sales_report.xlsx")
sheet = workbook["매출현황"]

# 기존 값 수정
sheet["B2"] = 10

# 새 행 추가
sheet.append(["모니터", 2, 180000])

# 다른 이름으로 저장
workbook.save("sales_report_updated.xlsx")

여기서 sheet.append()는 시트의 마지막 행 다음에 데이터를 추가합니다.

실무에서는 원본 파일을 바로 덮어쓰기보다, 처음에는 다른 이름으로 저장하는 편이 안전합니다.

workbook.save("sales_report_updated.xlsx")

이렇게 하면 실수로 원본 파일을 망가뜨렸을 때 다시 돌아갈 수 있습니다.

여러 행을 읽는 방법

엑셀 자동화에서는 특정 셀 하나만 읽는 경우보다 여러 행을 반복해서 읽는 경우가 더 많습니다.

# read_rows.py

from openpyxl import load_workbook

workbook = load_workbook("sales_report.xlsx")
sheet = workbook["매출현황"]

for row in sheet.iter_rows(min_row=2, values_only=True):
    product_name = row[0]
    quantity = row[1]
    price = row[2]

    print(product_name, quantity, price)

min_row=2를 사용한 이유는 첫 번째 행이 제목 행이기 때문입니다.

상품명 | 수량 | 단가

이런 헤더 행까지 데이터로 처리하면 계산이나 저장 과정에서 오류가 생길 수 있습니다.

values_only=True를 사용하면 셀 객체가 아니라 셀 안의 값만 가져옵니다. 초보자 입장에서는 이 옵션을 켜고 시작하는 편이 이해하기 쉽습니다.

간단한 합계 열 추가하기

이번에는 수량과 단가를 곱해서 합계 열을 만들어보겠습니다.

# add_total.py

from openpyxl import load_workbook

workbook = load_workbook("sales_report.xlsx")
sheet = workbook["매출현황"]

# 헤더 추가
sheet["D1"] = "합계"

# 2행부터 마지막 행까지 반복
for row_number in range(2, sheet.max_row + 1):
    quantity = sheet[f"B{row_number}"].value
    price = sheet[f"C{row_number}"].value

    total = quantity * price
    sheet[f"D{row_number}"] = total

workbook.save("sales_report_with_total.xlsx")

여기서 sheet.max_row는 현재 시트에서 사용 중인 마지막 행 번호를 의미합니다.

이 예시는 단순하지만 실제 업무 자동화에 꽤 자주 쓰이는 패턴입니다.

기존 파일 읽기
특정 열 값 가져오기
계산하기
새 열에 결과 입력하기
새 파일로 저장하기

이 흐름만 익혀도 반복적인 엑셀 작업을 꽤 많이 줄일 수 있습니다.

엑셀 수식 입력하기

openpyxl로 엑셀 수식도 입력할 수 있습니다.

# add_formula.py

from openpyxl import load_workbook

workbook = load_workbook("sales_report.xlsx")
sheet = workbook["매출현황"]

sheet["D1"] = "합계"
sheet["D2"] = "=B2*C2"
sheet["D3"] = "=B3*C3"

workbook.save("sales_report_formula.xlsx")

주의할 점이 있습니다.

openpyxl은 수식을 “입력”할 수는 있지만, 엑셀처럼 수식을 직접 계산하는 도구는 아닙니다.

즉, =B2*C2라는 수식을 파일에 넣을 수는 있지만, 계산 결과를 바로 파이썬에서 기대하면 안 됩니다. 수식 계산은 보통 엑셀 프로그램에서 파일을 열 때 처리됩니다.

이 부분을 오해하기 쉽습니다.

계산 결과가 파이썬 코드 안에서 바로 필요하다면 수식 문자열을 넣기보다, 앞에서 본 것처럼 파이썬에서 직접 계산해서 값을 넣는 방식이 더 단순합니다.

자주 발생하는 오류와 해결 방법

1. ModuleNotFoundError: No module named 'openpyxl'

ModuleNotFoundError: No module named 'openpyxl'

openpyxl이 설치되지 않았거나, 설치한 파이썬 환경과 실행 중인 파이썬 환경이 다른 경우입니다.

먼저 다음 명령어로 설치합니다.

pip install openpyxl

그래도 안 된다면 현재 사용하는 파이썬에 직접 설치합니다.

python -m pip install openpyxl

가상환경을 사용 중이라면 가상환경이 활성화되어 있는지도 확인해야 합니다.

2. FileNotFoundError: 파일을 찾을 수 없음

FileNotFoundError: [Errno 2] No such file or directory: 'sales_report.xlsx'

이 오류는 코드에서 지정한 엑셀 파일이 현재 실행 위치에 없을 때 발생합니다.

예를 들어 코드에서는 이렇게 작성했는데,

load_workbook("sales_report.xlsx")

실제 파일이 다른 폴더에 있으면 오류가 납니다.

해결 방법은 두 가지입니다.

첫 번째는 파이썬 파일과 엑셀 파일을 같은 폴더에 두는 것입니다.

두 번째는 파일 경로를 정확히 지정하는 것입니다.

load_workbook("data/sales_report.xlsx")

처음 연습할 때는 같은 폴더에 두고 시작하는 편이 덜 헷갈립니다.

3. KeyError: Worksheet does not exist

KeyError: 'Worksheet 매출현황 does not exist.'

엑셀 파일 안에 해당 이름의 시트가 없을 때 발생합니다.

예를 들어 코드에서 이렇게 작성했는데,

sheet = workbook["매출현황"]

실제 시트 이름이 Sheet, 매출 현황, 매출현황 처럼 다르면 오류가 납니다.

시트 이름을 먼저 확인해보면 됩니다.

print(workbook.sheetnames)

출력된 이름을 그대로 복사해서 사용하는 것이 가장 안전합니다.

4. PermissionError: 파일 권한 오류

PermissionError: [Errno 13] Permission denied: 'sales_report.xlsx'

Windows 환경에서 자주 볼 수 있는 오류입니다.

대부분 엑셀 파일을 Microsoft Excel에서 열어둔 상태로 파이썬에서 저장하려고 할 때 발생합니다.

해결 방법은 간단합니다.

엑셀 프로그램에서 해당 파일을 닫고 다시 실행하면 됩니다.

운영 자동화에서는 이 문제를 막기 위해 원본 파일을 직접 덮어쓰기보다 결과 파일을 새 이름으로 저장하는 방식이 더 안전합니다.

openpyxl을 쓸 때 알아두면 좋은 제한사항

openpyxl은 편리하지만 모든 엑셀 작업에 적합한 도구는 아닙니다.

다음 상황에서는 주의가 필요합니다.

상황	주의할 점
`.xls` 파일 처리	openpyxl은 주로 `.xlsx` 계열 파일에 사용한다
복잡한 엑셀 수식 계산	수식 입력은 가능하지만 계산 엔진은 아니다
엑셀 화면 조작	엑셀 앱을 직접 클릭하거나 조작하는 도구는 아니다
매우 큰 파일 처리	파일 크기가 크면 속도와 메모리 사용량을 고려해야 한다
매크로 실행	매크로 실행 자동화 도구로 보면 안 된다

특히 .xls와 .xlsx 차이를 헷갈리는 경우가 많습니다.

요즘 엑셀 파일은 대부분 .xlsx지만, 오래된 파일은 .xls일 수 있습니다. 파일 확장자가 .xls라면 openpyxl로 바로 처리하기 어렵기 때문에 파일 형식을 먼저 확인해야 합니다.

실습 예제: 매출표 자동 생성하기

마지막으로 간단한 실습 예제를 하나로 정리해보겠습니다.

목표는 상품명, 수량, 단가 데이터를 이용해서 엑셀 매출표를 자동 생성하는 것입니다.

파일명은 sales_automation.py로 작성합니다.

# sales_automation.py

from openpyxl import Workbook
from openpyxl.styles import Font

sales_data = [
    ["키보드", 3, 50000],
    ["마우스", 5, 20000],
    ["모니터", 2, 180000],
    ["노트북 거치대", 4, 35000],
]

workbook = Workbook()
sheet = workbook.active
sheet.title = "매출현황"

# 헤더 작성
headers = ["상품명", "수량", "단가", "합계"]
sheet.append(headers)

# 헤더 글씨 굵게
for cell in sheet[1]:
    cell.font = Font(bold=True)

# 데이터 작성
for item in sales_data:
    product_name = item[0]
    quantity = item[1]
    price = item[2]
    total = quantity * price

    sheet.append([product_name, quantity, price, total])

# 열 너비 조정
sheet.column_dimensions["A"].width = 18
sheet.column_dimensions["B"].width = 10
sheet.column_dimensions["C"].width = 12
sheet.column_dimensions["D"].width = 12

workbook.save("monthly_sales.xlsx")

실행합니다.

python sales_automation.py

결과로 monthly_sales.xlsx 파일이 생성됩니다.

위 코드에서 Font(bold=True)는 첫 번째 행의 제목 글씨를 굵게 만드는 역할을 합니다. column_dimensions["A"].width처럼 열 너비를 지정하면 엑셀 파일을 열었을 때 값이 잘리지 않아 결과물을 확인하기 편합니다.

다만 서식 자동화는 처음부터 많이 넣기보다, 데이터 입력과 저장 흐름을 먼저 익힌 뒤 필요한 만큼만 추가하는 편이 좋습니다. 엑셀 자동화의 핵심은 화려한 디자인보다 정확한 데이터를 반복해서 안정적으로 넣는 것입니다.

sales_automation.py 실행결과인 monthly_sales.xlsx 파일

위 이미지는 sales_automation.py를 실행한 뒤 생성된 monthly_sales.xlsx 파일을 열어 캡처하면 됩니다. 상품명, 수량, 단가, 합계가 표 형태로 들어간 화면을 보여주면 독자가 코드 실행 결과를 바로 이해할 수 있습니다.

이 예제는 단순하지만 엑셀 자동화의 기본 흐름을 대부분 포함합니다.

데이터를 리스트로 준비한다
새 엑셀 파일을 만든다
헤더를 작성한다
반복문으로 데이터를 넣는다
계산 결과를 추가한다
보기 좋게 일부 스타일을 적용한다
파일로 저장한다

실제로는 sales_data 부분을 데이터베이스, CSV 파일, API 응답, 크롤링 결과 등으로 바꿔서 사용할 수 있습니다.

openpyxl 기초 학습 순서

openpyxl을 처음 배운다면 모든 기능을 한 번에 보려고 하지 않는 편이 좋습니다.

다음 순서로 익히면 덜 막힙니다.

새 엑셀 파일 만들기
셀에 값 입력하기
기존 엑셀 파일 읽기
반복문으로 여러 행 읽고 쓰기
기존 파일 수정 후 다른 이름으로 저장하기
간단한 스타일 적용하기
실제 반복 업무 파일에 적용하기

처음부터 차트, 이미지, 병합 셀, 복잡한 스타일을 다루면 코드가 금방 복잡해집니다.

먼저 “값을 읽고 쓰는 자동화”부터 익히는 것이 좋습니다. 대부분의 업무 자동화는 화려한 서식보다 정확한 데이터 입력과 저장이 더 중요합니다.

마무리

openpyxl은 파이썬으로 엑셀 파일을 다룰 때 입문자가 접근하기 좋은 라이브러리입니다. 새 파일을 만들고, 기존 파일을 읽고, 셀 값을 수정하고, 반복문으로 여러 행을 처리하는 기본 흐름만 익혀도 반복적인 엑셀 작업을 줄일 수 있습니다.

다만 openpyxl을 엑셀 프로그램 자체의 대체재로 보면 안 됩니다. 수식 계산, 매크로 실행, 화면 조작까지 모두 처리하는 도구가 아니라 .xlsx 파일을 코드로 읽고 쓰는 도구에 가깝습니다.

처음에는 원본 파일을 바로 덮어쓰지 말고, 항상 다른 이름으로 저장하면서 연습하는 것이 안전합니다. 그다음 자주 반복하는 보고서나 정리 파일 하나를 골라 작은 자동화부터 적용해보면 됩니다.

Gemini CLI 종료? Antigravity CLI로 바뀌는 이유 정리

notebase — Mon, 1 Jun 2026 15:09:14 +0900

Gemini CLI 종료 이슈와 Antigravity CLI 전환 이유를 정리했습니다. 개인·기업용 차이와 기존 사용자의 점검 사항도 살펴봅니다.

Gemini CLI를 쓰고 있었다면 가장 먼저 확인해야 할 점은 하나다.
이 변화는 단순한 이름 변경이 아니라, Google이 터미널용 AI 코딩 도구를 Antigravity 플랫폼 안으로 통합하는 전환에 가깝다.

개인 사용자 기준으로는 Gemini CLI를 계속 그대로 쓰기 어렵다. Google은 Gemini CLI와 Gemini Code Assist IDE 확장이 개인 사용자, Google AI Pro, Google AI Ultra 사용자 대상으로 요청 처리를 중단한다고 안내했다.

다만 모든 사용자가 한 번에 끊기는 것은 아니다.
기업용 라이선스나 Google Cloud 기반으로 사용하는 경우에는 조건이 다르다.

Gemini CLI는 정말 종료되는 걸까

정확히 말하면, 개인 사용자가 쓰던 Gemini CLI는 Antigravity CLI로 넘어가는 흐름이다.

Google은 Gemini CLI를 Antigravity CLI로 전환한다고 공식 발표했다. 대상에는 개인용 Gemini Code Assist를 통해 무료로 사용하던 사용자, Google AI Pro, Google AI Ultra 사용자가 포함된다.

영향을 받는 항목은 크게 두 가지다.

Gemini CLI
Gemini Code Assist IDE 확장

즉, 터미널에서 Gemini CLI를 쓰던 사람뿐 아니라 VS Code 같은 IDE에서 Gemini Code Assist 확장을 사용하던 사람도 영향을 받을 수 있다.

다만 기업 사용자는 조금 다르다.
Gemini Code Assist Standard 또는 Enterprise 라이선스를 사용하는 조직, Google Cloud를 통해 Gemini Code Assist for GitHub를 사용하는 조직은 기존 접근이 유지된다고 안내되어 있다.

그래서 “Gemini CLI가 완전히 사라진다”라고만 말하면 조금 부정확하다.
개인 사용자 중심의 기존 Gemini CLI 흐름은 Antigravity CLI로 전환되고, 기업용 경로는 별도로 유지되는 구조에 가깝다.

Gemini CLI에서 Antigravity CLI로 바뀌는 이유

표면적으로는 제품명 변경처럼 보이지만, Google이 설명한 핵심 이유는 개발 워크플로우의 변화다.

Gemini CLI는 터미널에서 Gemini 모델을 바로 호출할 수 있는 가벼운 도구였다. 간단한 코드 질문, 파일 수정, 프로젝트 생성, 명령 실행 보조에는 잘 맞았다.

그런데 AI 코딩 도구의 방향이 바뀌고 있다.

이전에는 “터미널에서 모델에게 물어보고 답을 받는 방식”이 중심이었다면, 지금은 여러 에이전트가 나눠서 작업하고, 파일을 수정하고, 명령을 실행하고, 긴 작업을 백그라운드에서 처리하는 흐름으로 이동하고 있다.

Google이 Antigravity를 강조하는 이유도 여기에 있다.
Antigravity는 단순 CLI 하나가 아니라, 데스크톱 앱과 CLI가 같은 에이전트 기반 구조를 공유하는 개발 플랫폼에 가깝다.

여기서 중요한 점은 Gemini CLI가 실패해서 사라진다기보다, Google이 AI 코딩 도구의 중심을 “단일 터미널 도구”에서 “에이전트 플랫폼”으로 옮기고 있다는 점이다.

Antigravity CLI는 Gemini CLI와 무엇이 다른가

Antigravity CLI는 터미널에서 쓰는 AI 코딩 도구라는 점에서는 Gemini CLI와 비슷하다.
하지만 방향은 조금 다르다.

Gemini CLI가 비교적 가볍고 직접적인 터미널 인터페이스였다면, Antigravity CLI는 Antigravity 2.0과 같은 에이전트 엔진을 공유하는 CLI다.

공식 자료 기준으로 Antigravity CLI는 다음 흐름을 강조한다.

구분	Gemini CLI	Antigravity CLI
아키텍처 성격	터미널 중심 AI 도구	Antigravity 플랫폼 연계형 CLI
핵심 워크플로우	모델 호출, 코드 보조, 명령 실행	멀티 에이전트, 백그라운드 작업, 통합 에이전트 구조
확장 방식	Extensions 계열	Antigravity plugins 중심
연동 범위	로컬 터미널 중심	터미널, SSH, Antigravity 2.0 연계
전략적 방향성	가벼운 단독 CLI 도구	에이전트 기반 개발 플랫폼의 일부

Google은 Antigravity CLI가 Gemini CLI의 핵심 기능을 일부 유지한다고 설명한다.
대표적으로 Agent Skills, Hooks, Subagents, Extensions 계열 기능이 Antigravity 쪽으로 이어진다. 다만 처음부터 1:1 기능 동등성이 보장되는 것은 아니라고 밝히고 있다.

이 부분은 기존 Gemini CLI 사용자에게 꽤 중요하다.
명령어, 설정 방식, 확장 구조가 완전히 동일하게 유지된다고 기대하면 안 된다. 특히 자동화 스크립트나 팀 내부 문서에 Gemini CLI 명령어를 넣어둔 경우에는 전환 테스트가 필요하다.

기존 Gemini CLI 사용자는 무엇을 해야 하나

Gemini CLI를 개인 계정으로 사용 중이라면 Antigravity CLI 설치와 로그인 흐름을 미리 확인하는 편이 좋다.

Antigravity CLI는 macOS, Linux, Windows 설치 방식을 제공한다. 터미널 사용자라면 기존 CLI를 대체할 수 있는지 먼저 간단한 프로젝트에서 확인해보는 것이 안전하다.

특히 아래에 해당하면 바로 점검하는 게 좋다.

Gemini CLI를 매일 터미널에서 사용한다
프로젝트 생성, 코드 수정, 리팩터링에 Gemini CLI를 활용한다
VS Code에서 Gemini Code Assist 확장을 사용한다
사내 문서나 개인 자동화 스크립트에 Gemini CLI 명령어가 들어 있다
MCP, Hooks, 확장 기능을 연결해서 쓰고 있다

Antigravity CLI를 설치한 뒤에는 공식 문서의 기본 실행 예시를 먼저 확인하는 것이 좋다.
새로 전환되는 도구인 만큼 명령어, 옵션, 인증 방식이 업데이트될 수 있기 때문이다.

블로그나 커뮤니티에 올라온 예시 명령어를 그대로 따라 하기보다는, 공식 문서의 설치 및 시작하기 문서를 기준으로 확인하는 편이 안전하다. CLI 도구는 설치 과정에서 터미널 명령을 실행하는 경우가 많고, AI 코딩 도구는 프로젝트 파일과 명령 실행 권한을 함께 다루기 때문이다.

단순 질문용으로만 썼다면 전환 부담은 크지 않을 수 있다.
하지만 파일 수정, 명령 실행, 자동화에 연결해뒀다면 이야기가 달라진다.

AI 코딩 도구는 단순 앱이 아니라 개발 환경의 일부가 되는 경우가 많다. 그래서 “설치만 바꾸면 끝”이라고 보기 어렵다. 설정 파일, 권한, 플러그인, 인증 방식, 기존 워크플로우까지 같이 확인해야 한다.

VS Code 확장 사용자는 어떻게 봐야 하나

이번 변화에서 헷갈리기 쉬운 부분이 IDE 확장이다.

Gemini CLI만 쓰던 사람은 “터미널 도구만 바뀌는구나”라고 이해하면 되지만, Google 발표에는 Gemini Code Assist IDE 확장도 포함되어 있다.

개인 사용자 또는 Google AI Pro, Google AI Ultra 사용자가 Gemini Code Assist IDE 확장을 사용 중이라면, 해당 확장의 요청 처리 중단 대상에 들어간다.
반면 기업용 Gemini Code Assist Standard, Enterprise 라이선스를 쓰는 조직은 기존 접근이 유지된다고 안내되어 있다.

즉, VS Code 확장을 쓰는 사람은 본인이 어떤 계정 유형으로 사용 중인지 확인해야 한다.

개인 계정으로 쓰고 있다면 Antigravity 쪽 전환을 준비하는 것이 맞다.
회사 계정으로 쓰고 있다면 조직 라이선스 정책을 먼저 확인해야 한다.

여기서 무작정 확장을 지우거나 설정을 바꾸기보다는, 현재 로그인 계정과 라이선스 유형을 먼저 확인하는 편이 안전하다.

Antigravity CLI로 넘어갈 때 주의할 점

Antigravity CLI는 Gemini CLI보다 더 강한 에이전트형 도구를 지향한다.
이 말은 편해진다는 뜻이기도 하지만, 동시에 권한 관리가 더 중요해진다는 뜻이기도 하다.

공식 저장소에서도 AI 코딩 에이전트 사용 시 자율 코드 실행, 데이터 유출, 프롬프트 인젝션, 공급망 위험 같은 보안 이슈를 주의하라고 안내한다.

실제로는 아래 정도는 확인하고 쓰는 게 좋다.

1. 설치 경로는 공식 문서에서 확인하기

AI 개발 도구는 공격자들이 사칭하기 좋은 대상이다.
특히 CLI 도구는 설치 과정에서 터미널 명령어를 실행하는 경우가 많기 때문에, 블로그나 커뮤니티에 있는 설치 명령어를 그대로 복사하기보다 공식 문서에서 확인하는 습관이 필요하다.

2. 프로젝트 루트에서 바로 실행하기 전에 테스트하기

처음부터 실제 서비스 코드에서 실행하지 말고, 테스트용 저장소나 복사본에서 먼저 동작을 확인하는 편이 낫다.

AI 에이전트는 파일을 읽고, 수정하고, 명령을 실행할 수 있다.
도구가 똑똑해질수록 실수했을 때의 영향도 커진다.

3. Git 상태를 깨끗하게 만든 뒤 사용하기

AI 코딩 도구를 실행하기 전에는 최소한 현재 변경사항을 커밋하거나 별도 브랜치를 만드는 것이 좋다.

예를 들면 이런 흐름이 안전하다.

git status
git checkout -b test/antigravity-cli

작업 후에는 변경된 파일을 직접 확인해야 한다.

git diff

AI가 만든 코드가 그럴듯해 보여도, 실제 요구사항과 보안 기준을 만족하는지는 사람이 확인해야 한다.

4. 플러그인과 권한 설정 확인하기

Antigravity CLI에서는 기존 Extensions 흐름이 Antigravity plugins 쪽으로 이어진다.
플러그인은 편리하지만, 외부 도구 연결이나 명령 실행과 관련될 수 있다.

처음에는 필요한 기능만 최소한으로 연결하는 편이 좋다.
특히 MCP 서버, 훅, 서브에이전트 같은 기능을 연결할 때는 어떤 파일에 접근하는지, 어떤 명령을 실행할 수 있는지 확인해야 한다.

왜 Google은 굳이 Antigravity로 통합하려 할까

개발자 입장에서는 불편하게 느껴질 수 있다.
Gemini CLI가 나온 지 오래되지 않았고, 이미 익숙해진 사용자도 많기 때문이다.

하지만 Google 입장에서는 Gemini CLI, Gemini Code Assist, Antigravity 2.0, GitHub 연동, 기업용 AI 개발 도구를 따로 발전시키는 것보다 하나의 에이전트 기반 플랫폼으로 묶는 편이 유리하다.

AI 코딩 도구 시장은 단순 자동완성 경쟁에서 벗어나고 있다.

이제 경쟁 포인트는 “코드를 얼마나 잘 추천하느냐”만이 아니다.

여러 파일을 이해하는가
긴 작업을 나눠서 처리할 수 있는가
터미널과 IDE, 데스크톱 앱이 같은 맥락을 공유하는가
팀 단위 권한과 보안을 관리할 수 있는가
에이전트가 작업한 내역을 추적할 수 있는가

이런 요소가 중요해지고 있다.

Gemini CLI는 터미널 도구로는 매력적이었지만, Google이 그리는 방향은 더 넓은 개발 플랫폼이다.
그래서 Antigravity CLI는 Gemini CLI의 후속 도구이면서, 동시에 Antigravity 생태계로 사용자를 옮기는 입구 역할을 한다.

Gemini CLI 사용자는 바로 갈아타야 할까

개인 사용자라면 미리 갈아타는 쪽이 현실적이다.
기존 Gemini CLI가 계속 같은 방식으로 유지될 가능성은 낮아 보인다.

다만 당장 모든 작업을 Antigravity CLI에 맡길 필요는 없다.

처음에는 아래 순서로 확인하는 것이 좋다.

Antigravity CLI 설치
로그인 및 기본 명령 확인
작은 테스트 프로젝트에서 파일 수정 테스트
기존 Gemini CLI에서 자주 쓰던 명령과 비교
플러그인, Hooks, MCP 연결 여부 확인
실제 프로젝트에는 별도 브랜치에서 적용

특히 기존에 Gemini CLI를 자동화 스크립트처럼 쓰고 있었다면, 명령어 호환성을 직접 확인해야 한다.
Google이 핵심 기능을 유지한다고 했더라도, 1:1 호환을 보장하는 것은 아니기 때문이다.

정리: 이름 변경보다 플랫폼 전환에 가깝다

Gemini CLI에서 Antigravity CLI로의 변화는 단순 리브랜딩으로 보기 어렵다.

핵심은 Google의 AI 코딩 도구 전략이 터미널 단일 도구에서 에이전트 플랫폼 중심으로 이동하고 있다는 점이다.

개인 사용자라면 Gemini CLI와 Gemini Code Assist IDE 확장 사용 흐름을 Antigravity CLI 기준으로 다시 확인해야 한다.
기업 사용자는 조직 라이선스에 따라 영향 범위가 다르므로, 개인 계정 기준 안내만 보고 판단하면 안 된다.

기존 Gemini CLI를 가볍게 질문용으로만 썼다면 전환 부담은 크지 않을 수 있다.
하지만 코드 수정, 명령 실행, 확장 기능, MCP, 자동화까지 연결해두었다면 미리 테스트해야 한다.

Antigravity CLI는 더 강한 에이전트형 개발 도구를 지향한다.
그만큼 편해질 수 있지만, 권한과 보안, 변경사항 검토는 더 중요해진다.

지금 Gemini CLI를 쓰고 있다면 “언제까지 쓸 수 있나”보다 “내 개발 흐름에서 어떤 부분을 Antigravity CLI로 옮겨야 하나”를 먼저 확인하는 편이 낫다.

바이브 코딩 실전 체크리스트: 만들기 전에 정해야 할 것들

notebase — Mon, 1 Jun 2026 09:00:42 +0900

바이브 코딩을 시작하기 전에 정해야 할 기능, 화면, 데이터, 로그인, 보안, 테스트, 배포 기준을 실전 체크리스트로 정리했습니다. AI 코딩 도구로 프로젝트를 만들기 전 참고하기 좋습니다.

바이브 코딩은 AI에게 “이런 앱 만들어줘”라고 말하는 것만으로 끝나지 않는다. 실제로는 만들기 전에 무엇을 정했는지가 결과물의 품질을 거의 결정한다.

AI 코딩 도구가 좋아지면서 작은 웹앱이나 자동화 도구는 예전보다 훨씬 빠르게 만들 수 있다. Cursor, Claude Code, Codex, Gemini CLI, GitHub Copilot 같은 도구를 쓰면 코드 작성과 수정 속도는 확실히 빨라진다.

문제는 속도다.

너무 빨리 만들어지기 때문에, 처음에 기준을 정하지 않으면 나중에 어디서 꼬였는지 찾기 어려워진다. 기능은 늘어나고, 파일은 많아지고, AI는 이전 의도를 잊은 것처럼 다른 방향으로 코드를 바꾼다.

그래서 바이브 코딩을 할 때는 “코드를 어떻게 짤까?”보다 먼저 “무엇을 만들고, 어디까지 만들고, 어떤 기준으로 확인할까?”를 정해야 한다.

이 글은 바이브 코딩으로 프로젝트를 시작하기 전에 정리해두면 좋은 실전 체크리스트다.

바이브 코딩은 코딩보다 결정이 먼저다

바이브 코딩을 처음 하면 보통 이렇게 시작한다.

할 일 관리 앱 만들어줘.

AI는 바로 코드를 만들어준다. 화면도 생기고, 버튼도 생기고, 어느 정도 동작도 한다.

그런데 조금만 더 진행하면 질문이 생긴다.

할 일을 어디에 저장하지?
로그인은 필요한가?
삭제한 데이터는 복구할 수 있어야 하나?
모바일에서도 써야 하나?
혼자 쓰는 앱인가, 여러 명이 쓰는 앱인가?
API 키는 어디에 보관해야 하지?

이런 질문에 답하지 않은 상태에서 코드를 계속 만들면 프로젝트가 쉽게 흔들린다.

AI는 사용자의 의도를 추측해서 구현한다. 사용자가 정하지 않은 부분은 AI가 알아서 채운다. 이게 편할 때도 있지만, 실전에서는 오히려 문제가 된다.

내가 원한 구조가 아닌데 그럴듯하게 만들어지기 때문이다.

여기서 중요한 점은 바이브 코딩이 “기획 없이 개발하는 방식”은 아니라는 것이다. 오히려 기획이 짧고 선명해야 AI가 제대로 움직인다.

1단계: 방향 정하기

AI에게 코드를 맡기기 전에, 사람이 먼저 프로젝트의 기준선을 정하는 단계다.

처음부터 세부 기능을 전부 정할 필요는 없다. 하지만 “무엇을 만들고, 누가 쓰고, 어떤 상황에서 쓰는지”는 정해두는 편이 좋다.

이 기준이 없으면 AI가 알아서 방향을 잡는다. 문제는 그 방향이 내가 원한 방향과 다를 수 있다는 점이다.

1. 무엇을 만들지 한 문장으로 정하기

가장 먼저 정할 것은 프로젝트 설명이다.

긴 기획서가 아니어도 된다. 대신 한 문장으로 말할 수 있어야 한다.

좋지 않은 예시는 이런 식이다.

블로그 운영에 도움 되는 도구를 만들고 싶다.

너무 넓다. AI가 무엇을 만들어야 할지 추측해야 한다.

조금 더 좋은 예시는 이렇다.

티스토리 블로그 글 제목과 메타 설명을 입력하면 SEO 점검표를 만들어주는 웹앱을 만든다.

이 정도면 방향이 훨씬 선명해진다.

한 문장 안에는 가능하면 세 가지가 들어가면 좋다.

누가 쓰는지
무엇을 입력하는지
어떤 결과를 얻는지

예를 들면 다음과 같다.

개발 입문자가 에러 메시지를 붙여넣으면 원인과 확인할 명령어를 알려주는 웹앱을 만든다.

또는 이렇게 정리할 수도 있다.

개인 사용자가 구독 서비스 이름과 결제일을 입력하면 이번 달 결제 예정 목록을 보여주는 앱을 만든다.

이 한 문장이 프로젝트의 기준점이 된다.

AI가 다른 방향으로 코드를 만들기 시작하면 다시 이 문장으로 돌아오면 된다.

2. 사용자와 사용 상황 정하기

다음은 누가, 언제, 왜 쓰는지 정해야 한다.

많은 사람이 이 단계를 건너뛴다. 하지만 이 부분을 정하지 않으면 기능이 계속 늘어난다.

예를 들어 “메모 앱”을 만든다고 해보자.

혼자 쓰는 메모 앱인지, 팀이 같이 쓰는 메모 앱인지에 따라 구조가 달라진다. 혼자 쓰는 앱이면 로그인 없이 로컬 저장만으로도 충분할 수 있다. 팀이 쓰는 앱이면 계정, 권한, 공유 기능이 필요하다.

같은 메모 앱이어도 사용 상황에 따라 완전히 다른 프로젝트가 된다.

정리할 때는 거창하게 쓰지 않아도 된다.

사용자: 개발 공부를 시작한 초보자
상황: 에러 메시지를 봤지만 어디서부터 확인해야 할지 모를 때
목적: 에러 원인 후보와 확인 순서를 빠르게 알고 싶다

또는 이런 식으로 정리할 수 있다.

사용자: 티스토리 블로그 운영자
상황: 글을 발행하기 전에 제목, 설명, 태그를 점검하고 싶을 때
목적: 검색 의도와 글 구조가 맞는지 확인하고 싶다

이 정도만 정해도 AI에게 훨씬 정확하게 지시할 수 있다.

2단계: 구조 설계하기

이 단계에서는 기능, 화면, 데이터, 권한 범위를 정한다.

바이브 코딩에서 프로젝트가 꼬이는 이유는 대부분 이 구간에서 나온다. 기능을 계속 추가하다가 화면 구조가 복잡해지고, 데이터 구조가 바뀌고, 로그인이나 권한 같은 무거운 기능이 뒤늦게 붙으면서 코드가 흔들린다.

처음 목표는 “작지만 끝까지 동작하는 버전”을 만드는 것이다.

3. 핵심 기능과 나중 기능 나누기

바이브 코딩에서 가장 흔한 실수는 처음부터 기능을 많이 넣는 것이다.

AI는 요청하면 대부분 만들어준다. 그래서 채팅창에 계속 기능을 추가하게 된다.

로그인도 넣어줘.
다크모드도 넣어줘.
관리자 페이지도 넣어줘.
엑셀 다운로드도 넣어줘.
알림 기능도 넣어줘.

문제는 기능이 늘어나는 속도보다 구조가 망가지는 속도가 더 빠를 수 있다는 점이다.

처음에는 핵심 기능만 정해야 한다.

예를 들어 “구독 결제 관리 앱”이라면 핵심 기능은 이 정도면 충분하다.

구독 서비스 추가
결제일 입력
월 결제 금액 입력
이번 달 결제 예정 목록 보기

반대로 아래 기능은 나중으로 미뤄도 된다.

로그인
통계 차트
이메일 알림
카드사 문자 자동 분석
가족 공유
다크모드

처음부터 모든 기능을 넣으려고 하면 AI가 만든 코드도 복잡해진다. 초보자 입장에서는 나중에 수정하기 더 어려워진다.

처음 버전은 작아도 된다. 대신 실제로 끝까지 동작해야 한다.

4. 화면 흐름 먼저 그리기

코드를 만들기 전에 화면 흐름을 정해야 한다.

디자인을 예쁘게 만들라는 뜻이 아니다. 사용자가 어떤 순서로 움직이는지만 정하면 된다.

예를 들어 간단한 SEO 점검 도구라면 화면 흐름은 이렇게 잡을 수 있다.

1. 제목 입력
2. 메타 설명 입력
3. 본문 일부 입력
4. 점검하기 버튼 클릭
5. SEO 체크 결과 표시

이 흐름이 없으면 AI는 화면을 마음대로 구성한다. 어떤 경우에는 입력창이 너무 많아지고, 어떤 경우에는 결과 화면이 불필요하게 복잡해진다.

처음에는 종이에 써도 되고, 메모장에 적어도 된다.

중요한 것은 화면 단위를 먼저 나누는 것이다.

홈 화면
입력 화면
결과 화면
설정 화면

이렇게 화면을 나누면 AI에게 작업을 시킬 때도 편하다.

먼저 입력 화면만 만들어줘.
아직 API 연결은 하지 말고, 임시 데이터로 결과 화면까지 확인할 수 있게 해줘.

이런 식으로 작은 단위로 요청할 수 있다.

5. 데이터 구조 정하기

바이브 코딩에서 데이터 구조를 대충 넘기면 나중에 수정 비용이 커진다.

예를 들어 할 일 관리 앱을 만든다고 하면 “할 일”에 어떤 정보가 들어갈지 먼저 정해야 한다.

할 일
- id
- 제목
- 완료 여부
- 생성일
- 마감일

처음에는 이 정도면 충분하다.

여기에 우선순위, 태그, 반복 일정, 첨부파일까지 한 번에 넣으면 구조가 복잡해진다.

블로그 SEO 점검 도구라면 데이터 구조는 이렇게 잡을 수 있다.

SEO 점검 요청
- 제목
- 메타 설명
- 본문
- 핵심 키워드
- 작성일

SEO 점검 결과
- 제목 길이 평가
- 메타 설명 평가
- 키워드 포함 여부
- 개선 제안 목록

이렇게 데이터 구조를 먼저 정하면 AI가 코드를 만들 때 흔들림이 줄어든다.

특히 데이터베이스를 쓰는 프로젝트라면 이 단계가 더 중요하다.

처음에는 SQLite, Supabase, Firebase, PostgreSQL 같은 선택지도 고민하게 된다. 하지만 초보 단계에서는 저장 방식보다 데이터 항목을 먼저 정하는 것이 더 중요하다.

저장소는 나중에 바꿀 수 있지만, 데이터 구조가 계속 바뀌면 전체 코드가 흔들린다.

6. 로그인과 권한 범위 정하기

로그인은 생각보다 무거운 기능이다.

“그냥 로그인 붙여줘”라고 하면 AI가 코드를 만들어줄 수는 있다. 하지만 실제 서비스 관점에서는 계정 생성, 비밀번호 저장, 세션, 토큰, 로그아웃, 권한 확인, 개인정보 처리까지 이어진다.

혼자 쓰는 도구라면 처음부터 로그인이 필요 없을 수 있다.

예를 들어 로컬에서만 쓰는 블로그 제목 점검 도구라면 로그인 없이 시작해도 된다. 반대로 여러 사용자가 각자의 데이터를 저장해야 하는 앱이라면 로그인이 필요하다.

시작 전에 아래 질문에 답해보면 좋다.

이 앱은 나 혼자 쓰는가?
다른 사용자도 쓰는가?
사용자별로 데이터를 분리해야 하는가?
관리자 권한이 필요한가?
민감한 정보를 저장하는가?
API 키나 토큰이 필요한가?

여기서 “민감한 정보”가 들어가면 더 조심해야 한다.

비밀번호, API 키, 결제 정보, 개인 연락처, 업무 문서 같은 데이터는 AI가 만든 코드를 그대로 믿고 저장하면 위험하다.

API 키나 비밀번호가 필요한 프로젝트라면 처음부터 AI에게 이렇게 요구하는 편이 좋다.

API 키, 비밀번호, 토큰 같은 민감한 값은 코드에 직접 쓰지 말고 .env 환경 변수로 분리해줘.
.env 파일은 Git에 올라가지 않도록 .gitignore에 추가해줘.

처음 바이브 코딩 실습이라면 민감한 정보를 다루지 않는 프로젝트로 시작하는 편이 좋다.

3단계: 실행과 검증 준비하기

이 단계에서는 AI에게 어떤 순서로 일을 맡길지, 무엇을 성공 기준으로 볼지 정한다.

바이브 코딩은 빠르게 만들 수 있다는 장점이 있다. 하지만 빠르게 만든 만큼 검증 기준이 없으면 “일단 돌아가는 것처럼 보이는 코드”에서 멈추기 쉽다.

AI에게 한 번에 많이 시키기보다, 작게 나누고 확인하면서 진행하는 편이 안전하다.

7. AI에게 줄 작업 단위 쪼개기

AI 코딩 도구를 쓸 때는 요청을 작게 나눠야 한다.

한 번에 이렇게 요청하면 결과가 흔들리기 쉽다.

구독 관리 앱 전체를 만들어줘. 로그인, DB, 통계, 알림, 배포까지 다 해줘.

겉보기에는 빠르지만, 실제로는 검토하기 어렵다.

더 좋은 방식은 작업을 단계별로 나누는 것이다.

1단계: React로 기본 화면만 만들어줘. 데이터는 임시 배열을 사용해.
2단계: 구독 항목 추가와 삭제 기능을 붙여줘.
3단계: localStorage에 저장되게 해줘.
4단계: 월 결제 합계를 계산해줘.
5단계: 코드 구조를 컴포넌트 단위로 정리해줘.

이렇게 나누면 각 단계에서 확인할 수 있다.

AI에게 줄 지시문에는 “하지 말아야 할 것”도 넣는 것이 좋다.

아직 로그인은 만들지 마.
아직 서버 API는 연결하지 마.
디자인보다 기능 동작을 먼저 확인할 수 있게 해줘.
기존 파일 구조는 유지해줘.
수정한 파일 목록을 마지막에 정리해줘.

바이브 코딩은 AI에게 많이 맡기는 방식이지만, 방향은 사람이 잡아야 한다.

8. 테스트 기준 정하기

AI가 만든 코드는 그럴듯하게 보일 때가 많다.

하지만 그럴듯한 코드와 제대로 동작하는 코드는 다르다. 그래서 만들기 전에 테스트 기준을 정해야 한다.

테스트라고 해서 처음부터 복잡한 자동화 테스트를 말하는 것은 아니다. 최소한 사용자가 직접 확인할 시나리오는 있어야 한다.

예를 들어 구독 관리 앱이라면 이렇게 정할 수 있다.

구독 서비스를 추가하면 목록에 표시된다.
금액을 입력하면 월 합계에 반영된다.
삭제 버튼을 누르면 목록에서 사라진다.
새로고침해도 데이터가 유지된다.
빈 값을 입력하면 저장되지 않는다.

이 정도만 있어도 AI가 만든 결과물을 확인하기 쉬워진다.

에러 상황도 미리 정해야 한다.

금액에 문자를 입력하면 어떻게 할 것인가?
결제일을 비워두면 어떻게 할 것인가?
같은 이름의 구독 서비스를 두 번 추가할 수 있는가?

이 질문을 하지 않으면 AI가 임의로 처리한다.

실제로는 이런 작은 예외 처리가 앱의 완성도를 좌우한다.

9. 배포와 유지보수 기준 정하기

처음부터 배포까지 생각할 필요가 없다고 느낄 수 있다.

하지만 어디에서 실행할지는 미리 정하는 것이 좋다.

예를 들어 개인용 웹앱이라면 다음 선택지가 있다.

내 컴퓨터에서만 실행
GitHub Pages에 정적 페이지로 배포
Vercel이나 Netlify에 배포
서버와 데이터베이스까지 연결해 배포

각 선택지에 따라 구현 방식이 달라진다.

정적 페이지로 배포할 앱이라면 서버 기능을 넣으면 안 된다. 반대로 사용자별 데이터 저장이 필요하다면 백엔드나 외부 데이터베이스가 필요할 수 있다.

유지보수 기준도 정해야 한다.

내가 직접 코드를 읽고 수정할 수 있어야 하는가?
AI에게 계속 맡길 것인가?
파일 구조를 단순하게 유지할 것인가?
기능 추가보다 안정성을 우선할 것인가?

바이브 코딩으로 만든 프로젝트는 초반 속도가 빠르다. 하지만 구조가 복잡해진 뒤에는 사람이 이해하기 어려워질 수 있다.

그래서 작은 프로젝트일수록 파일 구조와 기능 범위를 단순하게 유지하는 것이 좋다.

바이브 코딩 시작 전 체크리스트

아래 항목을 채운 뒤 AI 코딩 도구를 시작하면 결과물이 훨씬 안정적이다.

구분	정해야 할 것	예시
프로젝트 정의	무엇을 만들 것인가	블로그 제목 SEO 점검 도구
사용자	누가 쓰는가	티스토리 블로그 운영자
사용 상황	언제 쓰는가	글 발행 전 제목과 설명을 점검할 때
핵심 기능	반드시 필요한 기능	제목 입력, 메타 설명 입력, 점검 결과 표시
제외 기능	지금 만들지 않을 기능	로그인, 통계, 자동 발행
화면 흐름	어떤 순서로 쓰는가	입력 → 점검 → 결과
데이터 구조	어떤 정보를 저장하는가	제목, 설명, 본문, 키워드
저장 방식	어디에 저장하는가	처음에는 localStorage
권한	로그인이나 관리자 기능이 필요한가	개인용이면 로그인 제외
보안 기준	민감한 값을 어떻게 관리할 것인가	API 키는 .env로 분리
테스트 기준	무엇이 되면 성공인가	입력값에 따라 결과가 표시됨
배포 방식	어디에서 실행할 것인가	로컬 실행 또는 Vercel 배포

이 표를 그대로 복사해서 프로젝트마다 채워도 된다.

핵심은 거창한 문서를 만드는 것이 아니다. AI가 마음대로 추측하지 않도록 최소한의 기준을 정해두는 것이다.

AI에게 처음 줄 프롬프트 예시

아래는 바이브 코딩을 시작할 때 사용할 수 있는 첫 프롬프트 예시다.

특히 API 키나 토큰이 필요한 프로젝트라면, 보안 조건을 프롬프트에 처음부터 넣어두는 것이 좋다. 나중에 고치려고 하면 이미 코드 곳곳에 민감한 값이 섞여 있을 수 있다.

나는 티스토리 블로그 운영자를 위한 간단한 SEO 점검 웹앱을 만들고 싶다.

목표:
- 글 제목, 메타 설명, 핵심 키워드를 입력하면 기본 점검 결과를 보여준다.
- 처음 버전에서는 로그인, 서버, 데이터베이스는 만들지 않는다.
- 데이터는 브라우저 localStorage에만 저장한다.

사용자:
- 티스토리 블로그 글을 직접 작성하는 개인 운영자

핵심 기능:
1. 제목 입력
2. 메타 설명 입력
3. 핵심 키워드 입력
4. 점검하기 버튼
5. 제목 길이, 메타 설명 길이, 키워드 포함 여부를 결과로 표시
6. 최근 점검 기록 5개 저장

제외할 기능:
- 로그인
- 서버 API
- 자동 글 생성
- 티스토리 자동 업로드
- 결제 기능

보안 조건:
- API 키, 비밀번호, 토큰 같은 민감한 값은 코드에 직접 넣지 않는다.
- 민감한 값이 필요해지는 경우 .env 환경 변수로 분리한다.
- .env 파일은 Git에 올라가지 않도록 .gitignore에 추가한다.

요청:
- 먼저 React 기준으로 화면과 기본 동작을 만들어줘.
- 디자인은 단순해도 된다.
- 한 파일에 너무 많은 코드가 몰리지 않게 컴포넌트를 나눠줘.
- 수정한 파일 목록과 실행 방법을 마지막에 정리해줘.

이렇게 요청하면 AI가 추측해야 할 부분이 줄어든다.

처음부터 “멋진 서비스처럼 만들어줘”라고 하는 것보다 훨씬 낫다.

주의할 점: AI가 만든 코드를 그대로 믿지 않기

바이브 코딩은 빠르지만, 검토가 필요 없는 방식은 아니다.

AI는 존재하지 않는 패키지를 추천할 수 있고, 오래된 문법을 섞을 수 있다. 보안상 위험한 코드를 자연스럽게 넣을 때도 있다. 에러가 나면 원인을 정확히 고치기보다 우회하는 코드를 만들기도 한다.

특히 아래 항목은 반드시 확인해야 한다.

설치하라는 패키지가 실제로 존재하는지
비밀번호나 API 키가 코드에 직접 들어가지 않았는지
.env 파일이 Git에 올라가도록 되어 있지 않은지
파일 삭제, DB 초기화 같은 위험한 명령이 포함되지 않았는지
로그인이나 인증 코드가 너무 단순하게 처리되지 않았는지
에러를 숨기기만 하고 실제 원인을 해결하지 않은 것은 아닌지

개발 초보자라면 더더욱 작은 단위로 실행하고 확인해야 한다.

AI가 “완성했습니다”라고 말해도 실제로 완성된 것은 아니다. 실행해보고, 눌러보고, 이상한 값을 넣어봐야 한다.

작은 프로젝트부터 시작하는 게 좋다

바이브 코딩을 실전에서 익히려면 처음부터 큰 서비스를 만들기보다 작고 명확한 도구가 좋다.

예를 들면 이런 주제가 적당하다.

블로그 제목 점검 도구
구독 결제일 관리 앱
간단한 할 일 관리 앱
CSV 파일 정리 도구
에러 메시지 기록 노트
독서 기록 관리 앱
운동 기록 체크 앱

공통점은 기능이 작고, 데이터 구조가 단순하고, 민감한 정보를 많이 다루지 않는다는 점이다.

처음부터 결제, 로그인, 관리자 페이지, 실시간 채팅, 복잡한 권한 기능이 들어가는 프로젝트는 피하는 편이 좋다.

AI가 코드를 만들어줄 수는 있지만, 문제가 생겼을 때 사용자가 이해하기 어렵다.

마무리

바이브 코딩은 아이디어를 빠르게 결과물로 바꾸는 데 유용하다. 하지만 만들기 전에 아무것도 정하지 않으면 AI가 프로젝트의 방향까지 대신 정해버린다.

실제로 중요한 것은 프롬프트를 화려하게 쓰는 것이 아니다.

무엇을 만들지, 누구를 위한 것인지, 어디까지 만들지, 어떤 기준으로 확인할지를 먼저 정하는 것이다.

처음에는 작은 기능 하나만 제대로 동작하게 만드는 것이 좋다. 그다음 기능을 추가해도 늦지 않다.

바이브 코딩을 실전에서 쓰고 싶다면, 코드를 요청하기 전에 체크리스트부터 채워보는 편이 낫다. 그 10분이 나중에 몇 시간짜리 수정 작업을 줄여준다.

FastAPI CORS 설정 방법: 프론트엔드 연동할 때 막히는 이유

notebase — Fri, 29 May 2026 16:17:43 +0900

React, Vue, Next.js 같은 프론트엔드에서 FastAPI API 호출이 CORS 오류로 막히는 이유와 CORSMiddleware 설정 방법을 초보자 기준으로 정리합니다.

FastAPI CORS 설정은 프론트엔드에서 백엔드 API를 호출할 때 자주 막히는 지점이다. React, Vue, Next.js 개발 서버와 FastAPI 서버를 따로 실행하면 브라우저 콘솔에 CORS 오류가 뜨는 경우가 많다.

처음 보면 FastAPI 코드가 잘못된 것처럼 보인다.

하지만 실제로는 API 로직 문제가 아니라 브라우저 보안 정책 때문에 요청이 차단되는 상황인 경우가 많다.

CORS가 뭔가요?

CORS는 Cross-Origin Resource Sharing의 줄임말이다.

한국어로 풀면 “교차 출처 리소스 공유” 정도로 번역할 수 있다. 말은 어렵지만, 핵심은 단순하다.

다른 출처에서 온 요청을 서버가 허용할지 정하는 방식

예를 들어 프론트엔드는 아래 주소에서 실행 중이라고 해보자.

http://localhost:5173

FastAPI 서버는 아래 주소에서 실행 중이다.

http://localhost:8000

둘 다 내 컴퓨터에서 실행 중이지만 브라우저는 이 둘을 같은 곳으로 보지 않는다. 포트 번호가 다르기 때문이다.

이 상태에서 프론트엔드가 FastAPI 서버로 요청을 보내면 브라우저는 먼저 확인한다.

http://localhost:5173에서 온 요청이 http://localhost:8000 서버에 접근해도 되나요?

FastAPI 서버가 “허용한다”고 알려주면 응답을 프론트엔드 코드에서 사용할 수 있다.

반대로 서버가 허용 정보를 주지 않으면 브라우저가 응답을 막고 CORS 오류를 보여준다.

여기서 중요한 점은 CORS가 서버가 죽어서 나는 오류가 아니라는 것이다. 서버는 정상 응답을 했는데, 브라우저가 그 응답을 프론트엔드 코드에 넘기지 않는 경우도 있다.

그래서 CORS 설정은 단순히 오류를 없애는 코드가 아니다.

어떤 프론트엔드 주소가 내 FastAPI 서버에 접근할 수 있는지 정하는 설정이다.

CORS 오류는 왜 발생할까?

웹에서는 다음 세 가지가 모두 같아야 같은 출처, 즉 같은 Origin으로 본다.

프로토콜: http 또는 https
도메인: localhost, example.com 등
포트: 5173, 8000 등

아래 두 주소를 비교해보자.

http://localhost:5173
http://localhost:8000

프로토콜은 http로 같다.

도메인도 localhost로 같다.

하지만 포트가 다르다.

프론트엔드: http://localhost:5173
백엔드:     http://localhost:8000

그래서 브라우저는 이 둘을 서로 다른 Origin으로 본다.

프론트엔드 개발 서버와 백엔드 API 서버를 분리해서 실행하면 CORS 오류를 자주 만나는 이유가 여기에 있다.

FastAPI에서 CORS 설정하는 기본 방법

FastAPI에서는 CORSMiddleware를 추가해서 CORS를 설정한다.

FastAPI 공식 문서에서도 CORS 설정은 CORSMiddleware를 임포트하고, 허용할 Origin 목록을 만든 뒤, FastAPI 애플리케이션에 미들웨어로 추가하는 방식으로 안내한다.

기본 코드는 아래와 같다.

# main.py

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

origins = [
    "http://localhost:5173",
    "http://127.0.0.1:5173",
]

app.add_middleware(
    CORSMiddleware,
    allow_origins=origins,
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
    allow_headers=["Authorization", "Content-Type"],
)


@app.get("/")
def read_root():
    return {"message": "Hello FastAPI"}

이 설정에서 가장 중요한 부분은 allow_origins다.

origins = [
    "http://localhost:5173",
    "http://127.0.0.1:5173",
]

여기에 프론트엔드가 실행되는 주소를 넣어야 한다.

Vite 기반 React 프로젝트라면 보통 아래 주소를 많이 쓴다.

http://localhost:5173

Create React App이나 Next.js 개발 서버는 기본적으로 아래 주소를 많이 쓴다.

http://localhost:3000

다만 프로젝트 설정에 따라 포트는 달라질 수 있다. 브라우저 주소창에 실제로 표시되는 프론트엔드 주소를 확인한 뒤 넣는 게 가장 정확하다.

각 옵션은 무슨 의미일까?

CORS 설정 코드를 처음 보면 옵션이 많아서 헷갈릴 수 있다.

app.add_middleware(
    CORSMiddleware,
    allow_origins=origins,
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
    allow_headers=["Authorization", "Content-Type"],
)

각 옵션의 의미는 아래와 같다.

옵션	의미
`allow_origins`	요청을 허용할 프론트엔드 주소
`allow_credentials`	쿠키, 인증 헤더 등 인증 정보를 포함할 수 있는지
`allow_methods`	허용할 HTTP 메서드
`allow_headers`	허용할 요청 헤더

개발 중에는 아래처럼 넓게 허용하는 예시도 자주 보인다.

allow_methods=["*"]
allow_headers=["*"]

다만 allow_credentials=True를 함께 사용할 때는 주의해야 한다.

FastAPI 공식 문서 기준으로 allow_credentials=True인 경우 allow_origins, allow_methods, allow_headers는 ["*"]로 설정할 수 없다. 모두 명시적으로 지정해야 한다.

그래서 쿠키나 인증 정보를 포함하는 요청을 다룬다면 아래처럼 실제 값을 적어주는 편이 좋다.

app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "http://localhost:5173",
        "https://example.com",
    ],
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
    allow_headers=["Authorization", "Content-Type"],
)

입문 단계에서는 이 부분을 놓치기 쉽다. 단순 조회 API만 테스트할 때는 문제가 없어 보이다가, 로그인이나 인증 요청을 붙이는 순간 CORS 오류가 다시 나타날 수 있다.

프론트엔드 요청 예시

프론트엔드에서는 보통 fetch나 axios로 FastAPI API를 호출한다.

fetch("http://localhost:8000/")
  .then((response) => response.json())
  .then((data) => {
    console.log(data);
  });

FastAPI에 CORS 설정이 없거나, allow_origins에 현재 프론트엔드 주소가 빠져 있으면 브라우저 콘솔에 대략 이런 오류가 뜰 수 있다.

Access to fetch at 'http://localhost:8000/'
from origin 'http://localhost:5173'
has been blocked by CORS policy

이 메시지에서 봐야 할 부분은 두 가지다.

fetch at 'http://localhost:8000/'
origin 'http://localhost:5173'

즉, http://localhost:5173에서 http://localhost:8000으로 요청했는데 허용되지 않았다는 뜻이다.

이때 FastAPI 설정의 allow_origins에 http://localhost:5173을 추가해야 한다.

`localhost`와 `127.0.0.1`은 다르게 취급될 수 있다

입문자가 자주 놓치는 부분이 있다.

아래 두 주소는 비슷해 보인다.

http://localhost:5173
http://127.0.0.1:5173

하지만 Origin 기준에서는 문자열이 다르다.

프론트엔드를 http://127.0.0.1:5173으로 열어놓고, FastAPI CORS 설정에는 http://localhost:5173만 넣으면 CORS 오류가 날 수 있다.

그래서 개발 환경에서는 둘 다 넣어두는 편이 안전하다.

origins = [
    "http://localhost:5173",
    "http://127.0.0.1:5173",
]

실제로는 프론트엔드를 어떤 주소로 접속했는지 브라우저 주소창을 먼저 확인해야 한다.

임시로 모든 Origin을 허용해도 될까?

개발 중에는 아래처럼 모든 Origin을 허용하는 예시를 볼 수 있다.

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"],
)

이렇게 하면 여러 프론트엔드 주소에서 접근할 수 있어서 테스트가 편하다.

하지만 이 설정을 그대로 운영 환경에 가져가는 것은 조심해야 한다.

특히 로그인, 쿠키, 인증 토큰처럼 사용자 정보가 오가는 API라면 더 신중해야 한다.

그리고 allow_credentials=True를 사용한다면 아래처럼 와일드카드와 섞어서 쓰지 않는 편이 좋다.

# 피해야 할 예시
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

FastAPI 공식 문서에서도 credentials를 허용하는 경우에는 allow_origins, allow_methods, allow_headers를 모두 명시적으로 지정해야 한다고 안내한다.

운영 환경에서는 보통 실제 서비스 도메인만 허용한다.

origins = [
    "https://example.com",
    "https://www.example.com",
]

개발 환경과 운영 환경을 나눠서 설정하는 방식이 더 안전하다.

쿠키나 인증 정보를 보낼 때는 더 주의해야 한다

프론트엔드에서 쿠키 기반 로그인이나 인증 헤더를 사용한다면 allow_credentials=True가 필요할 수 있다.

예를 들어 axios에서 쿠키를 포함해 요청하려면 프론트엔드 코드에도 설정이 들어간다.

axios.get("http://localhost:8000/me", {
  withCredentials: true,
});

FastAPI 쪽에서는 아래처럼 설정한다.

app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "http://localhost:5173",
    ],
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
    allow_headers=["Authorization", "Content-Type"],
)

여기서 오해하기 쉬운 부분이 있다.

인증 정보가 오가는 요청이라면 어떤 프론트엔드 도메인에서 접근할 수 있는지 명확히 제한해야 한다.

운영 환경에서 allow_origins=["*"]처럼 모든 출처를 열어두는 방식은 피하는 편이 좋다. 특히 allow_credentials=True와 함께 쓸 때는 allow_methods, allow_headers까지 실제 필요한 값으로 명시하는 것이 공식 문서 기준에 맞다.

Preflight 요청 때문에 막히는 경우도 있다

CORS 오류를 보다 보면 실제 요청 전에 OPTIONS 요청이 먼저 나가는 경우가 있다.

이걸 Preflight 요청이라고 한다.

브라우저가 본 요청을 보내기 전에 서버에 먼저 확인하는 과정이다.

이 Origin에서 이런 메서드와 헤더로 요청해도 되나요?

예를 들어 Authorization 헤더를 붙이거나, Content-Type: application/json으로 POST 요청을 보내는 경우 Preflight 요청이 발생할 수 있다.

MDN 문서에서도 Preflight 요청은 실제 요청 전에 브라우저가 OPTIONS 메서드로 서버에 확인하는 요청이라고 설명한다.

FastAPI에서는 CORSMiddleware를 올바르게 추가하면 이런 Preflight 요청도 처리된다.

즉, 보통은 개발자가 OPTIONS 라우터를 직접 만들 필요가 없다.

CORS 설정했는데도 안 될 때 확인할 것

CORS 설정을 했는데도 계속 오류가 난다면 아래 순서로 확인해보면 좋다.

1. 프론트엔드 주소가 정확한가?

브라우저 주소창을 확인한다.

http://localhost:5173
http://127.0.0.1:5173
http://localhost:3000

이 주소가 allow_origins에 정확히 들어가 있어야 한다.

끝에 /를 붙여서 아래처럼 쓰면 의도와 다르게 동작할 수 있다.

# 권장하지 않음
"http://localhost:5173/"

보통은 아래처럼 쓴다.

"http://localhost:5173"

2. FastAPI 서버를 재시작했는가?

CORS 설정을 바꿨는데 서버가 이전 코드로 계속 실행 중일 수 있다.

개발 서버를 재시작하거나, --reload 옵션을 사용 중인지 확인한다.

fastapi dev main.py

또는 uvicorn을 직접 실행한다면 아래처럼 실행할 수 있다.

uvicorn main:app --reload

3. 요청 URL이 맞는가?

프론트엔드에서 요청하는 주소가 실제 FastAPI 서버 주소와 다를 수 있다.

fetch("http://localhost:8000/api/items")

FastAPI 서버가 8000번 포트에서 실행 중인지, API 경로가 /api/items가 맞는지 확인해야 한다.

CORS 오류처럼 보이지만 실제로는 경로 오류, 프록시 설정 오류, 서버 실행 오류가 섞여 있는 경우도 있다.

4. 프론트엔드 프록시 설정과 충돌하지 않는가?

Vite나 Next.js에서 프록시를 설정해두면 요청 흐름이 달라진다.

예를 들어 프론트엔드에서 아래처럼 요청한다고 해보자.

fetch("/api/items")

이 경우 브라우저가 바로 http://localhost:8000으로 요청하는 것이 아니라, 프론트엔드 개발 서버의 프록시 설정을 거칠 수 있다.

프록시를 사용할지, FastAPI에 직접 요청할지 먼저 정해야 한다.

둘을 섞어두면 오류 원인을 찾기 어렵다.

5. 커스텀 헤더를 보내고 있지 않은가?

프론트엔드에서 직접 만든 헤더를 보내는 경우도 있다.

fetch("http://localhost:8000/items", {
  headers: {
    "X-Client-Version": "1.0.0",
  },
});

이런 헤더를 사용한다면 FastAPI의 allow_headers에도 해당 헤더 이름을 추가해야 한다.

app.add_middleware(
    CORSMiddleware,
    allow_origins=origins,
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
    allow_headers=[
        "Authorization",
        "Content-Type",
        "X-Client-Version",
    ],
)

Authorization, Content-Type 외에 프로젝트에서 직접 사용하는 헤더가 있다면 이 목록에 빠지지 않았는지 확인해야 한다.

예를 들어 사내 프로젝트나 토이 프로젝트에서 X-API-Key, X-Client-Id 같은 헤더를 직접 붙여 쓰는 경우가 있다. 이때도 같은 방식으로 allow_headers에 추가하면 된다.

개발 환경과 운영 환경 설정을 나누는 예시

실제 프로젝트에서는 환경 변수로 허용 Origin을 관리하는 방식이 좋다.

간단한 예시는 아래와 같다.

# main.py

import os

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

ENV = os.getenv("ENV", "development")

if ENV == "production":
    origins = [
        "https://example.com",
        "https://www.example.com",
    ]
else:
    origins = [
        "http://localhost:5173",
        "http://127.0.0.1:5173",
        "http://localhost:3000",
        "http://127.0.0.1:3000",
    ]

app.add_middleware(
    CORSMiddleware,
    allow_origins=origins,
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
    allow_headers=["Authorization", "Content-Type"],
)


@app.get("/health")
def health_check():
    return {"status": "ok"}

이렇게 해두면 개발 중에는 로컬 프론트엔드 주소를 허용하고, 운영 환경에서는 실제 배포 도메인만 허용할 수 있다.

만약 프로젝트에서 커스텀 헤더를 사용한다면 이 예시의 allow_headers에도 해당 헤더를 추가하면 된다.

allow_headers=[
    "Authorization",
    "Content-Type",
    "X-Client-Version",
]

물론 실제 서비스에서는 환경 변수를 더 체계적으로 관리하는 편이 좋다. 예를 들어 .env 파일이나 배포 플랫폼의 환경 변수 설정을 사용할 수 있다.

FastAPI CORS 설정 전체 예시

입문자라면 일단 아래 코드로 시작해도 충분하다.

# main.py

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

origins = [
    "http://localhost:5173",
    "http://127.0.0.1:5173",
    "http://localhost:3000",
    "http://127.0.0.1:3000",
]

app.add_middleware(
    CORSMiddleware,
    allow_origins=origins,
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
    allow_headers=[
        "Authorization",
        "Content-Type",
        # 커스텀 헤더를 사용한다면 여기에 추가
        # "X-Client-Version",
    ],
)


@app.get("/")
def read_root():
    return {
        "message": "FastAPI CORS 설정 완료"
    }


@app.get("/items")
def read_items():
    return [
        {"id": 1, "name": "Apple"},
        {"id": 2, "name": "Banana"},
    ]

프론트엔드에서는 이렇게 호출할 수 있다.

fetch("http://localhost:8000/items")
  .then((response) => response.json())
  .then((data) => console.log(data));

브라우저 콘솔에 데이터가 정상 출력되면 기본 연동은 성공이다.

만약 인증이 없는 단순 API라면?

로그인, 쿠키, 인증 헤더가 전혀 없는 단순 테스트 API라면 개발 중에는 아래처럼 간단히 열어둘 수도 있다.

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"],
)

다만 이 설정은 “테스트 편의용”에 가깝다.

나중에 로그인 기능이나 인증 헤더를 붙일 예정이라면 처음부터 명시적인 Origin 방식으로 작성하는 편이 덜 헷갈린다.

CORS는 에러를 없애는 설정이 아니라 허용 범위를 정하는 설정이다

CORS를 단순히 “오류 해결용 코드”로만 보면 나중에 운영 환경에서 설정을 과하게 열어둘 수 있다.

실제로는 이 질문에 답하는 설정에 가깝다.

어떤 프론트엔드 주소가 이 API 서버에 접근할 수 있는가?

개발 중에는 localhost와 127.0.0.1을 넉넉히 허용해도 된다.

하지만 배포할 때는 실제 서비스 도메인만 남기는 편이 좋다.

FastAPI에서 프론트엔드 연동이 막힌다면 먼저 브라우저 콘솔의 CORS 메시지를 보고, 요청을 보낸 Origin과 allow_origins 값을 비교해보면 된다. 대부분의 로컬 개발 CORS 오류는 여기서 원인이 나온다.

특히 인증 요청이 포함된다면 allow_credentials=True와 와일드카드 설정을 함께 쓰고 있지 않은지도 같이 확인해야 한다.

그리고 직접 만든 헤더를 프론트엔드에서 보내고 있다면 allow_headers에 해당 헤더 이름이 포함되어 있는지도 확인하자.

FastAPI JWT 로그인 구현 기초: 토큰 인증 흐름 이해하기

notebase — Fri, 29 May 2026 08:29:55 +0900

FastAPI에서 JWT 로그인 인증이 어떻게 동작하는지 로그인 요청, 토큰 발급, Bearer 헤더 인증, 보호된 API 접근 흐름을 중심으로 정리합니다.

FastAPI JWT 로그인은 사용자가 로그인하면 서버가 토큰을 발급하고, 이후 요청에서 그 토큰을 확인해 사용자를 인증하는 방식이다. 핵심은 “로그인 상태를 서버가 계속 들고 있지 않는다”는 점이다.

일반적인 웹 로그인에서는 서버 세션을 떠올리기 쉽다.

사용자가 로그인하면 서버가 세션을 만들고, 브라우저는 쿠키를 들고 다닌다. 요청이 올 때마다 서버는 쿠키에 연결된 세션 정보를 확인한다.

JWT 방식은 조금 다르다.

서버는 로그인 성공 시 서명된 토큰을 만들어 클라이언트에 전달한다. 클라이언트는 이후 API 요청마다 이 토큰을 함께 보낸다. 서버는 토큰의 서명이 유효한지, 만료되지 않았는지 확인한 뒤 요청을 처리한다.

여기서 중요한 점은 JWT가 “암호화된 비밀 저장소”가 아니라는 것이다. JWT 안의 내용은 누구나 디코딩해서 볼 수 있다. 그래서 비밀번호, 주민등록번호, 결제 정보 같은 민감한 값은 넣으면 안 된다.

보통은 사용자를 식별할 수 있는 값 정도만 넣는다.

예를 들면 user_id, username, sub 같은 값이다.

FastAPI JWT 로그인 흐름을 먼저 이해하기

코드로 들어가기 전에 흐름부터 잡는 게 좋다.

JWT 로그인은 보통 이렇게 움직인다.

사용자가 아이디와 비밀번호를 보낸다.
서버가 사용자 정보를 확인한다.
비밀번호가 맞으면 Access Token을 만든다.
클라이언트는 토큰을 저장한다.
이후 요청마다 Authorization 헤더에 토큰을 담아 보낸다.
서버는 토큰을 검증하고 사용자를 식별한다.
토큰이 잘못됐거나 만료되면 401 Unauthorized를 반환한다.

요청 헤더는 보통 이런 형태가 된다.

Authorization: Bearer 발급받은_JWT_토큰

Bearer는 “이 토큰을 가진 사용자를 인증된 사용자로 봐 달라”는 의미에 가깝다.

FastAPI에서는 이 흐름을 처리할 때 OAuth2PasswordBearer를 자주 사용한다. 이름은 조금 길지만, 역할은 단순하다.

요청 헤더에서 Bearer 토큰을 꺼내오는 도구라고 보면 된다.

프로젝트 준비

먼저 필요한 패키지를 설치한다.

pip install fastapi uvicorn pyjwt passlib[bcrypt] python-multipart

각 패키지의 역할은 다음과 같다.

패키지	역할
`fastapi`	API 서버 구현
`uvicorn`	FastAPI 실행 서버
`pyjwt`	JWT 생성 및 검증
`passlib[bcrypt]`	비밀번호 해싱 및 검증
`python-multipart`	로그인 폼 데이터 처리

FastAPI 공식 문서의 JWT 예제에서는 다른 JWT 라이브러리를 사용하는 경우도 있다. 이 글에서는 pyjwt를 사용한다.

pyjwt는 JWT 생성과 검증에 집중한 라이브러리라 예제 코드 흐름이 단순하다. FastAPI에서 JWT 인증 구조를 익히는 목적이라면 jwt.encode(), jwt.decode()의 역할이 바로 보여서 이해하기 쉽다.

여기서 한 가지 주의할 점이 있다.

패키지는 pyjwt로 설치하지만, 코드에서 불러올 때는 import jwt로 작성한다. import pyjwt가 아니다.

import jwt

예외 클래스도 같은 방식으로 가져온다.

from jwt import PyJWTError

python-multipart는 OAuth2PasswordRequestForm을 사용할 때 필요하다. 설치하지 않으면 로그인 요청을 받을 때 오류가 날 수 있다.

사용자 데이터와 비밀번호 검증 구조

실제 서비스라면 사용자 정보는 데이터베이스에 저장한다.

여기서는 흐름 이해를 위해 메모리 딕셔너리를 사용한다.

from passlib.context import CryptContext

pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")

fake_users_db = {
    "kim": {
        "username": "kim",
        "hashed_password": pwd_context.hash("1234"),
        "disabled": False,
    },
    "lee": {
        "username": "lee",
        "hashed_password": pwd_context.hash("1234"),
        "disabled": True,
    },
}

비밀번호는 원문 그대로 저장하면 안 된다.

예를 들어 사용자의 비밀번호가 1234라고 해서 DB에 그대로 1234를 넣는 방식은 피해야 한다. DB가 유출되면 사용자의 비밀번호가 바로 노출되기 때문이다.

그래서 보통은 해시된 값을 저장한다.

검증할 때도 원문끼리 비교하지 않는다.

def verify_password(plain_password: str, hashed_password: str) -> bool:
    return pwd_context.verify(plain_password, hashed_password)

사용자 조회 함수도 따로 만든다.

def get_user(username: str):
    user = fake_users_db.get(username)
    if user:
        return user
    return None

그리고 로그인 시 사용할 인증 함수를 작성한다.

def authenticate_user(username: str, password: str):
    user = get_user(username)

    if not user:
        return None

    if not verify_password(password, user["hashed_password"]):
        return None

    return user

여기서는 사용자가 없거나 비밀번호가 틀리면 None을 반환한다.

실제 서비스에서는 “아이디가 없습니다”, “비밀번호가 틀렸습니다”를 너무 구체적으로 나누지 않는 경우도 있다. 공격자가 존재하는 계정을 추측하는 데 악용할 수 있기 때문이다.

JWT Access Token 만들기

JWT를 만들 때는 크게 네 가지가 필요하다.

토큰에 넣을 데이터
비밀 키
서명 알고리즘
만료 시간

예시 코드는 다음과 같다.

from datetime import datetime, timedelta, timezone
import jwt

SECRET_KEY = "change-this-secret-key"
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 30

def create_access_token(data: dict, expires_delta: timedelta | None = None):
    to_encode = data.copy()

    expire = datetime.now(timezone.utc) + (
        expires_delta or timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
    )

    to_encode.update({"exp": expire})

    encoded_jwt = jwt.encode(
        to_encode,
        SECRET_KEY,
        algorithm=ALGORITHM,
    )

    return encoded_jwt

여기서 SECRET_KEY는 토큰 서명에 사용된다.

이 값이 노출되면 공격자가 유효한 토큰을 직접 만들 수 있다. 예제에서는 문자열로 적었지만, 실제 서비스에서는 환경 변수나 별도 시크릿 관리 도구로 관리하는 게 좋다.

exp는 토큰 만료 시간이다.

JWT는 한 번 발급되면 서버가 별도 저장소에서 관리하지 않는 경우가 많다. 그래서 만료 시간이 없으면 탈취된 토큰이 계속 사용될 수 있다. Access Token은 보통 짧게 가져간다.

여기서는 30분으로 설정했다.

로그인 API 구현하기

이제 로그인 API를 만든다.

FastAPI에서는 OAuth2PasswordRequestForm을 사용하면 username, password 형식의 로그인 폼 데이터를 받을 수 있다.

from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordRequestForm
from datetime import timedelta

app = FastAPI()

@app.post("/token")
def login(form_data: OAuth2PasswordRequestForm = Depends()):
    user = authenticate_user(form_data.username, form_data.password)

    if not user:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="아이디 또는 비밀번호가 올바르지 않습니다.",
            headers={"WWW-Authenticate": "Bearer"},
        )

    access_token_expires = timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)

    access_token = create_access_token(
        data={"sub": user["username"]},
        expires_delta=access_token_expires,
    )

    return {
        "access_token": access_token,
        "token_type": "bearer",
    }

응답은 보통 이런 형태다.

{
  "access_token": "JWT_TOKEN_VALUE",
  "token_type": "bearer"
}

여기서 sub는 subject의 줄임말이다. 토큰이 누구를 가리키는지 담는 용도로 자주 사용된다.

이 예시에서는 username을 넣었다.

보호된 API에서 토큰 검증하기

로그인 API가 토큰을 발급했다면, 이제 토큰이 있어야 접근할 수 있는 API를 만들어야 한다.

먼저 OAuth2PasswordBearer를 설정한다.

from fastapi.security import OAuth2PasswordBearer

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

tokenUrl="token"은 토큰을 발급받는 경로를 의미한다.

앞에서 만든 로그인 API가 /token이므로 이렇게 맞춘다. 이 설정은 Swagger UI의 Authorize 버튼과도 연결된다.

이제 현재 사용자를 가져오는 함수를 만든다.

from jwt import PyJWTError

def get_current_user(token: str = Depends(oauth2_scheme)):
    credentials_exception = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="인증 정보를 확인할 수 없습니다.",
        headers={"WWW-Authenticate": "Bearer"},
    )

    try:
        payload = jwt.decode(
            token,
            SECRET_KEY,
            algorithms=[ALGORITHM],
        )

        username: str | None = payload.get("sub")

        if username is None:
            raise credentials_exception

    except PyJWTError:
        raise credentials_exception

    user = get_user(username)

    if user is None:
        raise credentials_exception

    if user.get("disabled"):
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="비활성화된 계정입니다.",
        )

    return user

이 함수의 흐름은 단순하다.

요청 헤더에서 Bearer 토큰을 꺼낸다.
JWT 서명을 검증한다.
토큰이 만료됐는지 확인한다.
토큰 안의 sub 값을 꺼낸다.
해당 사용자가 실제로 존재하는지 확인한다.
계정이 비활성화된 상태인지 확인한다.
문제가 없으면 사용자 정보를 반환한다.

여기서 disabled 확인이 빠지면, 정지되었거나 비활성화된 계정도 토큰만 유효하면 API에 접근할 수 있다. 그래서 사용자 조회 후 계정 상태를 한 번 더 확인하는 편이 안전하다.

이제 보호된 API에 적용한다.

@app.get("/users/me")
def read_users_me(current_user: dict = Depends(get_current_user)):
    return {
        "username": current_user["username"],
        "disabled": current_user["disabled"],
    }

이 API는 토큰 없이 접근하면 실패한다.

반대로 로그인해서 받은 토큰을 Authorization: Bearer ... 헤더에 넣으면 정상 응답을 받을 수 있다. 다만 disabled 값이 True인 계정은 토큰이 유효해도 접근이 차단된다.

전체 코드 예시

아래 코드는 흐름 이해용으로 한 파일에 정리한 예시다.

실제 서비스에서는 사용자 모델, 인증 로직, 설정값, 라우터를 파일별로 나누는 편이 좋다.

# main.py

from datetime import datetime, timedelta, timezone

import jwt
from jwt import PyJWTError
from passlib.context import CryptContext

from fastapi import Depends, FastAPI, HTTPException, status
from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm


# ==================================================
# 1. 기본 설정
# ==================================================

SECRET_KEY = "change-this-secret-key"
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 30

app = FastAPI()

pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")


# ==================================================
# 2. 예시 사용자 데이터
# ==================================================

fake_users_db = {
    "kim": {
        "username": "kim",
        "hashed_password": pwd_context.hash("1234"),
        "disabled": False,
    },
    "lee": {
        "username": "lee",
        "hashed_password": pwd_context.hash("1234"),
        "disabled": True,
    },
}


# ==================================================
# 3. 비밀번호 검증과 사용자 인증
# ==================================================

def verify_password(plain_password: str, hashed_password: str) -> bool:
    return pwd_context.verify(plain_password, hashed_password)


def get_user(username: str):
    user = fake_users_db.get(username)

    if user:
        return user

    return None


def authenticate_user(username: str, password: str):
    user = get_user(username)

    if not user:
        return None

    if not verify_password(password, user["hashed_password"]):
        return None

    return user


# ==================================================
# 4. JWT Access Token 생성
# ==================================================

def create_access_token(data: dict, expires_delta: timedelta | None = None):
    to_encode = data.copy()

    expire = datetime.now(timezone.utc) + (
        expires_delta or timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
    )

    to_encode.update({"exp": expire})

    encoded_jwt = jwt.encode(
        to_encode,
        SECRET_KEY,
        algorithm=ALGORITHM,
    )

    return encoded_jwt


# ==================================================
# 5. Bearer 토큰 검증과 현재 사용자 조회
# ==================================================

def get_current_user(token: str = Depends(oauth2_scheme)):
    credentials_exception = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="인증 정보를 확인할 수 없습니다.",
        headers={"WWW-Authenticate": "Bearer"},
    )

    try:
        payload = jwt.decode(
            token,
            SECRET_KEY,
            algorithms=[ALGORITHM],
        )

        username: str | None = payload.get("sub")

        if username is None:
            raise credentials_exception

    except PyJWTError:
        raise credentials_exception

    user = get_user(username)

    if user is None:
        raise credentials_exception

    if user.get("disabled"):
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="비활성화된 계정입니다.",
        )

    return user


# ==================================================
# 6. 로그인 API
# ==================================================

@app.post("/token")
def login(form_data: OAuth2PasswordRequestForm = Depends()):
    user = authenticate_user(form_data.username, form_data.password)

    if not user:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="아이디 또는 비밀번호가 올바르지 않습니다.",
            headers={"WWW-Authenticate": "Bearer"},
        )

    access_token_expires = timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)

    access_token = create_access_token(
        data={"sub": user["username"]},
        expires_delta=access_token_expires,
    )

    return {
        "access_token": access_token,
        "token_type": "bearer",
    }


# ==================================================
# 7. 보호된 API
# ==================================================

@app.get("/users/me")
def read_users_me(current_user: dict = Depends(get_current_user)):
    return {
        "username": current_user["username"],
        "disabled": current_user["disabled"],
    }

서버 실행은 다음 명령어로 한다.

uvicorn main:app --reload

실행 후 아래 주소로 접속한다.

http://127.0.0.1:8000/docs

Swagger UI에서 테스트하는 방법

FastAPI의 장점 중 하나는 인증 API도 Swagger UI에서 바로 테스트할 수 있다는 점이다.

순서는 다음과 같다.

/docs에 접속한다.
/token API를 연다.
Try it out을 클릭한다.
username에 kim, password에 1234를 입력한다.
응답으로 access_token을 받는다.
우측 상단 Authorize 버튼을 누른다.
토큰 값을 입력한다.
/users/me API를 호출한다.

여기서 헷갈리기 쉬운 부분이 있다.

Swagger UI의 Authorize 창에는 보통 토큰 값만 넣으면 된다. 직접 Bearer까지 붙이지 않아도 되는 경우가 많다.

반면 Postman, curl, 프론트엔드 코드에서 직접 요청을 보낼 때는 아래처럼 헤더를 구성해야 한다.

Authorization: Bearer 발급받은_토큰

curl로 요청하면 이런 형태다.

curl -X GET "http://127.0.0.1:8000/users/me" \
  -H "Authorization: Bearer 발급받은_토큰"

비활성화 계정 테스트도 해볼 수 있다.

예시 코드에서는 lee 계정의 disabled 값이 True다. 이 계정으로 로그인하면 토큰은 발급되지만, /users/me 요청에서는 403 Forbidden 응답을 받는다.

username: lee
password: 1234

이 흐름을 확인하면 “로그인 성공”과 “API 접근 허용”이 항상 같은 의미는 아니라는 점을 이해하기 쉽다.

JWT 로그인에서 자주 헷갈리는 부분

JWT는 로그인 상태를 저장하는 방식이 아니다

JWT는 서버 세션과 다르다.

서버가 “이 사용자는 로그인 중이다”라는 상태를 매번 저장해두는 방식이 아니라, 클라이언트가 들고 온 토큰을 서버가 검증하는 방식이다.

그래서 API 서버를 여러 대로 늘릴 때 유리한 점이 있다.

다만 토큰을 즉시 폐기하는 처리는 세션보다 까다로울 수 있다. 예를 들어 사용자가 로그아웃했는데 이미 발급된 Access Token이 아직 만료 전이라면, 서버가 별도 차단 목록을 관리하지 않는 한 토큰은 계속 유효할 수 있다.

이 부분 때문에 실무에서는 Access Token을 짧게 두고 Refresh Token을 함께 설계하는 경우가 많다.

JWT 안에는 민감한 정보를 넣지 않는다

JWT는 서명된 토큰이지, 기본적으로 내용을 숨기는 토큰이 아니다.

즉, 토큰 안의 payload는 디코딩해서 볼 수 있다.

따라서 이런 값은 넣지 않는 게 좋다.

비밀번호
전화번호
주민등록번호
결제 정보
내부 관리자 권한 설명
민감한 개인정보

대신 최소한의 식별자만 넣는 편이 안전하다.

예를 들면 다음 정도다.

{
  "sub": "kim",
  "exp": 1760000000
}

권한이 필요한 서비스라면 role이나 scope를 넣기도 하지만, 이 역시 서비스 구조에 따라 신중하게 설계해야 한다.

SECRET_KEY는 코드에 그대로 두지 않는다

예제에서는 설명을 위해 SECRET_KEY를 코드 안에 적었다.

SECRET_KEY = "change-this-secret-key"

하지만 실제 서비스에서는 이렇게 관리하면 안 된다.

GitHub에 코드가 올라가거나 서버 접근 권한이 잘못 관리되면 시크릿 키가 노출될 수 있다. 시크릿 키가 노출되면 공격자가 정상 서명을 가진 토큰을 만들 가능성이 생긴다.

실제 프로젝트에서는 환경 변수를 사용하는 방식이 일반적이다.

import os

SECRET_KEY = os.getenv("JWT_SECRET_KEY")

.env 파일을 쓴다면 해당 파일은 Git에 올라가지 않도록 .gitignore에 추가해야 한다.

Access Token 만료 시간은 짧게 잡는다

Access Token은 API 접근 권한을 가진 토큰이다.

이 토큰이 길게 살아 있으면 탈취됐을 때 피해 범위가 커진다. 그래서 보통 Access Token은 짧게, Refresh Token은 상대적으로 길게 설정한다.

다만 이 글에서는 흐름을 단순하게 보기 위해 Access Token만 다뤘다.

로그인 유지, 자동 재로그인, 토큰 재발급까지 구현하려면 Refresh Token 구조가 추가로 필요하다.

실제 서비스에서는 무엇을 더 추가해야 할까

지금 예시는 JWT 로그인 흐름을 이해하기 위한 최소 구조다.

실제 서비스에 적용하려면 다음 요소를 추가로 고려해야 한다.

항목	이유
데이터베이스 연동	사용자 정보를 메모리가 아니라 DB에서 관리해야 함
비밀번호 해싱 정책	bcrypt, argon2 등 안전한 해싱 방식 사용
환경 변수 관리	SECRET_KEY, DB URL 같은 민감 정보 보호
Refresh Token	로그인 유지와 토큰 재발급 처리
HTTPS	네트워크 구간에서 토큰 탈취 방지
토큰 폐기 전략	로그아웃, 계정 정지, 비밀번호 변경 시 대응
권한 관리	일반 사용자와 관리자 API 분리

여기서 중요한 건 처음부터 모든 걸 한 번에 넣지 않는 것이다.

먼저 로그인 요청 → 토큰 발급 → 보호된 API 접근 흐름을 잡고, 그 다음 DB 연동과 Refresh Token으로 확장하는 편이 이해하기 쉽다.

마무리 기준

FastAPI JWT 로그인은 코드보다 흐름을 먼저 이해하는 게 중요하다.

핵심은 세 가지다.

사용자가 로그인하면 서버가 JWT를 발급한다. 클라이언트는 이후 요청마다 Authorization: Bearer ... 헤더에 토큰을 담아 보낸다. 서버는 토큰의 서명, 만료 시간, 사용자 식별 정보, 계정 상태를 확인한 뒤 API 접근을 허용한다.

이 구조만 잡히면 OAuth2PasswordBearer, OAuth2PasswordRequestForm, jwt.encode(), jwt.decode()가 각각 어디에 쓰이는지도 자연스럽게 연결된다.

처음 구현할 때는 Access Token 하나로 흐름을 익히고, 실제 프로젝트에서는 DB 연동, 환경 변수, Refresh Token, HTTPS, 토큰 폐기 전략까지 차례로 붙이는 방식이 적절하다.

AI 코딩 에이전트 코드 검토 체크리스트: 초보자가 그대로 실행하기 전에 확인할 것

notebase — Thu, 28 May 2026 17:25:03 +0900

Codex, Claude Code, Cursor 같은 AI 코딩 도구가 만든 코드를 그대로 실행하기 전, 초보자가 반드시 확인해야 할 코드 검토 기준을 정리했습니다.

AI 코딩 도구를 쓰면 개발 속도는 확실히 빨라집니다.

Codex, Claude Code, Cursor, GitHub Copilot 같은 도구는 코드를 대신 작성해 주고, 오류를 고쳐 주고, 때로는 여러 파일을 한 번에 수정하기도 합니다.

하지만 여기서 중요한 문제가 하나 있습니다.

AI가 만든 코드라고 해서 무조건 안전한 코드는 아닙니다.

특히 개발을 막 시작한 초보자라면 AI가 제안한 코드가 맞는지, 위험한지, 내 프로젝트에 적절한지 판단하기 어려울 수 있습니다.

이 글에서는 AI 코딩 에이전트가 만든 코드를 그대로 실행하기 전에 초보자가 반드시 확인해야 할 기준을 정리합니다.

1. 먼저 AI가 어떤 파일을 바꿨는지 확인하기

AI 코딩 도구가 코드를 수정하면 가장 먼저 확인해야 할 것은 변경된 파일 목록입니다.

단순히 코드가 잘 작동하는지만 보면 안 됩니다. 어떤 파일이 바뀌었는지부터 확인해야 합니다.

예를 들어 다음과 같은 파일이 수정되었다면 특히 주의해야 합니다.

.env
package.json
requirements.txt
Dockerfile
docker-compose.yml
settings.py
config.py
auth.py
database.py

이 파일들은 프로젝트 설정, 인증, 데이터베이스 연결, 외부 패키지 설치와 관련된 경우가 많습니다.

즉, 잘못 수정되면 단순한 화면 오류가 아니라 보안 문제나 실행 환경 문제로 이어질 수 있습니다.

초보자를 위한 기준
내가 모르는 설정 파일이 바뀌었다면 바로 실행하지 말고, 변경 내용을 먼저 확인해야 합니다.

2. Git diff로 변경 내용 확인하기

AI가 코드를 수정했다면 git diff 명령어로 변경 내용을 확인하는 습관을 들이는 것이 좋습니다.

git diff

이 명령어는 현재 작업 중인 코드가 이전 상태와 어떻게 달라졌는지 보여줍니다.

초보자에게는 처음에 조금 낯설 수 있지만, AI 코드 검토에서는 가장 중요한 기본 도구입니다.

예를 들어 다음과 같은 부분을 확인할 수 있습니다.

- DEBUG = False
+ DEBUG = True

이런 변경은 겉으로 보기에는 단순하지만, 배포 환경에서는 위험할 수 있습니다.

또는 다음처럼 API 주소가 바뀌었을 수도 있습니다.

- API_URL = "https://api.example.com"
+ API_URL = "http://localhost:8000"

로컬 개발 환경에서는 문제없어 보여도, 실제 배포 환경에서는 서비스가 정상 동작하지 않을 수 있습니다.

초보자를 위한 기준
AI가 바꾼 코드가 많을수록 실행 전에 git diff를 먼저 확인해야 합니다.

3. 기능 브랜치에서 먼저 테스트하기

AI가 만든 코드를 바로 메인 브랜치에 반영하는 것은 위험할 수 있습니다.

가능하면 별도 브랜치를 만들어 테스트하는 것이 좋습니다.

git checkout -b feature/ai-code-review

이렇게 하면 AI가 만든 코드에 문제가 있더라도 기존 작업을 비교적 안전하게 보호할 수 있습니다.

테스트 후 문제가 없다면 그때 메인 브랜치에 병합하면 됩니다.

초보자 입장에서는 브랜치가 번거롭게 느껴질 수 있지만, AI 코딩 도구를 사용할수록 브랜치 사용은 더 중요해집니다.

AI는 한 번에 여러 파일을 바꿀 수 있기 때문입니다.

4. 민감 정보가 코드에 들어갔는지 확인하기

AI 코딩 도구를 사용할 때 가장 조심해야 할 부분 중 하나는 민감 정보 노출입니다.

다음과 같은 값이 코드에 직접 들어가 있으면 위험합니다.

API_KEY
SECRET_KEY
ACCESS_TOKEN
DATABASE_URL
PRIVATE_KEY
PASSWORD

예를 들어 AI가 다음과 같은 코드를 생성했다면 그대로 커밋하면 안 됩니다.

OPENAI_API_KEY = "sk-xxxxxxxxxxxxxxxx"

API 키나 비밀번호는 코드에 직접 넣지 않고, 보통 .env 파일이나 환경 변수로 관리해야 합니다.

import os

OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")

만약 실수로 GitHub에 키를 올렸다면 단순히 코드를 지우는 것으로 끝나지 않습니다.

GitHub에는 민감 정보가 올라왔을 때 자동으로 감지하거나 경고하는 시스템이 있지만, 이미 노출된 키는 안전하다고 보기 어렵습니다.

이 경우 해당 키를 폐기하고 새 키를 발급받는 것이 안전합니다.

초보자를 위한 기준
비밀번호, API 키, 토큰처럼 보이는 값이 코드에 직접 들어가 있으면 커밋하지 않아야 합니다.

5. 외부 패키지를 새로 설치하는지 확인하기

AI 코딩 도구는 문제를 해결하기 위해 새로운 패키지를 설치하라고 제안할 수 있습니다.

예를 들어 다음과 같은 명령어를 제안할 수 있습니다.

pip install some-package
npm install some-package

외부 패키지를 설치하는 것 자체가 문제는 아닙니다.

하지만 AI가 제안한 패키지가 실제로 존재하는지, 신뢰할 수 있는지, 프로젝트에 꼭 필요한지 확인해야 합니다.

AI는 가끔 실제로 존재하지 않는 패키지 이름을 만들어내기도 합니다. 이를 AI 할루시네이션이라고 부릅니다.

예를 들어 그럴듯해 보이는 패키지 이름을 제안했지만, 실제 공식 저장소에는 없을 수 있습니다.

또한 악의적인 사람이 유명 패키지와 비슷한 이름의 패키지를 만들어 배포하는 경우도 있습니다.

따라서 패키지를 설치하기 전에는 다음을 확인하는 것이 좋습니다.

패키지 이름이 정확한가?
공식 문서나 저장소가 있는가?
다운로드 수나 유지보수 상태가 지나치게 이상하지 않은가?
내가 해결하려는 문제에 꼭 필요한가?

초보자를 위한 기준
AI가 설치하라고 한 패키지는 바로 설치하지 말고, 이름과 출처를 먼저 확인해야 합니다.

6. 명령어 실행 전에 의미 확인하기

AI 코딩 에이전트는 코드를 작성하는 것뿐 아니라 터미널 명령어를 제안하기도 합니다.

예를 들어 다음과 같은 명령어가 나올 수 있습니다.

rm -rf node_modules
npm install

이 정도는 흔히 사용하는 명령어일 수 있지만, 초보자에게는 위험하게 느껴질 수 있습니다.

특히 다음과 같은 명령어는 바로 실행하지 않는 것이 좋습니다.

rm -rf /
sudo rm -rf
chmod -R 777
curl ... | bash
docker system prune -a

이 명령어들은 시스템 파일 삭제, 권한 변경, 외부 스크립트 실행, Docker 리소스 삭제 등으로 이어질 수 있습니다.

AI가 제안했다고 해서 모든 명령어를 그대로 실행하면 안 됩니다.

실행 전에 최소한 다음을 확인해야 합니다.

무엇을 삭제하는 명령어인가?
어떤 권한을 바꾸는 명령어인가?
외부 URL에서 스크립트를 받아 실행하는가?
되돌릴 수 있는 작업인가?

초보자를 위한 기준
명령어의 의미를 설명할 수 없다면 바로 실행하지 않는 것이 안전합니다.

7. 인증과 권한 관련 코드는 더 꼼꼼히 보기

로그인, 회원가입, 권한 검사, 토큰 검증과 관련된 코드는 특히 주의해야 합니다.

예를 들어 AI가 다음과 같은 코드를 만들 수 있습니다.

def is_admin(user):
    return True

이 코드는 테스트용으로는 단순해 보일 수 있지만, 실제 서비스에 들어가면 모든 사용자가 관리자 권한을 갖게 됩니다.

또는 인증이 필요한 API에서 권한 검사가 빠질 수도 있습니다.

@app.get("/admin/users")
def get_users():
    return users

이 코드가 관리자만 접근해야 하는 API라면, 인증과 권한 확인 로직이 반드시 필요합니다.

초보자는 인증 코드가 복잡하게 느껴질 수 있습니다.

하지만 최소한 다음 질문은 해봐야 합니다.

로그인하지 않은 사용자도 접근할 수 있는가?
일반 사용자가 관리자 기능에 접근할 수 있는가?
토큰 검증이 실제로 수행되는가?
임시 테스트 코드가 남아 있지 않은가?

초보자를 위한 기준
로그인, 권한, 토큰 관련 코드는 작동 여부보다 보안 흐름을 먼저 확인해야 합니다.

8. 데이터 삭제·수정 로직 확인하기

AI가 만든 코드 중 데이터베이스를 수정하거나 삭제하는 코드는 반드시 조심해야 합니다.

예를 들어 다음과 같은 코드는 위험할 수 있습니다.

DELETE FROM users;

조건 없이 실행되면 사용자 데이터가 전부 삭제될 수 있습니다.

또는 다음과 같은 코드도 주의해야 합니다.

User.objects.all().delete()

테스트 데이터 삭제용으로 생성된 코드가 실제 데이터베이스에 연결되면 큰 문제가 생길 수 있습니다.

데이터를 삭제하거나 수정하는 코드를 볼 때는 다음을 확인해야 합니다.

삭제 조건이 있는가?
실제 운영 데이터베이스에 연결되어 있지 않은가?
실행 전에 백업이 필요한 작업인가?
테스트 코드가 운영 코드에 섞여 있지 않은가?

초보자를 위한 기준
데이터 삭제 코드는 한 줄이라도 반드시 의심하고 확인해야 합니다.

9. 테스트 코드 또는 실행 결과 확인하기

AI가 만든 코드가 보기에는 그럴듯해도 실제로 작동하지 않을 수 있습니다.

따라서 가능하면 테스트를 실행해야 합니다.

Python 프로젝트라면 다음과 같은 명령어를 사용할 수 있습니다.

pytest

Node.js 프로젝트라면 다음과 같은 명령어를 사용할 수 있습니다.

npm test

테스트 코드가 없다면 최소한 직접 실행해 보면서 주요 기능이 깨지지 않았는지 확인해야 합니다.

확인할 항목은 다음과 같습니다.

기존 기능이 그대로 동작하는가?
새로 만든 기능이 의도대로 동작하는가?
오류 메시지가 새로 생기지 않았는가?
로그에 이상한 경고가 나오지 않는가?

AI가 만든 코드가 컴파일되거나 실행된다고 해서 항상 올바른 것은 아닙니다.

실행 결과와 기능 흐름까지 확인해야 합니다.

10. 코드가 너무 많이 바뀌었다면 나눠서 요청하기

AI 코딩 에이전트가 한 번에 너무 많은 파일을 수정하면 검토하기 어려워집니다.

초보자에게는 특히 위험합니다.

변경 범위가 크면 무엇이 문제를 일으켰는지 찾기 어렵기 때문입니다.

이럴 때는 AI에게 작업을 더 작게 나눠서 요청하는 것이 좋습니다.

한 번에 전체를 수정하지 말고, 로그인 오류만 먼저 수정해줘.

UI 수정은 제외하고 API 응답 형식만 변경해줘.

파일 하나씩 수정하고 각 변경 이유를 설명해줘.

AI를 잘 쓰는 핵심은 많은 코드를 한 번에 맡기는 것이 아니라, 검토 가능한 크기로 작업을 나누는 것입니다.

초보자를 위한 기준
내가 한 번에 이해할 수 없는 변경량이라면 AI에게 작업 범위를 줄이라고 요청해야 합니다.

11. AI에게 변경 이유를 설명하게 하기

AI가 코드를 수정한 뒤에는 단순히 결과만 확인하지 말고, 왜 그렇게 바꿨는지 설명하게 하는 것이 좋습니다.

예를 들어 다음처럼 요청할 수 있습니다.

방금 수정한 파일별로 변경 이유를 설명해줘.

이 코드가 기존 코드와 비교해서 어떤 문제를 해결하는지 알려줘.

초보자가 주의해야 할 위험한 변경 사항이 있는지 알려줘.

이렇게 질문하면 AI가 만든 코드를 이해하는 데 도움이 됩니다.

또한 AI의 설명이 애매하거나 앞뒤가 맞지 않는다면, 해당 코드는 다시 확인해야 합니다.

AI가 설명하지 못하는 코드는 사람도 검토하기 어렵습니다.

12. 초보자를 위한 최종 체크리스트

AI 코딩 도구가 만든 코드를 실행하기 전에는 아래 항목을 확인해 보세요.

□ 어떤 파일이 바뀌었는지 확인했다.
□ git diff로 변경 내용을 확인했다.
□ 기능 브랜치에서 먼저 테스트했다.
□ API 키, 비밀번호, 토큰이 코드에 직접 들어가지 않았다.
□ 새로 설치하는 패키지의 이름과 출처를 확인했다.
□ 터미널 명령어의 의미를 이해했다.
□ 인증, 권한, 토큰 관련 코드가 안전한지 확인했다.
□ 데이터 삭제·수정 로직에 조건이 있는지 확인했다.
□ 테스트를 실행하거나 주요 기능을 직접 확인했다.
□ 변경 범위가 너무 크면 AI에게 작업을 나눠 달라고 요청했다.
□ AI에게 변경 이유를 설명하게 했다.

이 체크리스트를 모두 지키면 AI가 만든 코드를 훨씬 안전하게 검토할 수 있습니다.

마무리

AI 코딩 에이전트는 개발을 빠르게 만들어 주는 강력한 도구입니다.

하지만 AI가 만든 코드를 그대로 믿고 실행하는 습관은 위험합니다.

특히 초보자일수록 AI가 작성한 코드의 의미를 완전히 이해하지 못한 상태에서 승인하거나 실행할 가능성이 높습니다.

AI 코딩 도구를 안전하게 사용하려면 중요한 기준은 하나입니다.

AI에게 코드를 맡기더라도, 최종 책임은 실행하는 사람에게 있습니다.

따라서 AI가 만든 코드는 항상 변경 파일, 보안 정보, 외부 패키지, 명령어, 데이터 삭제 로직을 확인한 뒤 실행해야 합니다.

초보자를 위한 핵심 요약
이 코드가 무엇을 바꾸는지 모르면 바로 승인하지 않는다.

FastAPI 프로젝트 구조 잡는 법: main.py 하나에서 벗어나기

notebase — Wed, 27 May 2026 13:23:23 +0900

FastAPI 프로젝트가 커질 때 main.py 하나로 관리하기 어려워집니다. APIRouter, schemas, models, database 파일을 어떤 기준으로 나누면 좋은지 초보자 눈높이에서 정리합니다.

FastAPI 프로젝트 구조는 처음부터 복잡하게 잡을 필요는 없습니다. 다만 API가 늘어나고 데이터베이스, 요청 모델, 응답 모델이 생기면 main.py 하나로 관리하기 어려워집니다.

처음에는 한 파일로 시작해도 괜찮습니다.

하지만 어느 순간 이런 문제가 생깁니다.

main.py 안에
- API 코드
- Pydantic 모델
- DB 연결 코드
- 테이블 모델
- 예외 처리
- 비즈니스 로직
이 전부 섞여 있음

이렇게 되면 코드를 고치기 어려워집니다.
새로운 API를 추가할 때마다 main.py를 계속 열어야 하고, 어디에 무엇이 있는지도 헷갈립니다.

FastAPI 공식 문서에서도 작은 예제는 한 파일로 작성할 수 있지만, 실제 웹 API를 만들다 보면 여러 파일로 나누는 경우가 많다고 설명합니다. 이때 핵심이 되는 기능이 APIRouter입니다.

처음에는 main.py 하나로도 충분하다

입문 단계에서는 아래처럼 작성해도 문제 없습니다.

fastapi-basic/
└── main.py

예를 들어 간단한 API만 만들 때는 main.py 하나가 더 이해하기 쉽습니다.

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def read_root():
    return {"message": "Hello FastAPI"}

이 단계에서 억지로 폴더를 많이 나누면 오히려 헷갈립니다.

초보자가 처음부터 아래처럼 구조를 만들 필요는 없습니다.

app/
├── api/
├── core/
├── db/
├── models/
├── schemas/
├── services/
└── repositories/

이 구조가 틀렸다는 뜻은 아닙니다.
다만 아직 API가 몇 개 없는 상태라면 과한 구조입니다.

프로젝트 구조는 “처음부터 멋있게”가 아니라, 코드가 많아졌을 때 “덜 헷갈리게” 만드는 도구에 가깝습니다.

FastAPI 프로젝트는 언제 나눠야 할까?

아래 상황이 생기면 파일 분리를 고민할 만합니다.

- API 주소가 5개 이상으로 늘어남
- users, items, posts처럼 기능이 나뉘기 시작함
- Pydantic 모델이 많아짐
- 데이터베이스 연결 코드가 들어감
- 인증, 예외 처리, 설정값 관리가 필요해짐
- main.py가 너무 길어져서 스크롤이 많아짐

특히 main.py에서 아래 코드들이 한꺼번에 보이기 시작하면 분리할 시점입니다.

app = FastAPI()

class UserCreate(BaseModel):
    ...

class UserResponse(BaseModel):
    ...

engine = create_engine(...)

@app.get("/users")
def get_users():
    ...

@app.post("/users")
def create_user():
    ...

이런 코드는 처음에는 편합니다.
하지만 프로젝트가 커질수록 수정하기 어려워집니다.

입문자에게 적당한 FastAPI 프로젝트 구조

처음 파일을 나눠본다면 아래 정도가 적당합니다.

fastapi-project/
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── database.py
│   ├── models.py
│   ├── schemas.py
│   └── routers/
│       ├── __init__.py
│       └── users.py
└── requirements.txt

이 구조는 너무 복잡하지 않으면서도, FastAPI 프로젝트에서 자주 등장하는 역할을 분리해 줍니다.

FastAPI 공식 문서의 “Bigger Applications” 예시도 app/main.py, dependencies.py, routers/ 같은 방식으로 파일을 나누는 흐름을 보여줍니다. 특히 routers 폴더 안에 기능별 API 파일을 두는 방식이 핵심입니다.

각 파일의 역할

위 구조에서 각 파일은 대략 이런 역할을 합니다.

app/main.py           → FastAPI 앱 생성, 라우터 등록
app/database.py       → 데이터베이스 연결 설정
app/models.py         → DB 테이블 모델
app/schemas.py        → 요청/응답 데이터 모델
app/routers/users.py  → users 관련 API

하나씩 보면 어렵지 않습니다.

main.py: 앱의 시작점

main.py는 FastAPI 앱이 시작되는 파일입니다.

from fastapi import FastAPI
from app.routers import users

app = FastAPI()

app.include_router(users.router)


@app.get("/")
def read_root():
    return {"message": "FastAPI project structure"}

여기서 중요한 코드는 이 부분입니다.

app.include_router(users.router)

users.py에 작성한 API를 main.py에 연결하는 코드입니다.

즉, main.py는 모든 API 코드를 직접 들고 있는 파일이 아닙니다.
여러 라우터를 모아서 앱에 등록하는 역할을 합니다.

routers/users.py: 기능별 API 파일

routers/users.py에는 사용자와 관련된 API를 작성합니다.

from fastapi import APIRouter

router = APIRouter(
    prefix="/users",
    tags=["users"]
)


@router.get("/")
def get_users():
    return [
        {"id": 1, "name": "kim"},
        {"id": 2, "name": "lee"}
    ]


@router.get("/{user_id}")
def get_user(user_id: int):
    return {"id": user_id, "name": "kim"}

여기서는 FastAPI() 대신 APIRouter()를 사용합니다.

router = APIRouter(
    prefix="/users",
    tags=["users"]
)

prefix="/users"를 지정했기 때문에 아래 API는

@router.get("/")
def get_users():
    ...

실제로는 다음 주소로 동작합니다.

GET /users/

그리고 아래 API는

@router.get("/{user_id}")
def get_user(user_id: int):
    ...

다음 주소로 동작합니다.

GET /users/1

이 방식의 장점은 명확합니다.
사용자 API는 users.py, 게시글 API는 posts.py, 상품 API는 products.py처럼 기능별로 나눌 수 있습니다.

FastAPI의 APIRouter는 이런 식으로 여러 API를 모듈 단위로 나눌 때 사용하는 도구입니다. Flask를 써본 사람이라면 Blueprint와 비슷한 역할로 이해할 수 있습니다.

prefix와 슬래시 경로를 헷갈리지 말자

여기서 한 가지 주의할 점이 있습니다.

prefix="/users"를 지정한 상태에서 라우터 내부 경로를 어떻게 쓰느냐에 따라 실제 주소가 조금 달라질 수 있습니다.

router = APIRouter(prefix="/users")


@router.get("")
def get_users():
    return []

이 경우 경로는 보통 아래처럼 이해하면 됩니다.

GET /users

반면 아래처럼 작성하면

router = APIRouter(prefix="/users")


@router.get("/")
def get_users():
    return []

경로는 다음처럼 됩니다.

GET /users/

둘 중 하나가 무조건 정답은 아닙니다.
다만 프로젝트 안에서 기준을 섞으면 헷갈릴 수 있습니다.

예를 들어 어떤 파일에서는 @router.get("")를 쓰고, 다른 파일에서는 @router.get("/")를 쓰면 주소 끝의 슬래시 때문에 예상과 다르게 동작한다고 느낄 수 있습니다.

입문 단계에서는 아래처럼 하나의 기준을 정해두는 편이 좋습니다.

목록 조회 API는 @router.get("/") 형태로 작성한다.
prefix는 /users, /posts처럼 기능 단위로 지정한다.

이 글의 예제도 눈으로 보기 쉬운 @router.get("/") 방식을 기준으로 설명합니다.

schemas.py: 요청과 응답 모델 분리

schemas.py에는 Pydantic 모델을 작성합니다.

from pydantic import BaseModel


class UserCreate(BaseModel):
    name: str
    email: str


class UserResponse(BaseModel):
    id: int
    name: str
    email: str

이 파일은 API에서 주고받는 데이터 모양을 정의하는 곳입니다.

예를 들어 회원가입 API가 있다면 요청 데이터는 이런 형태일 수 있습니다.

{
  "name": "kim",
  "email": "kim@example.com"
}

이때 UserCreate 모델을 사용하면 FastAPI가 요청 데이터의 구조를 검사해 줍니다.

@router.post("/")
def create_user(user: UserCreate):
    return user

여기서 중요한 점은 schemas.py가 데이터베이스 테이블을 정의하는 파일은 아니라는 것입니다.

schemas.py는 API 요청과 응답의 모양을 담당합니다.

models.py: 데이터베이스 테이블 모델

models.py에는 데이터베이스 테이블과 연결되는 모델을 작성합니다.

예를 들어 SQLAlchemy를 사용한다면 이런 코드가 들어갈 수 있습니다.

from sqlalchemy import Column, Integer, String
from app.database import Base


class User(Base):
    __tablename__ = "users"

    id = Column(Integer, primary_key=True, index=True)
    name = Column(String, nullable=False)
    email = Column(String, unique=True, index=True, nullable=False)

schemas.py와 models.py를 헷갈리기 쉽습니다.

간단히 구분하면 이렇습니다.

파일	역할
`schemas.py`	API 요청/응답 데이터 구조
`models.py`	데이터베이스 테이블 구조

실제로는 둘 다 “모델”처럼 보이기 때문에 초보자가 자주 헷갈립니다.

하지만 역할이 다릅니다.

schemas.py는 클라이언트와 주고받는 데이터에 가깝고,
models.py는 데이터베이스에 저장되는 구조에 가깝습니다.

database.py: DB 연결 설정

database.py에는 데이터베이스 연결 코드를 둡니다.

from sqlalchemy import create_engine
from sqlalchemy.orm import declarative_base, sessionmaker

DATABASE_URL = "sqlite:///./test.db"

engine = create_engine(
    DATABASE_URL,
    connect_args={"check_same_thread": False}
)

SessionLocal = sessionmaker(
    autocommit=False,
    autoflush=False,
    bind=engine
)

Base = declarative_base()

SQLite를 사용할 때는 위처럼 sqlite:///./test.db 형태로 DB 파일을 지정할 수 있습니다.

FastAPI 공식 SQL 데이터베이스 문서에서도 입문 예제에서는 SQLite를 사용합니다. SQLite는 하나의 파일로 동작하고, Python에서 기본적으로 지원하기 때문에 예제와 실습에 적합합니다. 다만 실제 운영 환경에서는 PostgreSQL 같은 데이터베이스 서버를 사용할 수 있다고 안내합니다.

여기서 중요한 건 DB 연결 코드를 main.py에 직접 넣지 않는다는 점입니다.

DB 설정은 프로젝트 전체에서 재사용될 가능성이 높습니다.
따라서 database.py처럼 따로 분리하는 편이 관리하기 쉽습니다.

전체 코드 흐름으로 보면 더 쉽다

위 구조를 흐름으로 보면 이렇습니다.

main.py
  └── users.router 등록

routers/users.py
  └── /users API 작성

schemas.py
  └── 요청/응답 데이터 구조 정의

models.py
  └── DB 테이블 구조 정의

database.py
  └── DB 연결 설정

즉, main.py가 모든 일을 하는 구조에서 벗어나 각 파일이 역할을 나눠 갖는 방식입니다.

이렇게 나누면 코드를 찾기 쉬워집니다.

사용자 API를 수정하고 싶으면 routers/users.py를 보면 됩니다.
요청 데이터 구조를 수정하고 싶으면 schemas.py를 보면 됩니다.
DB 연결 설정을 바꾸고 싶으면 database.py를 보면 됩니다.

기능이 더 많아지면 어떻게 나눌까?

프로젝트가 조금 더 커지면 routers 안에 파일을 추가할 수 있습니다.

app/
├── main.py
├── database.py
├── models.py
├── schemas.py
└── routers/
    ├── __init__.py
    ├── users.py
    ├── posts.py
    └── comments.py

그리고 main.py에서 각각 등록합니다.

from fastapi import FastAPI
from app.routers import users, posts, comments

app = FastAPI()

app.include_router(users.router)
app.include_router(posts.router)
app.include_router(comments.router)

각 라우터 파일은 자기 기능만 담당합니다.

users.py     → 사용자 API
posts.py     → 게시글 API
comments.py  → 댓글 API

이 정도만 해도 입문자 프로젝트에서는 충분히 깔끔합니다.

더 큰 프로젝트에서는 기능별 폴더로 나누기도 한다

프로젝트가 더 커지면 아래처럼 기능별로 폴더를 나누는 방식도 사용할 수 있습니다.

app/
├── main.py
├── database.py
└── users/
    ├── router.py
    ├── schemas.py
    ├── models.py
    └── service.py

또는 여러 기능을 이렇게 나눌 수도 있습니다.

app/
├── main.py
├── database.py
├── users/
│   ├── router.py
│   ├── schemas.py
│   └── service.py
├── posts/
│   ├── router.py
│   ├── schemas.py
│   └── service.py
└── comments/
    ├── router.py
    ├── schemas.py
    └── service.py

이 구조는 기능 단위가 명확한 프로젝트에서 유용합니다.

예를 들어 사용자 기능이 복잡해져서 사용자 API, 사용자 요청 모델, 사용자 서비스 로직이 많아졌다면 users/ 폴더로 묶는 편이 낫습니다.

다만 처음부터 이 구조로 시작할 필요는 없습니다.

입문 단계에서는 오히려 파일을 찾는 데 시간이 더 걸릴 수 있습니다.

services.py는 언제 필요할까?

초보자 프로젝트에서는 처음부터 services.py를 만들지 않아도 됩니다.

하지만 API 함수 안에 로직이 길어지면 분리하는 편이 좋습니다.

예를 들어 아래 코드는 API 함수가 너무 많은 일을 합니다.

@router.post("/")
def create_user(user: UserCreate):
    # 이메일 중복 확인
    # 비밀번호 암호화
    # DB 저장
    # 응답 데이터 생성
    return result

이런 경우에는 실제 처리 로직을 서비스 함수로 분리할 수 있습니다.

@router.post("/")
def create_user(user: UserCreate):
    return user_service.create_user(user)

그러면 API 파일은 요청을 받고 응답을 돌려주는 역할에 집중할 수 있습니다.

다만 이 단계는 프로젝트가 어느 정도 커졌을 때 고민해도 늦지 않습니다.

dependencies.py는 언제 필요할까?

FastAPI에는 의존성 주입 기능이 있습니다.
FastAPI의 Dependency Injection 시스템은 다른 구성 요소를 쉽게 통합하고 재사용할 수 있도록 설계되어 있습니다.

예를 들어 DB 세션을 여러 API에서 반복해서 사용한다면 아래처럼 의존성 함수를 만들 수 있습니다.

from app.database import SessionLocal


def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

이런 함수는 dependencies.py에 둘 수 있습니다.

app/
├── main.py
├── database.py
├── dependencies.py
└── routers/
    └── users.py

그리고 API에서 이렇게 사용합니다.

from fastapi import Depends
from sqlalchemy.orm import Session
from app.dependencies import get_db


@router.get("/")
def get_users(db: Session = Depends(get_db)):
    return []

처음에는 낯설 수 있지만, DB 연결이나 인증 처리처럼 여러 API에서 반복되는 코드를 줄일 때 유용합니다.

init.py는 왜 필요할까?

폴더 구조 예시를 보면 __init__.py 파일이 자주 보입니다.

app/
├── __init__.py
└── routers/
    ├── __init__.py
    └── users.py

__init__.py는 해당 폴더를 Python 패키지로 인식하게 해주는 파일입니다.

최근 Python에서는 일부 상황에서 없어도 동작할 수 있지만, 입문자라면 일단 만들어두는 편이 덜 헷갈립니다.

특히 아래처럼 import를 할 때 도움이 됩니다.

from app.routers import users

파일 안에는 아무 코드가 없어도 됩니다.

# 비워둬도 됩니다.

초보자가 피하면 좋은 구조

FastAPI 프로젝트를 처음 나눌 때 흔히 하는 실수가 있습니다.

너무 빨리 구조를 복잡하게 만드는 것입니다.

예를 들어 API가 3개뿐인데 아래처럼 나누면 오히려 불편합니다.

app/
├── api/
│   └── v1/
│       └── endpoints/
├── core/
├── crud/
├── db/
├── models/
├── schemas/
├── services/
├── repositories/
└── utils/

이런 구조는 실무 프로젝트에서 쓸 수는 있습니다.

하지만 입문자 입장에서는 “코드를 어디에 넣어야 하지?”라는 고민만 늘어납니다.

처음에는 아래 정도면 충분합니다.

app/
├── main.py
├── database.py
├── models.py
├── schemas.py
└── routers/
    └── users.py

프로젝트 구조는 실력 과시용이 아닙니다.
수정하기 쉬운 코드를 만들기 위한 최소한의 정리입니다.

FastAPI 프로젝트 구조를 잡을 때 기준

파일을 나눌 때는 이름보다 기준이 더 중요합니다.

아래 기준으로 판단하면 됩니다.

main.py
→ 앱 생성과 라우터 등록만 남긴다.

routers/
→ API 주소별 처리 코드를 둔다.

schemas.py
→ 요청/응답 데이터 모델을 둔다.

models.py
→ DB 테이블 모델을 둔다.

database.py
→ DB 연결 설정을 둔다.

dependencies.py
→ 여러 API에서 반복해서 쓰는 의존성 함수를 둔다.

services.py
→ API 안에서 처리하기엔 긴 비즈니스 로직을 둔다.

처음부터 모든 파일이 필요하지는 않습니다.

예를 들어 DB를 쓰지 않는 프로젝트라면 database.py, models.py는 필요 없습니다.
서비스 로직이 거의 없다면 services.py도 없어도 됩니다.

필요할 때 추가하면 됩니다.

처음 구조는 단순한 게 좋다

FastAPI 프로젝트 구조에 정답은 없습니다.

하지만 입문자라면 아래 구조부터 시작하는 게 가장 무난합니다.

app/
├── main.py
├── database.py
├── models.py
├── schemas.py
└── routers/
    └── users.py

이 구조만 이해해도 FastAPI 프로젝트를 한 파일에서 벗어나 관리할 수 있습니다.

여기서 중요한 기준은 하나입니다.

파일을 많이 나누는 것이 좋은 구조가 아니라, 코드를 찾고 고치기 쉬운 구조가 좋은 구조입니다.

API가 적으면 main.py 하나로 시작해도 됩니다.
API가 늘어나면 routers로 나누면 됩니다.
DB와 요청 모델이 생기면 database.py, models.py, schemas.py를 분리하면 됩니다.

처음부터 실무형 구조를 따라 하기보다, 프로젝트가 커지는 속도에 맞춰 한 단계씩 나누는 편이 더 안전합니다.

FastAPI CRUD API 만들기: GET, POST, PUT, DELETE 한 번에 이해하기

notebase — Wed, 27 May 2026 08:52:05 +0900

FastAPI로 간단한 CRUD API를 만드는 방법을 예제로 정리했습니다. GET, POST, PUT, DELETE 요청이 각각 어떤 역할을 하는지 코드와 함께 확인할 수 있습니다.

FastAPI CRUD API를 처음 만들 때는 데이터베이스부터 연결하기보다, 메모리 데이터를 사용해 흐름을 먼저 잡는 게 좋습니다. GET, POST, PUT, DELETE가 각각 어떤 역할을 하는지 코드로 바로 확인할 수 있기 때문입니다.

이번 예제에서는 상품 정보를 다루는 간단한 CRUD API를 만들어보겠습니다.

데이터베이스는 아직 사용하지 않습니다.
파이썬 딕셔너리에 데이터를 저장하는 방식으로 API 구조만 먼저 익힙니다.

CRUD API란?

CRUD는 데이터를 다룰 때 가장 기본이 되는 4가지 작업입니다.

CRUD	의미	HTTP 메서드	예시
Create	생성	POST	상품 추가
Read	조회	GET	상품 목록 조회
Update	수정	PUT	상품 정보 수정
Delete	삭제	DELETE	상품 삭제

실제로 백엔드 API를 만들면 대부분 이 흐름에서 시작합니다.

예를 들어 쇼핑몰 상품 API라면 다음과 같은 기능이 필요합니다.

상품 목록 조회
특정 상품 조회
새 상품 추가
상품 이름이나 가격 수정
상품 삭제

이게 바로 CRUD API입니다.

만들 API 구조

이번 글에서 만들 API는 아래와 같습니다.

기능	메서드	경로
전체 상품 조회	GET	`/items`
특정 상품 조회	GET	`/items/{item_id}`
상품 생성	POST	`/items`
상품 수정	PUT	`/items/{item_id}`
상품 삭제	DELETE	`/items/{item_id}`

여기서 {item_id}는 경로 파라미터입니다.

예를 들어 /items/1로 요청하면 ID가 1인 상품을 조회합니다.

프로젝트 준비

먼저 프로젝트 폴더를 만들고 이동합니다.

mkdir fastapi-crud-example
cd fastapi-crud-example

가능하면 프로젝트별로 가상환경을 만든 뒤 진행하는 것을 추천합니다.
여러 파이썬 프로젝트를 같이 다루다 보면 패키지 버전이 섞여 문제가 생길 수 있기 때문입니다.

macOS 또는 Linux에서는 아래처럼 실행합니다.

python -m venv .venv
source .venv/bin/activate

Windows에서는 아래 명령어를 사용할 수 있습니다.

python -m venv .venv
.venv\Scripts\activate

그다음 FastAPI와 실행 서버인 Uvicorn을 설치합니다.

pip install fastapi uvicorn

프로젝트 폴더 안에 main.py 파일을 만듭니다.

fastapi-crud-example/
└── main.py

FastAPI는 파이썬 타입 힌트를 기반으로 API를 만들 수 있는 웹 프레임워크입니다.
입문 단계에서는 타입 힌트가 낯설 수 있지만, FastAPI에서는 이 타입 정보가 요청 데이터 검증과 자동 문서화에 같이 활용됩니다.

기본 코드 작성하기

main.py에 먼저 기본 구조를 작성합니다.

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

여기서 FastAPI()는 애플리케이션 객체입니다.

HTTPException은 요청한 데이터가 없거나 잘못된 요청이 들어왔을 때 HTTP 상태 코드를 반환하기 위해 사용합니다.

BaseModel은 요청 데이터의 구조를 정의할 때 사용합니다.
FastAPI에서는 요청 본문을 받을 때 Pydantic 모델을 사용해 데이터 구조를 선언할 수 있습니다.

상품 모델 만들기

이번 예제에서는 상품에 name, price, description 값을 넣겠습니다.

class Item(BaseModel):
    name: str
    price: int
    description: str | None = None

이 예제는 Python 3.10 이상 문법을 기준으로 작성했습니다.
str | None은 “문자열이거나 None일 수 있다”는 뜻입니다.

Python 3.9 이하를 사용한다면 아래처럼 Optional을 사용하면 됩니다.

from typing import Optional

class Item(BaseModel):
    name: str
    price: int
    description: Optional[str] = None

각 필드의 의미는 다음과 같습니다.

필드	타입	설명
`name`	`str`	상품 이름
`price`	`int`	상품 가격
`description`	`str \| None`	상품 설명, 없어도 됨

description에는 기본값으로 None을 넣었습니다.

즉, 상품을 생성할 때 설명은 생략할 수 있습니다.

{
  "name": "Keyboard",
  "price": 50000
}

이런 요청도 가능합니다.

임시 데이터 저장소 만들기

아직 데이터베이스를 연결하지 않으므로 파이썬 딕셔너리를 사용합니다.

items = {
    1: {
        "name": "Keyboard",
        "price": 50000,
        "description": "Mechanical keyboard"
    },
    2: {
        "name": "Mouse",
        "price": 30000,
        "description": "Wireless mouse"
    }
}

실제 서비스라면 이 데이터는 서버가 꺼질 때 사라지면 안 됩니다.

그래서 SQLite, PostgreSQL 같은 데이터베이스를 사용합니다.
하지만 지금 단계에서는 CRUD 흐름을 이해하는 게 목적이므로 메모리 데이터로 충분합니다.

여기서 items 딕셔너리의 키는 1, 2처럼 정수입니다.
뒤에서 API 응답을 보면 "1", "2"처럼 문자열로 보이는데, 이건 오류가 아닙니다.

JSON 객체의 키는 문자열로 표현되기 때문에 FastAPI가 응답을 JSON으로 변환하는 과정에서 그렇게 표시됩니다.
파이썬 코드 안에서는 여전히 items[1]처럼 정수 키로 접근합니다.

전체 상품 조회 API 만들기

먼저 전체 상품을 조회하는 API입니다.

@app.get("/items")
def get_items():
    return items

이제 서버를 실행합니다.

uvicorn main:app --reload

브라우저에서 아래 주소로 접속합니다.

http://127.0.0.1:8000/items

그러면 현재 저장된 상품 목록이 JSON 형태로 반환됩니다.

{
  "1": {
    "name": "Keyboard",
    "price": 50000,
    "description": "Mechanical keyboard"
  },
  "2": {
    "name": "Mouse",
    "price": 30000,
    "description": "Wireless mouse"
  }
}

여기서 중요한 점은 API의 응답이 HTML 페이지가 아니라 JSON 데이터라는 점입니다.

백엔드 API는 보통 프론트엔드, 모바일 앱, 다른 서버가 데이터를 가져갈 수 있도록 JSON을 반환합니다.

특정 상품 조회 API 만들기

이번에는 상품 ID를 받아서 하나의 상품만 조회하는 API를 만듭니다.

@app.get("/items/{item_id}")
def get_item(item_id: int):
    if item_id not in items:
        raise HTTPException(status_code=404, detail="Item not found")

    return items[item_id]

요청 예시는 다음과 같습니다.

GET /items/1

응답은 이렇게 나옵니다.

{
  "name": "Keyboard",
  "price": 50000,
  "description": "Mechanical keyboard"
}

여기서 /items/{item_id}의 {item_id}는 함수의 item_id 매개변수로 전달됩니다.

주소로 들어오는 값은 원래 문자열입니다.
하지만 함수에서 item_id: int로 선언했기 때문에 FastAPI가 정수로 변환해 줍니다.

예를 들어 /items/1로 요청하면 "1"이라는 문자열이 들어오지만, 함수 안에서는 정수 1로 다룰 수 있습니다.
만약 /items/abc처럼 숫자로 바꿀 수 없는 값이 들어오면 FastAPI가 자동으로 검증 오류를 반환합니다.

존재하지 않는 ID를 요청하면 404 Not Found를 반환합니다.

GET /items/999

응답 예시는 다음과 같습니다.

{
  "detail": "Item not found"
}

여기서 단순히 "없음" 같은 문자열을 반환하지 않고 404 상태 코드를 반환하는 게 좋습니다.

API를 사용하는 쪽에서 “요청은 성공했지만 데이터가 없는 것인지”, “요청한 리소스 자체가 없는 것인지”를 구분할 수 있기 때문입니다.

상품 생성 API 만들기

상품을 새로 추가할 때는 POST를 사용합니다.

@app.post("/items")
def create_item(item: Item):
    new_id = max(items.keys()) + 1 if items else 1

    items[new_id] = item.model_dump()

    return {
        "id": new_id,
        "item": items[new_id]
    }

item: Item 부분이 요청 본문입니다.

클라이언트가 아래와 같은 JSON을 보내면 FastAPI가 Item 모델에 맞는지 자동으로 확인합니다.

{
  "name": "Monitor",
  "price": 200000,
  "description": "27 inch monitor"
}

정상 요청이면 새 ID와 함께 생성된 상품이 반환됩니다.

{
  "id": 3,
  "item": {
    "name": "Monitor",
    "price": 200000,
    "description": "27 inch monitor"
  }
}

item.model_dump()는 Pydantic 모델을 파이썬 딕셔너리로 바꾸는 코드입니다.

Pydantic v2 기준에서는 예전의 .dict()보다 .model_dump()를 사용하는 방식이 더 자연스럽습니다.

상품 수정 API 만들기

기존 상품을 수정할 때는 PUT을 사용합니다.

@app.put("/items/{item_id}")
def update_item(item_id: int, item: Item):
    if item_id not in items:
        raise HTTPException(status_code=404, detail="Item not found")

    items[item_id] = item.model_dump()

    return {
        "id": item_id,
        "item": items[item_id]
    }

이 코드에서도 /items/{item_id}의 {item_id}가 함수의 item_id: int로 연결됩니다.
특정 상품 조회 API와 같은 방식으로 FastAPI가 경로 값을 정수로 변환하고 검증합니다.

요청 예시는 다음과 같습니다.

PUT /items/1

요청 본문은 이렇게 보낼 수 있습니다.

{
  "name": "Gaming Keyboard",
  "price": 80000,
  "description": "RGB mechanical keyboard"
}

그러면 ID가 1인 상품 정보가 새 데이터로 바뀝니다.

{
  "id": 1,
  "item": {
    "name": "Gaming Keyboard",
    "price": 80000,
    "description": "RGB mechanical keyboard"
  }
}

여기서 오해하기 쉬운 부분이 있습니다.

PUT은 보통 “전체 수정”에 가깝게 사용합니다.
즉, 상품 이름만 바꾸고 싶더라도 전체 필드를 다시 보내는 방식입니다.

일부 필드만 수정하려면 PATCH를 따로 설계하는 경우가 많습니다.

이번 글에서는 CRUD 기본 구조에 집중하기 위해 PUT만 사용하겠습니다.

상품 삭제 API 만들기

상품을 삭제할 때는 DELETE를 사용합니다.

@app.delete("/items/{item_id}")
def delete_item(item_id: int):
    if item_id not in items:
        raise HTTPException(status_code=404, detail="Item not found")

    deleted_item = items.pop(item_id)

    return {
        "message": "Item deleted",
        "item": deleted_item
    }

요청 예시는 다음과 같습니다.

DELETE /items/2

응답은 이렇게 나옵니다.

{
  "message": "Item deleted",
  "item": {
    "name": "Mouse",
    "price": 30000,
    "description": "Wireless mouse"
  }
}

삭제 후 다시 /items를 조회하면 ID가 2인 상품은 사라진 상태입니다.

단, 지금은 메모리 데이터를 사용하므로 서버를 재시작하면 처음 코드에 적어둔 데이터로 다시 돌아갑니다.

전체 코드

아래는 지금까지 작성한 전체 코드입니다.

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    price: int
    description: str | None = None


items = {
    1: {
        "name": "Keyboard",
        "price": 50000,
        "description": "Mechanical keyboard"
    },
    2: {
        "name": "Mouse",
        "price": 30000,
        "description": "Wireless mouse"
    }
}


@app.get("/items")
def get_items():
    return items


@app.get("/items/{item_id}")
def get_item(item_id: int):
    if item_id not in items:
        raise HTTPException(status_code=404, detail="Item not found")

    return items[item_id]


@app.post("/items")
def create_item(item: Item):
    new_id = max(items.keys()) + 1 if items else 1

    items[new_id] = item.model_dump()

    return {
        "id": new_id,
        "item": items[new_id]
    }


@app.put("/items/{item_id}")
def update_item(item_id: int, item: Item):
    if item_id not in items:
        raise HTTPException(status_code=404, detail="Item not found")

    items[item_id] = item.model_dump()

    return {
        "id": item_id,
        "item": items[item_id]
    }


@app.delete("/items/{item_id}")
def delete_item(item_id: int):
    if item_id not in items:
        raise HTTPException(status_code=404, detail="Item not found")

    deleted_item = items.pop(item_id)

    return {
        "message": "Item deleted",
        "item": deleted_item
    }

서버 실행 명령어는 다음과 같습니다.

uvicorn main:app --reload

Swagger UI에서 테스트하기

FastAPI의 편한 점 중 하나는 API 문서가 자동으로 생성된다는 점입니다.

서버를 실행한 뒤 아래 주소로 접속합니다.

http://127.0.0.1:8000/docs

그러면 Swagger UI 화면이 열립니다.

여기서 직접 GET, POST, PUT, DELETE 요청을 테스트할 수 있습니다.

초보자 입장에서는 Postman 같은 별도 도구 없이도 API 요청을 바로 테스트할 수 있어서 실습하기 좋습니다.

테스트 순서 추천

처음 실습할 때는 아래 순서대로 테스트해 보면 흐름이 잘 보입니다.

GET /items로 전체 상품 조회
GET /items/1로 특정 상품 조회
POST /items로 새 상품 생성
다시 GET /items로 상품이 추가됐는지 확인
PUT /items/1로 상품 수정
DELETE /items/2로 상품 삭제
다시 GET /items로 삭제 결과 확인

이 순서대로 해보면 CRUD가 단순히 코드 조각이 아니라 하나의 데이터 흐름이라는 점이 보입니다.

이 예제에서 주의할 점

이번 예제는 CRUD API 구조를 이해하기 위한 입문용 코드입니다.

실제 서비스 코드와는 차이가 있습니다.

첫째, 데이터가 메모리에 저장됩니다.
서버를 재시작하면 데이터가 초기화됩니다.

둘째, ID 생성 방식이 단순합니다.
max(items.keys()) + 1 방식은 혼자 실습할 때는 괜찮지만, 여러 요청이 동시에 들어오는 실제 서비스에서는 적절하지 않습니다.

셋째, 인증과 권한 검사가 없습니다.
실제 서비스에서는 아무나 상품을 생성하거나 삭제하면 안 됩니다.

넷째, 데이터베이스 연결이 없습니다.
운영 환경에서는 SQLite, PostgreSQL, MySQL 같은 데이터베이스와 연결해야 합니다.

그래도 입문 단계에서는 이 방식이 더 낫습니다.
처음부터 데이터베이스, 세션, ORM까지 같이 넣으면 CRUD의 핵심 흐름이 흐려질 수 있기 때문입니다.

마무리

FastAPI CRUD API의 기본 흐름은 복잡하지 않습니다.

GET으로 조회한다
POST로 생성한다
PUT으로 수정한다
DELETE로 삭제한다

이 네 가지 구조만 제대로 이해해도 API 설계의 기본 뼈대는 잡을 수 있습니다.

다음 단계로 넘어간다면 같은 예제를 SQLite나 SQLModel과 연결해 보는 것이 좋습니다.
그때부터는 서버를 재시작해도 데이터가 유지되고, 실제 백엔드 프로젝트에 가까운 구조로 확장할 수 있습니다.

FastAPI SQLite 연결하기: SQLModel로 DB 저장 API 만들기

notebase — Tue, 26 May 2026 17:45:01 +0900

FastAPI에서 SQLite를 연결하는 방법을 SQLModel 기준으로 정리합니다. 최신 lifespan 방식으로 테이블을 생성하고, 데이터 저장·조회·삭제 API까지 초보자도 따라 할 수 있게 설명합니다.

FastAPI SQLite 연결은 API가 받은 데이터를 메모리에만 두지 않고 실제 DB 파일에 저장하는 첫 단계입니다. 입문 단계에서는 별도 DB 서버가 필요 없는 SQLite로 시작하면 구조를 이해하기 쉽습니다.

FastAPI에서 데이터베이스를 연결하는 방법은 여러 가지입니다.
SQLAlchemy를 직접 써도 되고, 비동기 DB 라이브러리를 써도 됩니다.

다만 처음 배우는 단계라면 SQLModel을 사용하는 방식이 편합니다. SQLModel은 Pydantic과 SQLAlchemy를 기반으로 만들어진 라이브러리라서, FastAPI의 요청·응답 모델과 DB 테이블 모델을 비슷한 문법으로 다룰 수 있습니다.

여기서는 2026년 5월 기준 FastAPI 공식 문서 흐름에 맞춰 FastAPI + SQLite + SQLModel 조합으로 간단한 메모 API를 만들어봅니다.

중요한 변경점도 하나 있습니다. 예전 FastAPI 예제에서는 @app.on_event("startup")을 자주 사용했지만, 현재는 앱 시작과 종료 시 실행할 작업을 lifespan으로 처리하는 방식이 권장됩니다. 이 글도 새로 작성하는 코드에 맞춰 lifespan 기준으로 설명합니다.

FastAPI에서 SQLite를 연결한다는 뜻

FastAPI만 사용하면 보통 이런 식으로 데이터를 다룹니다.

items = []

리스트나 딕셔너리에 데이터를 넣는 방식입니다.

이 방식은 테스트할 때는 편하지만 문제가 있습니다.
서버를 껐다 켜면 데이터가 사라집니다.

SQLite를 연결하면 데이터가 .db 파일에 저장됩니다.

예를 들어 아래처럼 파일이 생깁니다.

app.db

이 파일 안에 테이블이 만들어지고, API로 등록한 데이터가 저장됩니다.

흐름으로 보면 아래와 같습니다.

API 요청
↓
FastAPI 라우터
↓
SQLModel Session
↓
SQLite DB 파일

여기서 Session은 FastAPI 코드와 데이터베이스 사이에서 실제 저장, 조회, 삭제 작업을 처리하는 통로라고 보면 됩니다.

SQLite를 처음 DB로 쓰기 좋은 이유

SQLite는 별도 서버 설치가 필요 없습니다.

MySQL이나 PostgreSQL은 DB 서버를 실행하고, 계정과 비밀번호를 만들고, 포트 설정도 해야 합니다.
반면 SQLite는 파일 하나로 동작합니다.

그래서 FastAPI 입문 단계에서는 SQLite가 적당합니다.

SQLite
- 별도 DB 서버 설치 필요 없음
- 로컬 실습에 적합
- 작은 프로젝트나 테스트용으로 편함
- 파일 기반 DB라 구조를 이해하기 쉬움

물론 모든 서비스에 SQLite가 맞는 것은 아닙니다.
동시에 많은 사용자가 쓰는 서비스, 복잡한 운영 환경, 대규모 트래픽이 필요한 서비스라면 PostgreSQL이나 MySQL을 고려하는 게 일반적입니다.

하지만 FastAPI에서 DB 연결 구조를 처음 익히는 목적이라면 SQLite로 충분합니다.

SQLModel을 사용하는 이유

FastAPI를 배우다 보면 이런 이름들을 자주 보게 됩니다.

Pydantic
SQLAlchemy
SQLModel

처음에는 헷갈릴 수 있습니다.

간단히 나누면 이렇습니다.

도구	역할
Pydantic	API 요청/응답 데이터 검증
SQLAlchemy	파이썬에서 SQL DB를 다루는 ORM
SQLModel	Pydantic + SQLAlchemy를 FastAPI에 맞게 쉽게 사용하도록 만든 도구

여기서 중요한 점은 SQLModel이 완전히 새로운 DB 기술은 아니라는 것입니다.
SQLModel은 SQLAlchemy와 Pydantic 위에서 동작합니다.

입문자 입장에서는 장점이 큽니다.

DB 테이블 모델과 API 데이터 모델을 비슷한 문법으로 작성할 수 있기 때문입니다.
처음부터 SQLAlchemy의 모든 개념을 깊게 들어가기보다, FastAPI에서 DB가 연결되는 흐름을 먼저 익히기에 좋습니다.

프로젝트 구조 만들기

먼저 프로젝트 폴더를 하나 만듭니다.

mkdir fastapi-sqlite-example
cd fastapi-sqlite-example

가상환경을 만듭니다.

python -m venv .venv

macOS 또는 Linux라면 아래 명령어로 활성화합니다.

source .venv/bin/activate

Windows PowerShell이라면 아래처럼 실행합니다.

.venv\Scripts\Activate.ps1

파일 구조는 단순하게 시작합니다.

fastapi-sqlite-example/
├─ main.py
└─ app.db   # 실행 후 자동 생성

처음부터 폴더를 여러 개로 나누면 오히려 흐름이 안 보일 수 있습니다.
DB 연결 구조를 익힌 뒤에 database.py, models.py, routers/로 나누는 편이 낫습니다.

필요한 패키지 설치하기

FastAPI, Uvicorn, SQLModel을 설치합니다.

pip install fastapi "uvicorn[standard]" sqlmodel

각 패키지의 역할은 아래와 같습니다.

패키지	역할
fastapi	API 서버 프레임워크
uvicorn	FastAPI 앱을 실행하는 ASGI 서버
sqlmodel	SQLite 같은 SQL DB를 파이썬 모델로 다루는 도구

설치가 끝났다면 main.py 파일을 만듭니다.

SQLite 연결 코드 작성하기

먼저 가장 기본적인 DB 연결 코드를 작성합니다.

# main.py

from fastapi import FastAPI
from sqlmodel import SQLModel, Field, Session, create_engine

sqlite_file_name = "app.db"
sqlite_url = f"sqlite:///{sqlite_file_name}"

engine = create_engine(sqlite_url, echo=True)

app = FastAPI()

여기서 핵심은 이 부분입니다.

sqlite_url = f"sqlite:///{sqlite_file_name}"

sqlite:///app.db는 현재 프로젝트 폴더에 app.db라는 SQLite 파일을 사용하겠다는 뜻입니다.

그리고 이 코드는 DB 연결 엔진을 만듭니다.

engine = create_engine(sqlite_url, echo=True)

echo=True를 넣으면 SQLModel이 내부적으로 실행하는 SQL 문이 터미널에 출력됩니다.

입문 단계에서는 켜두는 것이 좋습니다.
API를 호출했을 때 어떤 SQL이 실행되는지 확인할 수 있기 때문입니다.

실제 운영 환경에서는 로그가 너무 많아질 수 있으므로 상황에 따라 끕니다.

engine = create_engine(sqlite_url, echo=False)

데이터 모델 만들기

이제 DB에 저장할 모델을 만듭니다.

여기서는 간단한 메모 API를 예시로 사용합니다.

# main.py

from fastapi import FastAPI
from sqlmodel import SQLModel, Field, Session, create_engine


sqlite_file_name = "app.db"
sqlite_url = f"sqlite:///{sqlite_file_name}"

engine = create_engine(sqlite_url, echo=True)

app = FastAPI()


class Memo(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    title: str
    content: str

이 클래스가 SQLite의 테이블이 됩니다.

class Memo(SQLModel, table=True):

table=True가 붙어 있기 때문에 SQLModel은 이 클래스를 DB 테이블로 인식합니다.

각 필드는 테이블의 컬럼이 됩니다.

id: int | None = Field(default=None, primary_key=True)
title: str
content: str

의미는 아래와 같습니다.

필드	설명
id	메모 고유 번호
title	메모 제목
content	메모 내용

id는 처음 생성할 때 직접 넣지 않아도 됩니다.
SQLite가 자동으로 값을 만들 수 있도록 default=None으로 둡니다.

앱 시작 시 테이블 생성하기

모델만 작성한다고 실제 DB 테이블이 생기지는 않습니다.

테이블을 만들려면 아래 코드가 필요합니다.

def create_db_and_tables():
    SQLModel.metadata.create_all(engine)

SQLModel.metadata.create_all(engine)은 지금까지 table=True로 정의한 모델을 기준으로 DB 테이블을 생성합니다.

이미 테이블이 있다면 매번 새로 덮어쓰는 것은 아닙니다.
없는 테이블을 만들어주는 역할에 가깝습니다.

이 작업은 앱이 시작될 때 한 번 실행되면 됩니다.

`lifespan`으로 시작 작업 등록하기

예전 FastAPI 예제에서는 아래와 같은 코드를 자주 볼 수 있습니다.

@app.on_event("startup")
def on_startup():
    create_db_and_tables()

하지만 새로 작성하는 코드라면 lifespan 방식으로 익혀두는 편이 좋습니다.
앱 시작 시 실행할 작업은 yield 위에 작성하고, 앱 종료 시 실행할 작업은 yield 아래에 작성합니다.

from contextlib import asynccontextmanager

@asynccontextmanager
async def lifespan(app: FastAPI):
    create_db_and_tables()
    yield

app = FastAPI(lifespan=lifespan)

여기서는 서버가 시작될 때 SQLite 테이블을 생성해야 하므로 create_db_and_tables()를 yield 위에 둡니다.

정리하면 이 단계까지의 코드는 아래와 같습니다.

# main.py

from contextlib import asynccontextmanager

from fastapi import FastAPI
from sqlmodel import SQLModel, Field, Session, create_engine


sqlite_file_name = "app.db"
sqlite_url = f"sqlite:///{sqlite_file_name}"

engine = create_engine(sqlite_url, echo=True)


class Memo(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    title: str
    content: str


def create_db_and_tables():
    SQLModel.metadata.create_all(engine)


@asynccontextmanager
async def lifespan(app: FastAPI):
    create_db_and_tables()
    yield


app = FastAPI(lifespan=lifespan)

이 상태로 서버를 실행하면 app.db 파일이 생성됩니다.

uvicorn main:app --reload

다만 아직 API 엔드포인트가 없기 때문에 저장이나 조회는 할 수 없습니다.
이제 데이터를 등록하는 API를 추가해봅니다.

데이터 저장 API 만들기

메모를 저장하는 POST API를 추가합니다.

@app.post("/memos/")
def create_memo(memo: Memo):
    with Session(engine) as session:
        session.add(memo)
        session.commit()
        session.refresh(memo)
        return memo

여기서 가장 중요한 부분은 Session, commit(), refresh()입니다.

with Session(engine) as session:

Session(engine)은 DB와 대화하기 위한 작업 단위를 만듭니다.

session.add(memo)

session.add(memo)는 저장할 객체를 세션에 추가합니다.
아직 DB 파일에 최종 저장된 상태는 아닙니다.

session.commit()

중요한 부분은 session.commit()입니다.
이 코드를 실행해야 변경 내용이 실제 DB에 반영됩니다.

session.refresh(memo)

session.refresh(memo)는 DB에 저장된 최신 값을 다시 가져옵니다.
특히 id처럼 DB가 자동으로 만든 값을 응답에 포함하려면 이 과정이 필요합니다.

전체 코드는 아래처럼 됩니다.

# main.py

from contextlib import asynccontextmanager

from fastapi import FastAPI
from sqlmodel import SQLModel, Field, Session, create_engine


sqlite_file_name = "app.db"
sqlite_url = f"sqlite:///{sqlite_file_name}"

engine = create_engine(sqlite_url, echo=True)


class Memo(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    title: str
    content: str


def create_db_and_tables():
    SQLModel.metadata.create_all(engine)


@asynccontextmanager
async def lifespan(app: FastAPI):
    create_db_and_tables()
    yield


app = FastAPI(lifespan=lifespan)


@app.post("/memos/")
def create_memo(memo: Memo):
    with Session(engine) as session:
        session.add(memo)
        session.commit()
        session.refresh(memo)
        return memo

데이터 조회 API 만들기

저장한 메모 목록을 조회하는 API도 추가합니다.

SQLModel에서는 select()를 사용해 데이터를 조회할 수 있습니다.

from sqlmodel import select

상단 import를 수정합니다.

from sqlmodel import SQLModel, Field, Session, create_engine, select

그리고 조회 API를 추가합니다.

@app.get("/memos/")
def read_memos():
    with Session(engine) as session:
        statement = select(Memo)
        memos = session.exec(statement).all()
        return memos

전체 코드는 아래와 같습니다.

# main.py

from contextlib import asynccontextmanager

from fastapi import FastAPI
from sqlmodel import SQLModel, Field, Session, create_engine, select


sqlite_file_name = "app.db"
sqlite_url = f"sqlite:///{sqlite_file_name}"

engine = create_engine(sqlite_url, echo=True)


class Memo(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    title: str
    content: str


def create_db_and_tables():
    SQLModel.metadata.create_all(engine)


@asynccontextmanager
async def lifespan(app: FastAPI):
    create_db_and_tables()
    yield


app = FastAPI(lifespan=lifespan)


@app.post("/memos/")
def create_memo(memo: Memo):
    with Session(engine) as session:
        session.add(memo)
        session.commit()
        session.refresh(memo)
        return memo


@app.get("/memos/")
def read_memos():
    with Session(engine) as session:
        statement = select(Memo)
        memos = session.exec(statement).all()
        return memos

이제 메모를 저장하고 다시 조회할 수 있습니다.

단일 메모 조회 API 추가하기

목록 조회만 있으면 조금 아쉽습니다.

이번에는 id로 하나의 메모만 조회하는 API를 추가합니다.

from fastapi import FastAPI, HTTPException

상단 import를 수정합니다.

from fastapi import FastAPI, HTTPException
from sqlmodel import SQLModel, Field, Session, create_engine, select

그리고 아래 코드를 추가합니다.

@app.get("/memos/{memo_id}")
def read_memo(memo_id: int):
    with Session(engine) as session:
        memo = session.get(Memo, memo_id)

        if memo is None:
            raise HTTPException(status_code=404, detail="Memo not found")

        return memo

session.get(Memo, memo_id)는 기본키 기준으로 데이터를 찾습니다.

데이터가 없으면 None이 반환됩니다.
이때 단순히 빈 값을 반환하기보다 404 Not Found를 보내는 편이 API답습니다.

삭제 API 추가하기

메모를 삭제하는 API도 만들어봅니다.

@app.delete("/memos/{memo_id}")
def delete_memo(memo_id: int):
    with Session(engine) as session:
        memo = session.get(Memo, memo_id)

        if memo is None:
            raise HTTPException(status_code=404, detail="Memo not found")

        session.delete(memo)
        session.commit()

        return {"message": "Memo deleted"}

삭제 흐름은 단순합니다.

id로 메모를 찾습니다.
없으면 404를 반환합니다.
있으면 삭제합니다.
session.commit()으로 DB에 반영합니다.

최종 코드

여기까지 합치면 최종 코드는 아래와 같습니다.

코드만 복사해서 실행해도 흐름을 이해할 수 있도록 주요 구간마다 주석을 넣었습니다.

# main.py

from contextlib import asynccontextmanager

from fastapi import FastAPI, HTTPException
from sqlmodel import SQLModel, Field, Session, create_engine, select


# 1. SQLite DB 연결 설정
sqlite_file_name = "app.db"
sqlite_url = f"sqlite:///{sqlite_file_name}"
engine = create_engine(sqlite_url, echo=True)


# 2. DB 테이블 모델 정의
class Memo(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    title: str
    content: str


# 3. 앱 시작 시 DB 테이블 생성
def create_db_and_tables():
    SQLModel.metadata.create_all(engine)


@asynccontextmanager
async def lifespan(app: FastAPI):
    create_db_and_tables()
    yield


app = FastAPI(lifespan=lifespan)


# 4. 메모 생성 API
@app.post("/memos/")
def create_memo(memo: Memo):
    with Session(engine) as session:
        session.add(memo)
        session.commit()
        session.refresh(memo)
        return memo


# 5. 메모 목록 조회 API
@app.get("/memos/")
def read_memos():
    with Session(engine) as session:
        statement = select(Memo)
        memos = session.exec(statement).all()
        return memos


# 6. 단일 메모 조회 API
@app.get("/memos/{memo_id}")
def read_memo(memo_id: int):
    with Session(engine) as session:
        memo = session.get(Memo, memo_id)

        if memo is None:
            raise HTTPException(status_code=404, detail="Memo not found")

        return memo


# 7. 메모 삭제 API
@app.delete("/memos/{memo_id}")
def delete_memo(memo_id: int):
    with Session(engine) as session:
        memo = session.get(Memo, memo_id)

        if memo is None:
            raise HTTPException(status_code=404, detail="Memo not found")

        session.delete(memo)
        session.commit()

        return {"message": "Memo deleted"}

이 코드만으로도 간단한 SQLite 기반 메모 API가 동작합니다.

서버 실행하기

터미널에서 실행합니다.

uvicorn main:app --reload

또는 FastAPI CLI를 사용한다면 아래처럼 실행할 수도 있습니다.

fastapi dev main.py

실행 후 브라우저에서 Swagger 문서에 접속합니다.

http://127.0.0.1:8000/docs

FastAPI는 자동으로 API 문서를 생성해줍니다.
여기서 POST /memos/, GET /memos/, GET /memos/{memo_id}, DELETE /memos/{memo_id}를 직접 테스트할 수 있습니다.

Swagger에서 메모 저장 테스트하기

POST /memos/를 열고 Try it out을 누릅니다.

요청 Body에 아래처럼 입력합니다.

{
  "title": "FastAPI SQLite 연습",
  "content": "SQLModel을 사용해서 SQLite에 데이터를 저장해본다."
}

응답은 대략 이런 형태로 나옵니다.

{
  "id": 1,
  "title": "FastAPI SQLite 연습",
  "content": "SQLModel을 사용해서 SQLite에 데이터를 저장해본다."
}

여기서 id는 직접 입력하지 않았지만 DB 저장 후 자동으로 생성됩니다.

그다음 GET /memos/를 실행하면 저장된 데이터가 목록으로 나옵니다.

[
  {
    "id": 1,
    "title": "FastAPI SQLite 연습",
    "content": "SQLModel을 사용해서 SQLite에 데이터를 저장해본다."
  }
]

서버를 껐다 켜도 app.db 파일이 남아 있다면 데이터도 유지됩니다.

자주 헷갈리는 부분

1. `app.db` 파일이 안 보일 때

서버를 실행하기 전에는 app.db 파일이 없을 수 있습니다.

이 파일은 아래 코드가 실행되면서 생성됩니다.

SQLModel.metadata.create_all(engine)

즉, 서버를 한 번 실행한 뒤 프로젝트 폴더를 확인해보면 됩니다.

2. `session.commit()`을 안 하면 저장되지 않는다

아래 코드만 쓰면 DB에 바로 저장되는 것처럼 보일 수 있습니다.

session.add(memo)

하지만 실제 반영은 session.commit()에서 일어납니다.

session.commit()

입문 단계에서 자주 하는 실수가 add()만 하고 commit()을 빼먹는 것입니다.

3. `session.refresh()`는 왜 필요할까?

session.refresh(memo)

이 코드는 DB에 저장된 최신 상태를 다시 가져옵니다.

특히 id처럼 DB가 자동으로 만든 값은 저장 전에는 알 수 없습니다.
session.refresh(memo)를 호출하면 방금 저장된 데이터의 id까지 포함해서 응답할 수 있습니다.

4. `lifespan`에서 `yield`는 왜 필요할까?

lifespan은 앱의 시작과 종료 흐름을 하나의 함수에서 다룹니다.

@asynccontextmanager
async def lifespan(app: FastAPI):
    create_db_and_tables()
    yield

yield 위쪽은 앱이 시작될 때 실행됩니다.
yield 아래쪽은 앱이 종료될 때 실행됩니다.

이 예제에서는 종료 시 따로 처리할 작업이 없기 때문에 yield 아래에는 아무 코드도 작성하지 않았습니다.

5. SQLite 파일을 지우면 데이터도 사라진다

SQLite는 파일 기반 DB입니다.

이 예제에서는 데이터가 app.db에 저장됩니다.

따라서 app.db 파일을 삭제하면 테이블과 데이터도 함께 사라집니다.
실습 중 DB 상태가 꼬였을 때는 파일을 지우고 다시 실행하는 방식으로 초기화할 수 있습니다.

단, 실제 중요한 데이터가 들어 있는 DB 파일은 함부로 삭제하면 안 됩니다.

SQLite를 계속 써도 되는 경우

SQLite는 단순 실습용으로만 쓰는 도구는 아닙니다.
작은 규모의 앱이나 로컬 도구에서는 충분히 유용합니다.

아래 상황이라면 SQLite로 시작해도 괜찮습니다.

- FastAPI DB 연결을 처음 배우는 경우
- 개인 프로젝트를 만드는 경우
- 로컬에서만 사용하는 자동화 도구를 만드는 경우
- 관리자 한두 명만 쓰는 작은 내부 도구를 만드는 경우
- 테스트용 API 서버를 빠르게 만들고 싶은 경우

반대로 아래 상황이라면 PostgreSQL이나 MySQL 같은 DB를 검토하는 편이 좋습니다.

- 여러 사용자가 동시에 많이 접속하는 서비스
- 운영 서버에서 안정적인 DB 관리가 필요한 경우
- 사용자 계정, 결제, 권한 같은 중요한 데이터를 다루는 경우
- 배포 환경에서 DB 백업과 마이그레이션이 중요한 경우

여기서 중요한 점은 SQLite가 나쁘다는 뜻이 아닙니다.
역할이 다를 뿐입니다.

FastAPI 입문 단계에서는 SQLite가 구조를 이해하기 좋고, 운영 서비스로 갈수록 더 강한 DB 관리 기능이 필요해집니다.

마무리

FastAPI에서 SQLite를 연결할 때 핵심은 세 가지입니다.

첫째, create_engine()으로 SQLite DB 파일과 연결합니다.
둘째, SQLModel 클래스로 테이블 구조를 만듭니다.
셋째, Session을 통해 데이터를 저장하고 조회합니다.

그리고 새로 작성하는 FastAPI 코드라면 앱 시작 작업은 @app.on_event("startup")보다 lifespan 방식으로 익혀두는 편이 좋습니다.

처음부터 PostgreSQL, Alembic, 비동기 DB 세션까지 한 번에 넣으면 구조가 흐려질 수 있습니다.
먼저 SQLite로 저장과 조회 흐름을 손에 익히고, 그다음 실제 서비스 구조로 넘어가는 편이 더 안정적입니다.

개인정보처리방침

notebase — Tue, 26 May 2026 16:10:03 +0900

Notebase는 이용자의 개인정보를 중요하게 생각하며, 개인정보 보호 관련 법령을 준수하기 위해 다음과 같은 개인정보처리방침을 운영합니다.

본 개인정보처리방침은 2026년 5월 20일부터 적용됩니다.

1. 개인정보의 수집 항목 및 수집 방법

본 블로그는 다음과 같은 정보를 수집할 수 있습니다.

- 수집 항목: 방문 일시, 브라우저 정보, 접속 IP, 쿠키, 기기 정보
- 수집 방법: Google Analytics, Google AdSense, 티스토리 통계 등 외부 서비스 및 블로그 운영 도구를 통한 자동 수집

2. 개인정보의 수집 및 이용 목적

수집된 정보는 다음의 목적을 위해 활용됩니다.

- 방문자 통계 분석
- 블로그 콘텐츠 및 사용자 경험 개선
- Google AdSense 등을 통한 광고 게재 및 맞춤형 광고 제공
- 블로그 운영 및 보안 관리를 위한 참고 자료

3. 개인정보의 보유 및 이용 기간

수집된 정보는 이용 목적 달성 후 지체 없이 파기되며, 관계 법령 또는 이용 중인 외부 서비스의 정책에 따라 일정 기간 보관될 수 있습니다.

4. 개인정보의 제3자 제공

본 블로그는 원칙적으로 이용자의 개인정보를 외부에 제공하지 않습니다.

다만, 다음의 경우에는 예외로 합니다.

- Google 등 광고 및 통계 서비스 제공자와의 광고 게재, 통계 분석, 서비스 개선 목적
- 법령에 따라 제공이 요구되거나 수사기관의 적법한 요청이 있는 경우

5. 쿠키 사용 및 거부

본 블로그는 방문자 통계 분석, 맞춤형 광고 제공, 사용자 경험 개선을 위해 쿠키를 사용할 수 있습니다.

Google을 포함한 제3자 광고 사업자는 사용자의 이전 방문 기록을 바탕으로 광고를 제공하기 위해 쿠키를 사용할 수 있습니다.

사용자는 브라우저 설정을 통해 쿠키 저장을 거부하거나 삭제할 수 있습니다. 단, 쿠키 저장을 거부할 경우 일부 서비스 이용에 제한이 있을 수 있습니다.

쿠키 설정 거부 방법 예시(Chrome 기준):

설정 > 개인정보 및 보안 > 서드 파티 쿠키 > 서드 파티 쿠키 차단

또한 사용자는 Google 광고 설정 페이지에서 개인 맞춤 광고를 관리하거나 거부할 수 있습니다.

6. 개인정보 보호 책임자

- 책임자: notebase
- 이메일: harperthebest222@gmail.com
- 문의 사항은 가능한 한 신속하고 성실하게 답변하겠습니다.

7. 개인정보처리방침의 변경

본 개인정보처리방침은 관련 법령, 서비스 정책 또는 블로그 운영 방침에 따라 변경될 수 있으며, 변경 시 본 블로그를 통해 공지합니다.

본 개인정보처리방침은 2026년 5월 20일부터 적용됩니다.

FastAPI Swagger 문서 자동 생성, `/docs` 화면이 만들어지는 원리

notebase — Tue, 26 May 2026 14:49:57 +0900

FastAPI에서 Swagger UI 문서가 자동으로 생성되는 원리를 초보자도 이해하기 쉽게 정리했습니다. /docs, /redoc, /openapi.json의 역할과 실제 API 테스트 방법까지 함께 설명합니다.

FastAPI를 실행한 뒤 /docs에 접속하면 API 문서 화면이 자동으로 열립니다. 따로 문서 파일을 만들지 않았는데도 엔드포인트, 요청값, 응답 구조가 정리되어 나오죠. 이 기능이 FastAPI의 Swagger 문서 자동 생성입니다.

처음 보면 꽤 신기합니다.

“내가 한 건 함수 하나 만든 것뿐인데, 왜 문서가 생기지?”

이 부분을 이해하면 FastAPI가 왜 입문자에게도 편하고, 협업용 API 서버를 만들 때 왜 자주 언급되는지 감이 잡힙니다.

2026년 5월 기준 FastAPI 공식 문서에 따르면, FastAPI는 기본적으로 Swagger UI를 /docs에서 제공하고, ReDoc을 /redoc에서 제공합니다. OpenAPI 스키마는 기본적으로 /openapi.json에서 확인할 수 있습니다.

FastAPI에서 Swagger 문서가 자동으로 생긴다는 뜻

API 문서는 보통 이런 내용을 담습니다.

어떤 주소로 요청해야 하는지
GET, POST 같은 HTTP 메서드는 무엇인지
요청할 때 어떤 값을 보내야 하는지
응답은 어떤 형태로 돌아오는지
에러가 발생하면 어떤 상태 코드가 나오는지

FastAPI는 이 정보를 코드에서 읽어 자동으로 문서를 만듭니다.

예를 들어 아래와 같은 코드가 있다고 해보겠습니다.

main.py

from fastapi import FastAPI

app = FastAPI()


@app.get("/hello")
def read_hello():
    return {"message": "Hello FastAPI"}

여기서 FastAPI는 다음 정보를 알 수 있습니다.

@app.get("/hello")를 보고 /hello라는 GET API가 있다는 것을 압니다.

read_hello() 함수가 이 API를 처리한다는 것도 압니다.

그리고 반환값을 통해 이 API가 어떤 응답을 줄 수 있는지 문서에 표시할 수 있습니다.

물론 단순한 예제에서는 정보가 많지 않습니다. 하지만 타입 힌트와 Pydantic 모델을 함께 사용하면 문서가 훨씬 구체적으로 만들어집니다.

Swagger UI는 어디에서 확인할 수 있을까

FastAPI 앱을 실행하면 기본적으로 아래 주소에서 Swagger UI를 볼 수 있습니다.

http://127.0.0.1:8000/docs

개발 서버를 실행하는 명령어는 보통 아래처럼 사용합니다.

fastapi dev main.py

또는 Uvicorn을 직접 사용한다면 이렇게 실행할 수 있습니다.

uvicorn main:app --reload

실행 후 브라우저에서 /docs에 접속하면 API 목록이 자동으로 정리된 화면이 나옵니다.

여기서 끝이 아닙니다.

Swagger UI는 단순히 읽기만 하는 문서가 아닙니다. 화면에서 바로 API 요청을 보내고 응답을 확인할 수 있습니다.

입문자 입장에서는 Postman 같은 별도 도구 없이도 API를 테스트할 수 있어서 꽤 편합니다.

FastAPI가 문서를 자동으로 만드는 원리

FastAPI의 자동 문서 생성은 크게 세 가지 요소를 바탕으로 동작합니다.

첫 번째는 라우터 정보입니다.

@app.get("/items")

이 코드를 보면 FastAPI는 /items라는 주소와 GET 메서드를 문서에 추가합니다.

두 번째는 타입 힌트입니다.

@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id}

여기서 item_id: int라고 적으면 FastAPI는 item_id가 정수여야 한다는 것을 압니다.

그래서 Swagger UI 문서에도 item_id가 integer 타입으로 표시됩니다.

세 번째는 Pydantic 모델입니다.

from pydantic import BaseModel


class Item(BaseModel):
    name: str
    price: int

이런 모델을 요청 본문에 사용하면, Swagger UI는 name과 price가 필요한 값이라는 것을 문서에 보여줍니다.

즉, FastAPI 문서는 별도의 문서 작성 도구가 아니라 코드 구조를 바탕으로 자동 생성되는 API 명세에 가깝습니다.

직접 확인해보는 간단한 예제

아래 예제를 main.py 파일에 작성해보겠습니다.

main.py

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class ItemCreate(BaseModel):
    name: str
    price: int
    description: str | None = None


@app.get("/")
def read_root():
    return {"message": "FastAPI 문서 자동 생성 예제입니다."}


@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {
        "item_id": item_id,
        "name": "keyboard",
        "price": 30000,
    }


@app.post("/items")
def create_item(item: ItemCreate):
    return {
        "message": "상품이 생성되었습니다.",
        "item": item,
    }

서버를 실행합니다.

fastapi dev main.py

브라우저에서 아래 주소로 접속합니다.

http://127.0.0.1:8000/docs

그러면 Swagger UI 화면에 API가 세 개 보입니다.

GET /
GET /items/{item_id}
POST /items

여기서 중요한 부분은 POST /items입니다.

ItemCreate 모델에 작성한 name, price, description 필드가 Swagger UI에 자동으로 표시됩니다.

코드에 타입을 잘 적어두면 문서도 그만큼 정확해집니다.

요청값과 응답값이 문서에 표시되는 방식

FastAPI에서 문서 품질을 높이려면 타입 힌트를 대충 쓰면 안 됩니다.

예를 들어 아래 코드는 문서 입장에서 정보가 부족합니다.

@app.post("/items")
def create_item(item):
    return item

item이 어떤 구조인지 알 수 없기 때문입니다.

반면 아래처럼 Pydantic 모델을 사용하면 문서가 훨씬 명확해집니다.

from pydantic import BaseModel


class ItemCreate(BaseModel):
    name: str
    price: int
    description: str | None = None

이 모델을 API에 연결하면 FastAPI는 다음 내용을 문서에 반영합니다.

필드	타입	필수 여부
name	string	필수
price	integer	필수
description	string 또는 null	선택

여기서 description: str | None = None은 초보자가 자주 헷갈리는 부분입니다.

str | None은 “문자열이거나 None일 수 있다”는 뜻입니다.

뒤의 = None은 “값을 보내지 않아도 된다”는 기본값입니다.

즉, 이 필드는 선택값으로 문서에 표시됩니다.

`Field()`로 문서 설명과 예시 추가하기

자동 생성된 문서를 조금 더 친절하게 만들고 싶다면 Pydantic의 Field()를 사용할 수 있습니다.

타입만 적으면 Swagger UI에 필드 이름과 타입 중심으로 표시됩니다. 여기에 description이나 examples를 넣으면 문서 화면에서 해당 필드가 어떤 값인지 더 쉽게 이해할 수 있습니다.

main.py

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()


class ItemCreate(BaseModel):
    name: str = Field(
        description="상품의 이름입니다.",
        examples=["무선 마우스"],
    )
    price: int = Field(
        description="상품의 가격(원)입니다.",
        examples=[15000],
    )
    description: str | None = Field(
        default=None,
        description="상품 설명입니다.",
        examples=["블루투스 연결을 지원하는 무선 마우스"],
    )


@app.post("/items")
def create_item(item: ItemCreate):
    return {
        "message": "상품이 생성되었습니다.",
        "item": item,
    }

이렇게 작성하면 Swagger UI에서 각 필드의 설명과 예시를 함께 확인할 수 있습니다.

여기서 default=None은 이 필드가 선택값이라는 뜻입니다. 앞에서 봤던 description: str | None = None과 같은 역할을 하지만, Field()를 사용할 때는 기본값과 설명을 한곳에 묶어 적을 수 있습니다.

실제로는 이 차이가 협업할 때 꽤 큽니다.

프론트엔드 개발자나 API를 사용하는 사람이 문서를 봤을 때 “이 값에 뭘 넣어야 하지?”라고 덜 헷갈리기 때문입니다.

다만 처음부터 모든 필드에 설명을 길게 붙일 필요는 없습니다. 외부에 공유되는 API이거나, 이름만 보고 의미를 알기 어려운 필드부터 설명을 추가하는 정도면 충분합니다.

쿼리 파라미터나 경로 파라미터 설명을 더 자세히 넣고 싶다면 FastAPI의 Query(), Path()를 사용할 수도 있습니다. 이 글에서는 Swagger 문서 자동 생성 흐름이 핵심이므로, 여기서는 Pydantic 모델의 Field() 정도만 알아두면 됩니다.

Swagger UI에서 API를 테스트하는 방법

Swagger UI의 장점은 문서 화면에서 바로 API를 실행해볼 수 있다는 점입니다.

예를 들어 POST /items를 테스트하려면 아래 순서로 진행하면 됩니다.

/docs 화면에서 POST /items를 클릭합니다.
Try it out 버튼을 누릅니다.
요청 본문에 JSON 값을 입력합니다.
Execute 버튼을 누릅니다.
응답 코드와 응답 본문을 확인합니다.

예시 요청값은 아래처럼 넣을 수 있습니다.

{
  "name": "mouse",
  "price": 15000,
  "description": "무선 마우스"
}

실행하면 응답 결과가 화면 아래에 표시됩니다.

이 방식은 API 입문자에게 특히 좋습니다.

코드를 작성하고, 브라우저에서 바로 테스트하고, 응답까지 확인할 수 있기 때문입니다.

`/openapi.json`은 무엇일까

Swagger UI 뒤에는 OpenAPI 스키마가 있습니다.

FastAPI는 기본적으로 아래 주소에서 OpenAPI JSON을 제공합니다.

http://127.0.0.1:8000/openapi.json

이 파일에는 API 구조가 JSON 형태로 정리되어 있습니다.

Swagger UI는 이 JSON 정보를 읽어서 사람이 보기 좋은 문서 화면으로 보여줍니다.

흐름을 단순하게 정리하면 이렇습니다.

FastAPI 코드
→ OpenAPI 스키마 생성
→ /openapi.json 제공
→ Swagger UI가 이 정보를 읽어서 /docs 화면 구성

그래서 Swagger UI는 문서 화면이고, OpenAPI는 문서의 원본 데이터에 가깝다고 보면 됩니다.

FastAPI 공식 문서에서도 기본 OpenAPI 스키마 URL이 /openapi.json이라고 안내합니다. 이 URL은 openapi_url 설정으로 바꿀 수 있고, openapi_url=None으로 설정하면 OpenAPI 스키마와 이를 사용하는 문서 UI가 비활성화됩니다.

ReDoc과 Swagger UI의 차이

FastAPI는 Swagger UI뿐 아니라 ReDoc도 기본으로 제공합니다.

ReDoc은 아래 주소에서 확인할 수 있습니다.

http://127.0.0.1:8000/redoc

둘 다 API 문서를 보여주지만 느낌이 조금 다릅니다.

구분	Swagger UI	ReDoc
기본 주소	`/docs`	`/redoc`
특징	API를 직접 실행해보기 좋음	문서를 읽기 좋게 정리
용도	개발 중 테스트	외부 공유용 문서 확인
입문자 추천	먼저 볼 만함	구조 파악용으로 좋음

개발하면서 API를 직접 눌러보고 테스트하려면 Swagger UI가 편합니다.

반대로 전체 API 구조를 문서처럼 읽고 싶다면 ReDoc이 더 깔끔하게 느껴질 수 있습니다.

문서 제목과 설명 추가하기

기본 문서도 충분히 쓸 수 있지만, 프로젝트 이름과 설명을 넣으면 더 보기 좋아집니다.

main.py

from fastapi import FastAPI

app = FastAPI(
    title="상품 관리 API",
    description="상품 등록, 조회 기능을 제공하는 FastAPI 예제입니다.",
    version="1.0.0",
)

이렇게 작성하면 Swagger UI 상단에 API 제목, 설명, 버전 정보가 표시됩니다.

작은 차이지만 협업할 때는 꽤 중요합니다.

API 문서를 보는 사람이 이 서버가 어떤 역할을 하는지 바로 이해할 수 있기 때문입니다.

문서 주소를 바꾸는 방법

기본 Swagger UI 주소는 /docs입니다.

하지만 프로젝트에 따라 문서 주소를 바꾸고 싶을 수 있습니다.

main.py

from fastapi import FastAPI

app = FastAPI(
    docs_url="/api-docs",
    redoc_url="/api-redoc",
)

이렇게 설정하면 Swagger UI는 아래 주소에서 열립니다.

http://127.0.0.1:8000/api-docs

ReDoc은 아래 주소에서 열립니다.

http://127.0.0.1:8000/api-redoc

FastAPI 공식 문서에서도 Swagger UI 주소는 docs_url, ReDoc 주소는 redoc_url로 설정할 수 있다고 안내합니다. 각각 None으로 설정하면 해당 문서 UI를 끌 수도 있습니다.

운영 환경에서는 문서를 그대로 열어둬도 될까

개발 중에는 /docs가 매우 편합니다.

하지만 운영 환경에서는 한 번 더 생각해야 합니다.

API 문서가 열려 있으면 외부 사용자가 서버의 엔드포인트 구조를 쉽게 볼 수 있습니다. 물론 문서가 열려 있다고 해서 바로 보안 문제가 생기는 것은 아닙니다. 인증과 권한 처리가 제대로 되어 있다면 실제 데이터 접근은 막을 수 있습니다.

다만 내부 관리자 API, 테스트용 API, 아직 공개하면 안 되는 API가 문서에 노출될 수 있습니다.

그래서 운영 환경에서는 보통 아래 중 하나를 선택합니다.

문서 UI를 비활성화한다.
관리자나 내부망에서만 접근 가능하게 제한한다.
공개 가능한 API와 내부 API를 분리한다.
인증이 필요한 API는 보안 스키마를 명확히 설정한다.

문서를 끄고 싶다면 이렇게 작성할 수 있습니다.

main.py

from fastapi import FastAPI

app = FastAPI(
    docs_url=None,
    redoc_url=None,
)

OpenAPI 스키마 자체까지 끄고 싶다면 아래처럼 설정할 수 있습니다.

main.py

from fastapi import FastAPI

app = FastAPI(
    openapi_url=None,
)

이 설정을 하면 /openapi.json이 비활성화되고, 이를 기반으로 동작하는 Swagger UI와 ReDoc도 함께 비활성화됩니다.

문서 자동 생성이 편하려면 코드도 명확해야 한다

FastAPI의 Swagger 문서 자동 생성은 코드를 대신 설명해주는 기능입니다.

하지만 코드 자체가 애매하면 문서도 애매해집니다.

예를 들어 함수 이름, 모델 이름, 필드 이름을 대충 적으면 문서에서도 그대로 보입니다.

class Data(BaseModel):
    a: str
    b: int

이런 모델은 동작은 할 수 있지만, 문서를 보는 사람 입장에서는 a와 b가 무엇인지 알기 어렵습니다.

조금 더 명확하게 작성하는 편이 좋습니다.

class ProductCreate(BaseModel):
    name: str
    price: int

API 함수도 마찬가지입니다.

@app.post("/products")
def create_product(product: ProductCreate):
    return product

이렇게 작성하면 문서만 봐도 “상품을 생성하는 API”라는 느낌이 훨씬 분명해집니다.

FastAPI 문서 자동 생성 기능을 잘 쓰려면 결국 코드의 이름을 잘 짓는 습관이 중요합니다.

입문자가 자주 헷갈리는 부분

`/docs`가 실제 API 주소는 아니다

/docs는 API 테스트와 문서 확인을 위한 화면입니다.

실제 API 주소는 /items, /products, /users처럼 직접 만든 엔드포인트입니다.

Swagger UI가 데이터베이스를 만들어주는 것은 아니다

Swagger UI는 API를 보여주고 테스트하는 화면입니다.

데이터 저장, DB 연결, 로그인 처리 같은 기능은 직접 구현해야 합니다.

타입 힌트를 적으면 검증과 문서화가 함께 좋아진다

FastAPI에서는 타입 힌트가 단순한 메모가 아닙니다.

요청값 검증에도 쓰이고, 문서 자동 생성에도 반영됩니다.

그래서 FastAPI를 배울 때는 타입 힌트를 함께 익히는 편이 좋습니다.

마무리

FastAPI의 Swagger 문서 자동 생성은 단순한 편의 기능이 아닙니다.

API를 만들고, 테스트하고, 다른 사람에게 설명하는 흐름을 하나로 이어주는 기능에 가깝습니다.

입문 단계에서는 /docs에 접속해서 직접 요청을 보내보는 것만으로도 FastAPI 구조를 훨씬 빨리 이해할 수 있습니다.

여기서 중요한 기준은 하나입니다.

문서가 잘 나오게 하려면 코드도 명확해야 합니다.

경로 이름, 함수 이름, 타입 힌트, Pydantic 모델을 신경 써서 작성하면 Swagger UI 문서도 자연스럽게 좋아집니다. FastAPI를 처음 배운다면 API 기능을 하나 만들 때마다 /docs에서 어떻게 보이는지 같이 확인해보는 습관을 들이는 게 좋습니다.

FastAPI Pydantic 모델 기초: 요청 데이터를 검증하는 방법

notebase — Tue, 26 May 2026 09:28:36 +0900

FastAPI에서 Pydantic 모델을 사용하는 이유와 BaseModel 작성법, POST 요청 데이터 검증, Swagger UI 문서 자동 생성 흐름을 초보자 기준으로 정리합니다.

FastAPI Pydantic 모델은 API로 들어오는 JSON 데이터를 정해진 구조로 받고, 타입이 맞는지 자동으로 검증할 때 사용한다. POST 요청을 다루기 시작했다면 거의 반드시 만나게 되는 개념이다.

FastAPI를 처음 배울 때는 보통 이런 코드부터 시작한다.

@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id}

이 단계에서는 URL에 들어온 값을 함수 인자로 받는다.

그런데 회원가입, 게시글 작성, 상품 등록처럼 여러 값을 한 번에 보내야 하는 상황은 다르다.

예를 들어 클라이언트가 이런 데이터를 보낸다고 해보자.

{
  "name": "맥북 파우치",
  "price": 25000,
  "is_active": true
}

이 데이터는 URL 경로에 넣기 어렵다. 보통 HTTP 요청의 본문, 즉 Request Body에 담아서 보낸다.

FastAPI 공식 문서에서도 요청 본문을 선언할 때 Pydantic 모델을 사용한다고 설명한다. FastAPI는 이 모델을 기반으로 데이터 검증과 문서화를 처리한다.

참고: [FastAPI 공식 문서 - Request Body](https://fastapi.tiangolo.com/tutorial/body/)

Pydantic 모델은 무엇인가

Pydantic은 파이썬 타입 힌트를 이용해 데이터 구조를 정의하고, 들어온 데이터가 그 구조에 맞는지 검증하는 라이브러리다.

이 글의 예제는 2026년 5월 기준 FastAPI와 Pydantic v2 문법을 기준으로 작성했다. 오래된 튜토리얼에서 보이는 Pydantic v1 문법이나 에러 메시지 형태와 일부 차이가 있을 수 있다.

FastAPI에서는 Pydantic을 API 요청과 응답 처리에 적극적으로 활용한다.

쉽게 보면 Pydantic 모델은 이런 역할을 한다.

클라이언트가 보낸 JSON
        ↓
Pydantic 모델로 구조 확인
        ↓
타입이 맞으면 FastAPI 함수로 전달
        ↓
타입이 틀리면 자동으로 에러 응답

직접 if price < 0, if name is None 같은 코드를 매번 작성하지 않아도 된다.

여기서 중요한 점은 Pydantic 모델이 단순히 데이터를 담는 그릇이 아니라는 것이다. API가 받을 수 있는 데이터의 모양을 정하고, 잘못된 요청을 함수 실행 전에 걸러내는 기준이 된다.

참고: [Pydantic 공식 문서 - Models](https://pydantic.dev/docs/validation/latest/concepts/models/)

BaseModel로 요청 데이터 구조 만들기

Pydantic 모델은 보통 BaseModel을 상속해서 만든다.

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: int
    is_active: bool

이 코드는 Item이라는 데이터 구조를 만든 것이다.

각 필드는 다음 의미를 가진다.

필드	타입	의미
`name`	`str`	문자열
`price`	`int`	정수
`is_active`	`bool`	참/거짓 값

여기서 중요한 점은 이 모델이 실제로 검증 규칙으로도 사용된다는 것이다.

예를 들어 price에 문자열이 들어오거나, 필수 값인 name이 빠지면 FastAPI가 요청을 정상 처리하지 않고 검증 에러를 반환한다.

POST 요청에서 Pydantic 모델 사용하기

이제 FastAPI 코드에 연결해보자.

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: int
    is_active: bool

@app.post("/items")
def create_item(item: Item):
    return item

핵심은 이 부분이다.

def create_item(item: Item):

item의 타입을 Item으로 지정했기 때문에 FastAPI는 요청 본문을 Item 모델에 맞춰 해석한다.

클라이언트가 아래처럼 요청을 보내면 정상 처리된다.

{
  "name": "맥북 파우치",
  "price": 25000,
  "is_active": true
}

응답은 대략 이렇게 나온다.

{
  "name": "맥북 파우치",
  "price": 25000,
  "is_active": true
}

실제로는 이 데이터를 데이터베이스에 저장하거나, 추가 로직을 거친 뒤 응답하게 된다. 지금은 Pydantic 모델 흐름을 보기 위해 그대로 반환하는 예시다.

Swagger UI에서도 자동으로 보인다

FastAPI의 편한 점은 Pydantic 모델을 작성하면 Swagger UI 문서에도 요청 본문 구조가 자동으로 반영된다는 점이다.

서버를 실행한 뒤 아래 주소로 들어가면 된다.

http://127.0.0.1:8000/docs

POST /items를 열어보면 name, price, is_active 필드가 포함된 요청 예시가 보인다.

이 부분이 입문자에게 꽤 중요하다.

Pydantic 모델을 작성하는 것은 단순히 파이썬 코드 내부에서만 의미가 있는 게 아니다. API를 사용하는 사람에게 “이 API는 이런 JSON을 받는다”는 문서 역할도 같이 한다.

타입 검증은 어떻게 동작할까

다음처럼 잘못된 요청을 보낸다고 해보자.

{
  "name": "맥북 파우치",
  "price": "비쌈",
  "is_active": true
}

price는 int로 선언했는데 문자열 "비쌈"이 들어왔다.

이 경우 FastAPI는 함수를 실행하기 전에 요청을 막고 검증 에러를 반환한다. 개발자가 직접 예외 처리를 작성하지 않아도 된다.

보통 이런 식의 응답을 볼 수 있다.

{
  "detail": [
    {
      "type": "int_parsing",
      "loc": ["body", "price"],
      "msg": "Input should be a valid integer",
      "input": "비쌈"
    }
  ]
}

에러 메시지를 처음 보면 길어 보이지만, 핵심은 간단하다.

body 안의 price 값이 int로 변환될 수 없다

실제로는 이런 검증 실패 응답이 디버깅에 도움이 된다. 어느 위치의 어떤 값이 문제인지 FastAPI가 비교적 구체적으로 알려주기 때문이다.

기본값 넣기

모든 값을 매번 클라이언트가 보내야 하는 것은 아니다.

기본값을 지정할 수도 있다.

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: int
    is_active: bool = True

이제 클라이언트가 is_active를 보내지 않아도 된다.

{
  "name": "맥북 파우치",
  "price": 25000
}

FastAPI는 is_active 값을 자동으로 True로 채운다.

이런 기본값은 게시글의 공개 여부, 상품 활성화 여부, 알림 수신 여부처럼 기본 상태가 정해져 있는 필드에 자주 사용한다.

선택값 처리하기

값이 없을 수도 있는 필드는 None을 허용하도록 작성할 수 있다.

Python 3.10 이상에서는 아래처럼 쓴다.

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: int
    description: str | None = None

Python 3.9 이하 버전까지 고려한다면 Optional을 사용한다.

from typing import Optional
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: int
    description: Optional[str] = None

두 예시는 의미가 거의 같다.

다만 str | None = None은 두 부분으로 나눠서 보는 게 좋다.

코드	의미
`str \	None`	이 필드에는 문자열이 들어올 수도 있고, `None`이 들어올 수도 있다
`= None`	클라이언트가 이 필드를 아예 보내지 않으면 기본값으로 `None`을 넣는다

즉 str | None은 값의 타입을 정하는 부분이고, = None은 필드를 생략했을 때의 기본값을 정하는 부분이다.

초보자가 여기서 자주 헷갈리는 코드가 있다.

description: str | None

이렇게만 쓰면 None은 허용하지만, 필드 자체는 요청에 포함되어야 하는 것으로 해석될 수 있다.

Pydantic v2에서는 “필드가 필수인지 아닌지”를 판단할 때 기본값 유무가 중요하다. 그래서 실제로 생략 가능한 필드라면 아래처럼 기본값까지 같이 지정하는 편이 안전하다.

description: str | None = None

이렇게 써야 “안 보내도 되는 선택 필드”라는 의미가 더 분명해진다.

참고: [Pydantic 공식 문서 - Migration Guide](https://pydantic.dev/docs/validation/latest/get-started/migration/)

Field로 더 구체적인 조건 넣기

타입만으로는 부족한 경우가 있다.

예를 들어 가격은 정수여야 할 뿐 아니라 0보다 커야 한다. 상품명은 너무 짧으면 안 된다.

이럴 때 Field를 사용할 수 있다.

from pydantic import BaseModel, Field

class Item(BaseModel):
    name: str = Field(min_length=2, max_length=50)
    price: int = Field(gt=0)
    description: str | None = Field(default=None, max_length=300)

각 조건은 다음처럼 읽으면 된다.

코드	의미
`min_length=2`	최소 2글자
`max_length=50`	최대 50글자
`gt=0`	0보다 커야 함
`default=None`	기본값은 None

FastAPI 공식 문서에서도 Pydantic의 Field를 사용해 모델 속성에 추가 검증과 메타데이터를 선언할 수 있다고 설명한다.

참고: [FastAPI 공식 문서 - Body Fields](https://fastapi.tiangolo.com/tutorial/body-fields/)

여기서 gt는 greater than, 즉 “보다 큼”이라는 뜻이다.

price: int = Field(gt=0)

이 코드는 price가 0보다 큰 정수여야 한다는 의미다.

따라서 아래 요청은 실패한다.

{
  "name": "가방",
  "price": 0
}

가격이 0보다 커야 하는데 0이 들어왔기 때문이다.

요청 모델과 응답 모델은 분리하는 게 좋다

초보 단계에서는 요청으로 받은 모델을 그대로 응답해도 된다.

@app.post("/items")
def create_item(item: Item):
    return item

하지만 실제 서비스에서는 요청 모델과 응답 모델을 분리하는 경우가 많다.

예를 들어 상품을 만들 때 클라이언트는 name, price만 보낸다. 그런데 응답에는 서버가 만든 id도 포함해야 한다.

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()

class ItemCreate(BaseModel):
    name: str = Field(min_length=2, max_length=50)
    price: int = Field(gt=0)
    description: str | None = None

class ItemResponse(BaseModel):
    id: int
    name: str
    price: int
    description: str | None = None

@app.post("/items", response_model=ItemResponse)
def create_item(item: ItemCreate):
    return {
        "id": 1,
        "name": item.name,
        "price": item.price,
        "description": item.description
    }

여기서 ItemCreate는 요청용 모델이고, ItemResponse는 응답용 모델이다.

FastAPI의 response_model은 응답 데이터 문서화, 검증, 변환, 필터링 등에 사용된다. 공식 문서에서도 response_model을 통해 응답 데이터 구조를 선언할 수 있다고 설명한다.

참고: [FastAPI 공식 문서 - Response Model](https://fastapi.tiangolo.com/tutorial/response-model/)

참고로 FastAPI에서는 함수의 반환 타입 힌트로 응답 모델을 표현할 수도 있다. ```python @app.post("/items") def create_item(item: ItemCreate) -> ItemResponse: pass ` 위 코드는 반환 타입 힌트 문법을 보여주기 위한 간단한 예시다. 실제 코드에서는 pass 대신 데이터를 저장하거나, 응답으로 보낼 값을 만들어 return해야 한다. 다만 입문 단계에서는 response_model=ItemResponse처럼 명시적으로 적는 방식이 요청 모델과 응답 모델의 차이를 이해하기 더 쉽다.

여기서 중요한 점은 보안이다.

예를 들어 회원가입 API에서 요청 모델에 password가 있다고 해서 응답에도 그대로 비밀번호를 보내면 안 된다.

class UserCreate(BaseModel):
    email: str
    password: str

class UserResponse(BaseModel):
    id: int
    email: str

요청과 응답 모델을 분리하면 이런 실수를 줄일 수 있다.

자주 헷갈리는 부분

1. Pydantic 모델은 데이터베이스 모델이 아니다

Pydantic 모델은 요청과 응답 데이터의 구조를 검증하는 데 주로 사용한다.

데이터베이스 테이블을 정의하는 모델과는 다르다.

예를 들어 SQLAlchemy 모델은 DB 테이블과 연결되고, Pydantic 모델은 API 입출력 데이터와 연결된다.

처음에는 둘 다 “모델”이라고 부르기 때문에 헷갈릴 수 있다.

Pydantic 모델: API 요청/응답 데이터 검증
ORM 모델: 데이터베이스 테이블 매핑

둘은 목적이 다르다.

2. 타입 힌트만 쓴다고 자동 검증되는 것은 아니다

파이썬 함수에서 이렇게 쓴다고 해서 일반 파이썬 코드가 자동으로 타입을 막아주는 것은 아니다.

def create_item(price: int):
    return price

파이썬의 타입 힌트는 기본적으로 개발자와 도구를 위한 힌트에 가깝다.

하지만 FastAPI와 Pydantic을 함께 쓰면 이 타입 정보가 실제 요청 검증에 활용된다.

이 차이를 이해해야 한다.

3. GET 요청에는 보통 Body를 쓰지 않는다

FastAPI는 복잡한 경우 GET 요청에 Body를 받는 것도 지원하지만, 일반적인 API 설계에서는 POST, PUT, PATCH 요청에서 Body를 사용하는 흐름이 더 자연스럽다.

FastAPI 공식 문서도 데이터를 보낼 때는 보통 POST, PUT, DELETE, PATCH 등을 사용한다고 설명한다.

참고: [FastAPI 공식 문서 - Request Body](https://fastapi.tiangolo.com/tutorial/body/)

조회 조건이 단순하면 GET의 쿼리 파라미터를 쓰고, 생성이나 수정처럼 데이터 묶음을 보내야 하면 요청 본문을 쓰는 식으로 나누면 된다.

전체 예제 코드

아래 코드는 지금까지 내용을 합친 간단한 예제다.

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()

class ItemCreate(BaseModel):
    name: str = Field(min_length=2, max_length=50)
    price: int = Field(gt=0)
    description: str | None = Field(default=None, max_length=300)
    is_active: bool = True

class ItemResponse(BaseModel):
    id: int
    name: str
    price: int
    description: str | None = None
    is_active: bool

@app.post("/items", response_model=ItemResponse)
def create_item(item: ItemCreate):
    return {
        "id": 1,
        "name": item.name,
        "price": item.price,
        "description": item.description,
        "is_active": item.is_active
    }

서버 실행은 이전 글에서 사용한 방식과 동일하다.

fastapi dev main.py

파일 이름을 app.py로 만들었다면 아래처럼 파일명에 맞춰 실행하면 된다.

fastapi dev app.py

또는 환경에 따라 Uvicorn을 직접 실행할 수도 있다.

uvicorn main:app --reload

여기서 main:app은 main.py 파일 안의 app = FastAPI() 객체를 실행한다는 뜻이다. 파일 이름이 app.py라면 uvicorn app:app --reload처럼 앞부분도 파일명에 맞춰 바꿔야 한다.

브라우저에서 아래 주소로 접속한다.

http://127.0.0.1:8000/docs

POST /items를 열고 Try it out을 누른 뒤 아래 JSON을 입력해보면 된다.

{
  "name": "맥북 파우치",
  "price": 25000,
  "description": "노트북 보호용 파우치",
  "is_active": true
}

이제 price를 0으로 바꾸거나, name을 한 글자로 줄여보면 검증 에러가 어떻게 나오는지도 확인할 수 있다.

실제로는 정상 요청보다 실패 요청을 일부러 보내보는 게 더 도움이 된다. Pydantic 모델이 어떤 기준으로 요청을 막는지 눈으로 볼 수 있기 때문이다.

FastAPI에서 Pydantic 모델을 배울 때의 기준

FastAPI에서 Pydantic 모델은 “예쁘게 클래스를 만드는 문법”이 아니다.

API가 받을 수 있는 데이터의 모양을 정하고, 잘못된 요청을 함수 실행 전에 걸러내고, Swagger UI 문서까지 자동으로 정리해주는 기준점에 가깝다.

처음에는 아래 네 가지만 구분하면 충분하다.

BaseModel: 데이터 구조 정의
타입 힌트: 필드 타입 지정
Field: 세부 검증 조건 추가
response_model: 응답 구조 지정

이 흐름이 잡히면 FastAPI의 POST, PUT, PATCH 요청을 훨씬 안정적으로 다룰 수 있다.

다음 단계에서는 중첩 모델, 리스트 요청, 여러 모델을 함께 받는 방식까지 확장하면 된다.

FastAPI Path Parameter와 Query Parameter 차이 정리

notebase — Sun, 24 May 2026 12:17:01 +0900

FastAPI에서 Path Parameter와 Query Parameter를 어떻게 구분하고 사용하는지 예제 코드와 함께 정리합니다. 필수값, 선택값, 타입 변환, 검증 방식까지 함께 설명합니다.

FastAPI Path Parameter와 Query Parameter는 URL로 값을 받는 방식이다. 둘 다 API에서 자주 쓰이지만, 역할은 다르다.

FastAPI를 처음 배우면 이런 URL을 자주 보게 된다.

/items/1
/items?skip=0&limit=10

둘 다 서버에 값을 전달한다는 점은 같다.
하지만 /items/1의 1은 Path Parameter이고, ?skip=0&limit=10은 Query Parameter다.

이 차이를 정확히 알아야 API 주소를 자연스럽게 설계할 수 있다.

Path Parameter와 Query Parameter의 차이

가장 먼저 기준부터 잡고 가면 편하다.

구분	Path Parameter	Query Parameter
위치	URL 경로 안	`?` 뒤
예시	`/items/1`	`/items?skip=0&limit=10`
주 용도	특정 리소스 지정	검색, 필터, 정렬, 페이지네이션
필수 여부	보통 필수	선택값으로 자주 사용
FastAPI 처리 방식	경로에 선언된 이름으로 인식	함수 매개변수 중 경로에 없는 값을 쿼리로 인식

FastAPI에서 Path Parameter는 {item_id}처럼 중괄호를 사용해 선언한다.

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

여기서 /items/{item_id}의 {item_id}가 Path Parameter다.

FastAPI Path Parameter 사용법

Path Parameter는 URL 경로 자체에 값이 들어가는 방식이다.

예를 들어 상품 상세 조회 API를 만든다고 해보자.

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

이 API는 다음 주소로 요청할 수 있다.

http://127.0.0.1:8000/items/1

그러면 FastAPI는 URL의 1을 item_id에 넣어준다.

응답은 다음과 비슷하다.

{
  "item_id": 1
}

여기서 중요한 부분은 item_id: int다.
URL로 들어오는 값은 원래 문자열이지만, FastAPI는 타입 힌트를 보고 int로 변환한다.

만약 아래처럼 숫자가 아닌 값을 넣으면 어떻게 될까?

/items/abc

item_id는 int여야 하는데 abc는 정수로 바꿀 수 없다.
이 경우 FastAPI는 자동으로 검증 오류를 반환한다.

직접 if문으로 타입 검사를 작성하지 않아도 된다는 점이 FastAPI의 편한 부분이다.

Path Parameter는 언제 사용할까?

Path Parameter는 무엇을 조회할지 URL 경로에서 바로 알 수 있어야 할 때 사용한다.

예를 들면 이런 경우다.

/users/10
/posts/35
/products/7
/orders/202

각 주소는 특정한 하나의 리소스를 가리킨다.

/users/10 → 10번 사용자
/posts/35 → 35번 게시글
/products/7 → 7번 상품

즉, Path Parameter는 보통 ID나 고유한 이름처럼 리소스를 식별하는 값에 잘 맞는다.

FastAPI Query Parameter 사용법

Query Parameter는 URL의 ? 뒤에 붙는 값이다.

예를 들어 게시글 목록을 조회하면서 검색어를 전달한다고 해보자.

from fastapi import FastAPI

app = FastAPI()

@app.get("/posts")
async def read_posts(keyword: str | None = None):
    return {"keyword": keyword}

요청 주소는 이렇게 만들 수 있다.

http://127.0.0.1:8000/posts?keyword=fastapi

그러면 keyword에는 "fastapi"가 들어간다.

응답은 다음과 비슷하다.

{
  "keyword": "fastapi"
}

FastAPI에서는 함수 매개변수 중 URL 경로에 선언되지 않은 값이 있으면, 기본적으로 Query Parameter로 인식한다.

참고: 이 글의 예제는 Python 3.10 이상 문법을 기준으로 작성했다. str | None 문법은 Python 3.10 이상에서 사용할 수 있다. Python 3.9 이하를 사용한다면 from typing import Optional을 가져온 뒤 Optional[str] = None 형태로 작성하면 된다.

Python 3.9 이하에서는 위 코드를 이렇게 바꿔 쓸 수 있다.

from typing import Optional

from fastapi import FastAPI

app = FastAPI()

@app.get("/posts")
async def read_posts(keyword: Optional[str] = None):
    return {"keyword": keyword}

Query Parameter는 언제 사용할까?

Query Parameter는 목록을 조회하거나 조건을 추가할 때 자주 쓴다.

예를 들면 이런 주소다.

/posts?keyword=fastapi
/posts?category=python
/posts?skip=0&limit=10
/posts?sort=latest

각 값은 특정 리소스를 직접 가리키기보다는 조회 조건에 가깝다.

keyword=fastapi → 검색어
category=python → 카테고리 필터
skip=0&limit=10 → 페이지네이션
sort=latest → 정렬 기준

이런 값들은 없어도 기본 목록 조회가 가능하다.
그래서 Query Parameter는 선택값으로 설계하는 경우가 많다.

Query Parameter의 선택값과 필수값

Query Parameter는 기본값을 주면 선택값이 된다.

@app.get("/posts")
async def read_posts(keyword: str | None = None):
    return {"keyword": keyword}

여기서 keyword의 기본값은 None이다.
그래서 아래 주소도 정상적으로 동작한다.

/posts

이 경우 keyword에는 None이 들어간다.

반대로 기본값을 주지 않으면 필수 Query Parameter가 된다.

@app.get("/posts/search")
async def search_posts(keyword: str):
    return {"keyword": keyword}

이 API는 반드시 다음처럼 요청해야 한다.

/posts/search?keyword=fastapi

기본값이 있으면 선택값, 기본값이 없으면 필수값이라고 보면 된다.

Path Parameter와 Query Parameter 함께 사용하기

실제 API에서는 둘을 같이 쓰는 경우가 많다.

예를 들어 특정 사용자의 게시글 목록을 조회하면서 검색어와 페이지 크기를 함께 받는 API를 만들어보자.

from fastapi import FastAPI

app = FastAPI()

@app.get("/users/{user_id}/posts")
async def read_user_posts(
    user_id: int,
    keyword: str | None = None,
    limit: int = 10
):
    return {
        "user_id": user_id,
        "keyword": keyword,
        "limit": limit
    }

요청은 이렇게 보낼 수 있다.

/users/3/posts?keyword=fastapi&limit=5

이때 값은 다음처럼 들어간다.

{
  "user_id": 3,
  "keyword": "fastapi",
  "limit": 5
}

여기서 user_id는 Path Parameter다.
keyword와 limit은 Query Parameter다.

FastAPI는 함수 매개변수 순서에 의존해서 Path와 Query를 구분하지 않는다.
경로에 {user_id}가 있으므로 user_id는 Path Parameter가 되고, 나머지 값은 Query Parameter로 처리된다.

Boolean Query Parameter도 자동 변환된다

FastAPI는 Query Parameter의 타입도 자동으로 변환한다.

@app.get("/posts")
async def read_posts(short: bool = False):
    return {"short": short}

다음 요청들은 모두 short=True로 처리될 수 있다.

/posts?short=true
/posts?short=True
/posts?short=1
/posts?short=yes
/posts?short=on

FastAPI는 타입 힌트를 기준으로 /docs 문서도 자동 생성한다.
예를 들어 short: bool = False처럼 선언하면 Swagger UI에서는 해당 값이 boolean 타입으로 표시된다. API를 직접 테스트할 때도 어떤 타입을 기대하는지 바로 확인할 수 있다.

다만 실제 URL 요청에서는 true, 1, yes, on처럼 여러 표현이 True로 해석될 수 있다.
팀 내부나 외부 사용자에게 공개하는 API라면 예시 문서에서는 true / false처럼 하나의 표기 방식을 정해두는 편이 좋다.

`Path`와 `Query`로 검증 조건 추가하기

단순히 타입만 지정하는 것보다 더 자세한 조건을 걸고 싶을 때가 있다.

예를 들어 item_id는 1 이상이어야 하고, 검색어 q는 최대 50자까지만 허용하고 싶다고 해보자.

이럴 때는 Path, Query, Annotated를 함께 사용할 수 있다.

from typing import Annotated

from fastapi import FastAPI, Path, Query

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(
    item_id: Annotated[int, Path(ge=1)],
    q: Annotated[str | None, Query(max_length=50)] = None
):
    return {
        "item_id": item_id,
        "q": q
    }

여기서 Path(ge=1)은 item_id가 1 이상이어야 한다는 뜻이다.

/items/0

이런 요청은 검증을 통과하지 못한다.

Query(max_length=50)은 q의 길이를 최대 50자로 제한한다.
이런 검증 조건은 FastAPI가 자동 생성하는 OpenAPI 문서에도 함께 반영된다.

숫자 검증에서는 자주 이런 옵션을 사용한다.

옵션	의미
`gt`	greater than, 초과
`ge`	greater than or equal, 이상
`lt`	less than, 미만
`le`	less than or equal, 이하

예를 들어 limit 값을 1 이상 100 이하로 제한하고 싶다면 이렇게 작성할 수 있다.

from typing import Annotated

from fastapi import Query

async def read_posts(
    limit: Annotated[int, Query(ge=1, le=100)] = 10
):
    return {"limit": limit}

실제로는 목록 API에서 limit에 이런 제한을 자주 둔다.
제한이 없으면 한 번에 너무 많은 데이터를 요청할 수 있기 때문이다.

`Annotated` 문법은 어떻게 읽으면 될까?

입문자 입장에서는 Annotated[int, Path(ge=1)]가 낯설 수 있다.

이 문법은 크게 두 부분으로 보면 된다.

Annotated[int, Path(ge=1)]

int → 실제 값의 타입
Path(ge=1) → FastAPI에 전달할 검증 조건이나 메타데이터

즉, 위 코드는 “이 값은 int 타입이고, FastAPI에서는 경로 매개변수로 다루되 1 이상이어야 한다”는 뜻이다.

Query도 같은 방식으로 읽으면 된다.

Annotated[str | None, Query(max_length=50)]

이 코드는 “문자열이거나 None이 될 수 있고, 쿼리 파라미터로 받을 때 최대 길이는 50자까지 허용한다”는 의미다.

처음에는 문법이 길어 보일 수 있지만, 타입과 검증 조건을 한곳에 모아둘 수 있어서 코드가 커질수록 관리하기 편하다.

Path Parameter는 항상 필수다

여기서 자주 헷갈리는 부분이 있다.

Query Parameter는 기본값을 None으로 두면 선택값이 될 수 있다.
하지만 Path Parameter는 기본적으로 선택값이 될 수 없다.

예를 들어 이 주소를 보자.

/items/{item_id}

이 API를 호출하려면 item_id가 반드시 URL에 있어야 한다.

/items/1

아래처럼 호출하면 같은 경로가 아니다.

/items

Path Parameter는 URL 경로의 일부다.
그래서 선택적으로 받을 값이라면 Path Parameter가 아니라 Query Parameter로 설계하는 편이 자연스럽다.

실제 API 설계 기준

둘 중 무엇을 써야 할지 헷갈릴 때는 이 기준으로 보면 된다.

특정 대상을 가리키면 Path Parameter

/users/1
/posts/10
/products/3

이런 값은 URL에서 빠지면 API의 의미가 바뀐다.
따라서 Path Parameter가 잘 맞는다.

@app.get("/posts/{post_id}")
async def read_post(post_id: int):
    return {"post_id": post_id}

조회 조건을 조절하면 Query Parameter

/posts?keyword=fastapi
/posts?limit=10
/posts?sort=latest

이런 값은 목록 조회의 조건을 바꾼다.
값이 없어도 기본 조회는 가능하다.

@app.get("/posts")
async def read_posts(
    keyword: str | None = None,
    limit: int = 10
):
    return {
        "keyword": keyword,
        "limit": limit
    }

실제로는 Path와 Query를 같이 쓰는 경우가 많다.

/users/1/posts?limit=10&sort=latest

이 주소는 이렇게 읽을 수 있다.

users/1 → 1번 사용자의
posts → 게시글 목록을
limit=10&sort=latest → 10개씩 최신순으로 조회한다

URL만 봐도 API의 의도가 꽤 명확해진다.

자주 하는 실수

1. 검색 조건을 Path Parameter로 만드는 경우

/posts/fastapi

이 주소가 “fastapi라는 검색어로 게시글을 찾는다”는 의미라면 Query Parameter가 더 자연스럽다.

/posts?keyword=fastapi

/posts/fastapi는 보통 fastapi라는 고유 ID나, 글 제목을 URL에 쓰기 좋게 바꾼 식별자(slug)를 가진 게시글을 조회하는 느낌에 가깝다.

2. ID를 Query Parameter로만 처리하는 경우

/posts?post_id=10

동작은 가능하지만, 특정 게시글 하나를 조회하는 API라면 보통 아래가 더 자연스럽다.

/posts/10

리소스 식별자는 Path Parameter로 두는 쪽이 REST API 주소 구조에 더 잘 맞는다.

3. 선택값을 Path Parameter로 만들려는 경우

/posts/{category}

카테고리가 항상 필요한 API라면 괜찮다.
하지만 카테고리 없이 전체 게시글도 조회해야 한다면 Query Parameter가 낫다.

/posts
/posts?category=python

선택 조건은 Query Parameter로 빼는 편이 API를 확장하기 쉽다.

전체 예제 코드

마지막으로 지금까지 본 Path Parameter, Query Parameter, 타입 변환, 검증 조건을 하나로 조합해보자.

from typing import Annotated

from fastapi import FastAPI, Path, Query

app = FastAPI()

@app.get("/users/{user_id}/posts")
async def read_user_posts(
    user_id: Annotated[int, Path(ge=1)],
    keyword: Annotated[str | None, Query(max_length=50)] = None,
    limit: Annotated[int, Query(ge=1, le=100)] = 10,
    sort: str = "latest"
):
    return {
        "user_id": user_id,
        "keyword": keyword,
        "limit": limit,
        "sort": sort
    }

이 예제는 특정 사용자의 게시글 목록을 조회하면서 검색어, 개수 제한, 정렬 기준까지 함께 받는 형태다.

요청 예시는 다음과 같다.

/users/1/posts?keyword=fastapi&limit=20&sort=latest

이 예제에서 각 값의 역할은 다음과 같다.

값	종류	의미
`user_id`	Path Parameter	어떤 사용자의 게시글인지 지정
`keyword`	Query Parameter	검색어
`limit`	Query Parameter	가져올 개수
`sort`	Query Parameter	정렬 기준

user_id는 URL 경로에서 빠지면 API가 성립하지 않는다.
반면 keyword, limit, sort는 조회 조건이다.

이렇게 구분하면 API 주소가 훨씬 읽기 쉬워진다.

FAQ

Path Parameter와 Query Parameter는 둘 다 GET 요청에서만 쓰나요?

아니다. GET 요청에서 자주 보일 뿐이다. Path Parameter는 URL 경로의 일부이므로 다른 HTTP 메서드에서도 사용할 수 있다. 예를 들어 DELETE /posts/10처럼 특정 게시글을 삭제할 때도 Path Parameter를 쓴다.

Query Parameter는 항상 선택값인가요?

아니다. 기본값을 주면 선택값이 되지만, 기본값 없이 선언하면 필수값이 된다.

Path Parameter에 기본값을 줄 수 있나요?

Path Parameter는 URL 경로의 일부라서 항상 필요하다. 선택값처럼 쓰고 싶다면 Query Parameter로 설계하는 편이 자연스럽다.

`Path`, `Query`는 꼭 써야 하나요?

기본적인 값 전달만 할 때는 꼭 필요하지 않다. 하지만 최소값, 최대값, 문자열 길이, 별칭, 설명 같은 조건을 추가하려면 Path, Query를 쓰는 편이 좋다.

`Annotated`를 꼭 써야 하나요?

간단한 예제에서는 꼭 필요하지 않다. 다만 Path, Query로 검증 조건을 함께 넣을 때는 Annotated를 쓰면 타입과 검증 조건을 분리해서 읽기 좋다. FastAPI 공식 문서에서도 최신 예제에서는 Annotated 사용을 권장하는 흐름이다.

마무리

FastAPI에서 Path Parameter는 특정 리소스를 지정하는 값에 어울린다.
Query Parameter는 조회 조건을 조절하는 값에 어울린다.

글을 작성하거나 코드를 짤 때는 이 기준만 먼저 적용해도 대부분의 API 주소가 자연스럽게 정리된다.

특정 사용자, 게시글, 상품처럼 하나를 가리키면 Path Parameter
검색어, 정렬, 필터, 페이지네이션처럼 조건을 바꾸면 Query Parameter

FastAPI는 타입 힌트만으로도 값 변환과 검증을 처리해준다. 여기에 Path, Query, Annotated를 함께 쓰면 실무에서 쓰기 좋은 API 형태로 조금 더 단단하게 다듬을 수 있다.

FastAPI GET, POST 요청 이해하기: 조회와 데이터 전송의 차이

notebase — Sun, 24 May 2026 11:50:34 +0900

FastAPI에서 GET과 POST 요청이 어떻게 다른지, 조회 API와 데이터 생성 API를 직접 만들며 Request Body, Pydantic, HTTPException, 자동 문서 테스트 흐름까지 초보자 기준으로 정리했습니다.

FastAPI GET, POST 요청 차이는 API를 만들 때 가장 먼저 헷갈리는 부분입니다. 간단히 보면 GET은 데이터를 조회할 때, POST는 새 데이터를 보내거나 생성할 때 주로 사용합니다.

처음에는 @app.get()과 @app.post()가 문법만 다른 것처럼 보일 수 있습니다.

하지만 실제로는 API의 목적이 다릅니다.

사용자가 상품 목록을 본다 → GET
사용자가 새 상품을 등록한다 → POST
게시글 상세 내용을 불러온다 → GET
회원가입 정보를 서버로 보낸다 → POST

이 차이를 이해하면 FastAPI 코드도 훨씬 자연스럽게 읽힙니다.

GET과 POST는 무엇이 다를까?

API 요청은 클라이언트가 서버에 “무엇을 해달라”고 보내는 신호입니다.

여기서 클라이언트는 브라우저, 모바일 앱, 프론트엔드 화면, 다른 서버가 될 수 있습니다.

GET과 POST는 그 요청의 종류입니다.

구분	GET	POST
주 용도	데이터 조회	데이터 생성 또는 전송
데이터 전달 위치	URL 경로 또는 쿼리 파라미터	Request Body
브라우저 주소창 테스트	쉬움	어렵거나 제한적
FastAPI 문법	`@app.get()`	`@app.post()`
예시	상품 목록 조회	새 상품 등록

여기서 중요한 점은 GET이 “가볍고”, POST가 “무겁다”는 식으로 외우는 게 아닙니다.

GET은 서버에 있는 데이터를 가져오는 요청, POST는 서버에 데이터를 보내는 요청에 가깝게 이해하면 됩니다.

실습 준비

이 글은 이전 단계에서 FastAPI 설치와 첫 실행까지 끝낸 상태를 기준으로 합니다.

프로젝트 폴더 구조는 아래처럼 두면 됩니다.

fastapi-get-post/
├── .venv/
└── main.py

가상환경이 아직 없다면 먼저 만듭니다.

python -m venv .venv

Windows PowerShell에서는 아래처럼 활성화합니다.

.venv\Scripts\activate.ps1

macOS, Linux에서는 아래 명령어를 사용합니다.

source .venv/bin/activate

FastAPI가 설치되어 있지 않다면 설치합니다.

pip install "fastapi[standard]"

서버 실행은 아래 명령어를 사용할 겁니다.

fastapi dev main.py

fastapi dev main.py는 개발용 실행 명령어입니다. 코드를 수정하고 저장하면 서버가 자동으로 다시 로드되므로, 매번 터미널에서 서버를 껐다 켤 필요는 없습니다.

GET 요청 만들기

먼저 가장 단순한 GET API를 만들어보겠습니다.

main.py 파일에 아래 코드를 작성합니다.

# main.py
from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def read_root():
    return {"message": "FastAPI GET POST example"}

서버를 실행합니다.

fastapi dev main.py

브라우저에서 아래 주소로 접속합니다.

http://127.0.0.1:8000

응답은 이렇게 나옵니다.

{
  "message": "FastAPI GET POST example"
}

여기서 핵심은 이 부분입니다.

@app.get("/")
def read_root():
    return {"message": "FastAPI GET POST example"}

@app.get("/")는 / 주소로 GET 요청이 들어왔을 때 바로 아래 함수를 실행하라는 뜻입니다.

브라우저 주소창에 URL을 입력해서 접속하는 행동도 기본적으로 GET 요청에 가깝습니다. 그래서 GET API는 주소창에서 바로 테스트하기 쉽습니다.

상품 목록을 GET으로 조회하기

이번에는 조금 더 API다운 예제를 만들어보겠습니다.

상품 목록을 조회하는 API입니다.

main.py를 아래처럼 수정합니다.

# main.py
from fastapi import FastAPI

app = FastAPI()

items = [
    {"id": 1, "name": "keyboard", "price": 30000},
    {"id": 2, "name": "mouse", "price": 15000},
]


@app.get("/")
def read_root():
    return {"message": "FastAPI GET POST example"}


@app.get("/items")
def read_items():
    return {"items": items}

브라우저에서 아래 주소로 접속합니다.

http://127.0.0.1:8000/items

응답은 이렇게 나옵니다.

{
  "items": [
    {
      "id": 1,
      "name": "keyboard",
      "price": 30000
    },
    {
      "id": 2,
      "name": "mouse",
      "price": 15000
    }
  ]
}

이 API는 서버에 있는 items 목록을 가져옵니다.

그래서 GET /items가 자연스럽습니다.

여기서 items는 임시 데이터입니다. 실제 서비스라면 데이터베이스에 저장된 상품 목록을 가져오겠지만, 처음에는 리스트로 흐름만 이해해도 충분합니다.

Path Parameter로 특정 상품 조회하기

상품 전체 목록이 아니라 특정 상품 하나만 조회하고 싶을 수도 있습니다.

예를 들어 아래 주소처럼 상품 ID를 URL에 넣는 방식입니다.

http://127.0.0.1:8000/items/1

이런 값을 Path Parameter라고 합니다. FastAPI 공식 문서에서도 /items/{item_id} 같은 형식으로 path parameter를 선언하는 방식을 안내합니다.

main.py에 아래 코드를 추가합니다.

# main.py
from fastapi import FastAPI, HTTPException

app = FastAPI()

items = [
    {"id": 1, "name": "keyboard", "price": 30000},
    {"id": 2, "name": "mouse", "price": 15000},
]


@app.get("/")
def read_root():
    return {"message": "FastAPI GET POST example"}


@app.get("/items")
def read_items():
    return {"items": items}


@app.get("/items/{item_id}")
def read_item(item_id: int):
    for item in items:
        if item["id"] == item_id:
            return item

    raise HTTPException(status_code=404, detail="Item not found")

브라우저에서 아래 주소로 접속합니다.

http://127.0.0.1:8000/items/1

응답은 이렇게 나옵니다.

{
  "id": 1,
  "name": "keyboard",
  "price": 30000
}

이번에는 2번 상품을 조회해봅니다.

http://127.0.0.1:8000/items/2

응답은 이렇게 바뀝니다.

{
  "id": 2,
  "name": "mouse",
  "price": 15000
}

없는 상품 ID를 조회하면 어떻게 될까요?

http://127.0.0.1:8000/items/999

이 경우에는 아래 코드가 실행됩니다.

raise HTTPException(status_code=404, detail="Item not found")

HTTPException은 API에서 에러 응답을 명확하게 내려줄 때 사용합니다. 여기서는 상품을 찾지 못했으므로 404 Not Found 상태 코드를 반환합니다.

이전처럼 단순히 {"message": "Item not found"}를 반환할 수도 있습니다. 하지만 그러면 실제로는 상품을 못 찾았는데도 HTTP 상태 코드는 200 OK가 될 수 있습니다. API를 설계할 때는 이런 부분을 구분해주는 편이 좋습니다.

여기서 봐야 할 또 다른 부분은 item_id: int입니다.

def read_item(item_id: int):

FastAPI는 URL로 들어온 값이 정수인지 확인합니다.

예를 들어 /items/abc처럼 숫자가 아닌 값을 넣으면 FastAPI는 item_id를 정수로 바꿀 수 없다고 판단하고 422 검증 에러를 반환합니다.

응답 형식은 FastAPI와 Pydantic 버전에 따라 조금 다를 수 있지만, 대략 아래처럼 item_id 위치에서 정수 변환에 실패했다는 내용이 포함됩니다.

{
  "detail": [
    {
      "loc": ["path", "item_id"],
      "msg": "Input should be a valid integer"
    }
  ]
}

이게 FastAPI의 장점 중 하나입니다. Python 타입 힌트를 적으면 요청 데이터 검증과 문서화에 함께 활용됩니다.

Query Parameter로 검색 조건 받기

GET 요청에서는 URL 뒤에 조건을 붙여서 데이터를 조회할 수도 있습니다.

예를 들어 아래 주소를 봅니다.

http://127.0.0.1:8000/search?keyword=key

?keyword=key 부분이 Query Parameter입니다.

검색어, 페이지 번호, 정렬 조건처럼 “조회 조건”을 보낼 때 자주 사용합니다. FastAPI 공식 문서에서도 함수 인자 중 path에 포함되지 않은 단순 타입 값은 query parameter로 해석된다고 설명합니다.

main.py를 아래처럼 수정합니다.

# main.py
from fastapi import FastAPI, HTTPException

app = FastAPI()

items = [
    {"id": 1, "name": "keyboard", "price": 30000},
    {"id": 2, "name": "mouse", "price": 15000},
]


@app.get("/")
def read_root():
    return {"message": "FastAPI GET POST example"}


@app.get("/items")
def read_items():
    return {"items": items}


@app.get("/items/{item_id}")
def read_item(item_id: int):
    for item in items:
        if item["id"] == item_id:
            return item

    raise HTTPException(status_code=404, detail="Item not found")


@app.get("/search")
def search_items(keyword: str = ""):
    result = []

    for item in items:
        if keyword.lower() in item["name"].lower():
            result.append(item)

    return {"keyword": keyword, "result": result}

브라우저에서 아래 주소로 접속합니다.

http://127.0.0.1:8000/search?keyword=key

응답은 이렇게 나옵니다.

{
  "keyword": "key",
  "result": [
    {
      "id": 1,
      "name": "keyboard",
      "price": 30000
    }
  ]
}

keyword 값을 바꿔보면 결과도 바뀝니다.

http://127.0.0.1:8000/search?keyword=mouse

이렇게 GET 요청은 데이터를 조회하면서 조건을 붙이는 데 잘 어울립니다.

POST 요청 만들기

이제 POST 요청을 만들어보겠습니다.

POST는 보통 클라이언트가 서버에 데이터를 보낼 때 사용합니다. 예를 들어 새 상품 등록, 회원가입, 게시글 작성 같은 작업입니다.

GET은 주소창에서 쉽게 테스트할 수 있었지만, POST는 보통 Request Body에 JSON 데이터를 담아 보냅니다. 그래서 브라우저 주소창만으로는 테스트하기 어렵고, FastAPI의 /docs 화면이나 Postman 같은 도구를 사용합니다.

FastAPI에서는 Request Body를 받을 때 Pydantic의 BaseModel을 자주 사용합니다. 공식 문서에서도 Pydantic 모델을 함수 인자로 선언하면 해당 값이 request body로 처리된다고 안내합니다.

main.py를 아래처럼 수정합니다.

# main.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    price: int


items = [
    {"id": 1, "name": "keyboard", "price": 30000},
    {"id": 2, "name": "mouse", "price": 15000},
]


@app.get("/")
def read_root():
    return {"message": "FastAPI GET POST example"}


@app.get("/items")
def read_items():
    return {"items": items}


@app.get("/items/{item_id}")
def read_item(item_id: int):
    for item in items:
        if item["id"] == item_id:
            return item

    raise HTTPException(status_code=404, detail="Item not found")


@app.post("/items")
def create_item(item: Item):
    new_item = {
        "id": len(items) + 1,
        "name": item.name,
        "price": item.price,
    }

    items.append(new_item)

    return new_item

새로 추가된 부분은 두 군데입니다.

먼저 요청으로 받을 데이터 형식을 정의합니다.

class Item(BaseModel):
    name: str
    price: int

이 코드는 “상품을 등록할 때 name은 문자열, price는 정수로 받겠다”는 뜻입니다.

다음은 POST API입니다.

@app.post("/items")
def create_item(item: Item):
    new_item = {
        "id": len(items) + 1,
        "name": item.name,
        "price": item.price,
    }

    items.append(new_item)

    return new_item

@app.post("/items")는 /items 주소로 POST 요청이 들어왔을 때 실행됩니다.

GET으로 /items에 접근하면 상품 목록을 조회하고, POST로 /items에 요청하면 새 상품을 추가하는 구조입니다.

주소는 같아도 요청 방식이 다르면 다른 API처럼 동작할 수 있습니다.

`/docs`에서 POST 요청 테스트하기

POST 요청은 FastAPI 자동 문서에서 테스트하는 편이 가장 쉽습니다.

서버가 실행 중인 상태에서 아래 주소로 들어갑니다.

http://127.0.0.1:8000/docs

화면에서 POST /items 항목을 찾습니다.

아래 순서대로 진행합니다.

**POST /items** 항목을 클릭합니다.
**Try it out** 버튼을 누릅니다.
Request body 영역에 JSON 데이터를 입력합니다.
**Execute** 버튼을 누릅니다.
하단의 Response body에서 응답 결과를 확인합니다.

Request body에는 아래처럼 입력합니다.

{
  "name": "monitor",
  "price": 200000
}

성공하면 응답은 아래처럼 나옵니다.

{
  "id": 3,
  "name": "monitor",
  "price": 200000
}

이제 다시 GET /items를 실행해보면 새 상품이 목록에 추가된 것을 볼 수 있습니다.

{
  "items": [
    {
      "id": 1,
      "name": "keyboard",
      "price": 30000
    },
    {
      "id": 2,
      "name": "mouse",
      "price": 15000
    },
    {
      "id": 3,
      "name": "monitor",
      "price": 200000
    }
  ]
}

단, 이 예제는 메모리 안의 리스트에 데이터를 추가하는 방식입니다.

서버를 껐다가 다시 켜면 추가한 데이터는 사라집니다. 실제 서비스에서는 이런 데이터를 데이터베이스에 저장해야 합니다.

GET과 POST를 같은 주소로 쓰는 이유

처음 보면 헷갈릴 수 있습니다.

@app.get("/items")
def read_items():
    return {"items": items}


@app.post("/items")
def create_item(item: Item):
    ...

둘 다 주소는 /items입니다.

하지만 하나는 GET이고, 하나는 POST입니다.

이 구조는 실제 API에서 자연스럽게 쓰입니다.

GET /items → 상품 목록 조회
POST /items → 새 상품 등록
GET /items/1 → 1번 상품 조회

주소는 리소스를 나타내고, HTTP 메서드는 행동을 나타낸다고 보면 됩니다.

/items는 “상품들”이라는 자원입니다.

그 상품들을 조회하면 GET이고, 상품을 새로 추가하면 POST입니다.

GET으로 데이터를 보내면 안 될까?

GET도 query parameter를 통해 값을 보낼 수 있습니다.

예를 들어 검색어는 이렇게 보낼 수 있습니다.

/search?keyword=keyboard

하지만 상품 등록처럼 구조가 있는 데이터는 GET보다는 POST가 어울립니다.

{
  "name": "monitor",
  "price": 200000
}

이런 데이터는 URL에 붙이기보다 Request Body에 담아 보내는 편이 자연스럽습니다.

특히 회원가입, 게시글 작성, 주문 생성처럼 서버 상태가 바뀌는 작업은 GET보다 POST로 설계하는 게 일반적입니다.

여기서 오해하기 쉬운 부분이 있습니다.

POST Body에 넣는다고 해서 자동으로 보안이 보장되는 것은 아닙니다. URL에 그대로 보이지 않을 뿐입니다. 개발자 도구의 Network 탭을 보면 POST Body에 담긴 값도 확인할 수 있습니다.

실제 서비스에서 민감한 데이터를 다룬다면 HTTPS, 인증, 권한 확인 같은 보안 처리가 필요합니다.

잘못된 데이터가 들어오면 어떻게 될까?

Item 모델은 name을 문자열, price를 정수로 받도록 정의했습니다.

class Item(BaseModel):
    name: str
    price: int

그런데 /docs에서 아래처럼 잘못된 데이터를 보내봅니다.

{
  "name": "monitor",
  "price": "비쌈"
}

그러면 FastAPI는 요청을 그대로 처리하지 않고 검증 에러를 반환합니다.

price는 정수여야 하는데 문자열이 들어왔기 때문입니다.

이 부분이 FastAPI와 Pydantic을 함께 사용할 때 편한 지점입니다. 요청 데이터의 형식을 코드에 적어두면 FastAPI가 자동으로 검증하고, API 문서에도 해당 구조를 보여줍니다.

전체 코드

지금까지 작성한 전체 코드는 아래와 같습니다.

# main.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    price: int


items = [
    {"id": 1, "name": "keyboard", "price": 30000},
    {"id": 2, "name": "mouse", "price": 15000},
]


@app.get("/")
def read_root():
    return {"message": "FastAPI GET POST example"}


@app.get("/items")
def read_items():
    return {"items": items}


@app.get("/items/{item_id}")
def read_item(item_id: int):
    for item in items:
        if item["id"] == item_id:
            return item

    raise HTTPException(status_code=404, detail="Item not found")


@app.get("/search")
def search_items(keyword: str = ""):
    result = []

    for item in items:
        if keyword.lower() in item["name"].lower():
            result.append(item)

    return {"keyword": keyword, "result": result}


@app.post("/items")
def create_item(item: Item):
    new_item = {
        "id": len(items) + 1,
        "name": item.name,
        "price": item.price,
    }

    items.append(new_item)

    return new_item

서버 실행 명령어는 아래와 같습니다.

fastapi dev main.py

자동 문서 화면은 아래 주소에서 확인합니다.

http://127.0.0.1:8000/docs

자주 헷갈리는 부분

GET과 POST는 주소가 달라야 하나요?

꼭 그렇지는 않습니다.

GET /items와 POST /items처럼 주소가 같아도 됩니다.
요청 방식이 다르기 때문에 FastAPI는 서로 다른 함수로 처리합니다.

POST 요청은 브라우저 주소창에서 테스트할 수 있나요?

일반적인 방식으로는 어렵습니다.

주소창에 URL을 입력하는 것은 보통 GET 요청입니다. POST 요청은 /docs, Postman, curl, 프론트엔드 코드 등을 사용해서 테스트하는 편이 좋습니다.

Request Body와 Query Parameter는 뭐가 다른가요?

Query Parameter는 URL에 붙는 값입니다.

/search?keyword=keyboard

Request Body는 요청 안에 담겨서 전달되는 데이터입니다.

{
  "name": "keyboard",
  "price": 30000
}

검색, 필터링, 페이지 번호처럼 간단한 조회 조건은 Query Parameter가 어울립니다.
새 데이터를 생성하거나 구조가 있는 데이터를 보낼 때는 Request Body가 더 자연스럽습니다.

`BaseModel`은 왜 필요한가요?

BaseModel은 요청 데이터의 형태를 정의하는 데 사용합니다.

class Item(BaseModel):
    name: str
    price: int

이렇게 작성하면 FastAPI가 요청 데이터를 검증하고, /docs 문서에도 어떤 JSON을 보내야 하는지 표시해줍니다.

`HTTPException`은 왜 사용하나요?

API에서 에러 상황을 HTTP 상태 코드로 명확하게 알려주기 위해 사용합니다.

예를 들어 없는 상품을 조회했을 때는 단순 메시지보다 404 Not Found를 반환하는 편이 더 자연스럽습니다.

raise HTTPException(status_code=404, detail="Item not found")

FastAPI에서는 HTTPException을 return하는 것이 아니라 raise해서 사용합니다.

처음에는 이렇게 구분하면 된다

FastAPI에서 GET과 POST를 처음 배울 때는 너무 복잡하게 외울 필요가 없습니다.

아래 기준만 잡아도 대부분의 입문 예제는 이해할 수 있습니다.

GET  → 서버에서 데이터를 가져온다
POST → 서버로 데이터를 보낸다

상품 목록을 본다면 GET입니다.

새 상품을 등록한다면 POST입니다.

검색어처럼 간단한 조건은 URL의 Query Parameter로 보내고, 상품 정보처럼 구조가 있는 데이터는 POST의 Request Body로 보냅니다.

없는 상품처럼 요청 결과를 정상으로 처리하기 어려운 경우에는 HTTPException으로 적절한 상태 코드를 반환할 수 있습니다.

이 흐름이 잡히면 다음 단계로는 PUT, PATCH, DELETE 요청을 이어서 배우기 좋습니다. 그때부터는 단순 조회와 생성뿐 아니라 수정, 일부 수정, 삭제까지 API 구조가 조금 더 실제 서비스에 가까워집니다.

FastAPI 설치와 시작하기: 첫 API 만들고 문서 확인까지

notebase — Sun, 24 May 2026 11:33:21 +0900

Python FastAPI 설치부터 가상환경 생성, 첫 API main.py 코드 작성, 서버 실행, 자동 API 문서(docs) 확인까지 초보자 기준으로 직접 따라 할 수 있게 정리한 입문 가이드입니다.

FastAPI 설치를 끝내고 첫 API를 만드는 과정은 생각보다 짧습니다. Python 파일 하나를 만들고, 서버를 실행한 뒤 브라우저에서 응답을 확인하면 기본 흐름은 잡힙니다.

FastAPI는 Python으로 API 서버를 만들 때 자주 쓰이는 웹 프레임워크입니다. Django처럼 큰 웹 서비스 전체를 만들기보다는, 모바일 앱이나 프론트엔드에서 호출할 API 서버를 빠르게 만들 때 많이 사용합니다.

처음 배우는 입장에서는 자동 문서 기능이 특히 편합니다.

코드를 조금만 작성해도 API 문서 화면이 자동으로 만들어집니다. 그래서 내가 만든 API가 제대로 동작하는지 브라우저에서 바로 테스트할 수 있습니다.

FastAPI를 설치하기 전에 필요한 것

먼저 Python이 설치되어 있어야 합니다.

터미널이나 명령 프롬프트에서 아래 명령어를 입력해 봅니다.

python --version

환경에 따라 아래 명령어가 필요할 수 있습니다.

python3 --version

버전이 출력되면 Python은 설치된 상태입니다.

예를 들어 이런 식입니다.

Python 3.12.3

버전이 나오지 않는다면 Python부터 설치해야 합니다. Windows라면 Python 공식 사이트에서 설치할 수 있고, macOS에서는 Homebrew나 공식 설치 파일을 사용할 수 있습니다.

여기서 중요한 점은 FastAPI 자체보다 Python 실행 환경을 먼저 정리하는 것입니다. 설치는 됐는데 python 명령어가 안 먹히면, FastAPI 문제가 아니라 Python 경로 설정 문제일 가능성이 큽니다.

프로젝트 폴더 만들기

먼저 FastAPI 실습용 폴더를 하나 만듭니다.

mkdir fastapi-first-api
cd fastapi-first-api

폴더 이름은 꼭 같을 필요는 없습니다. 다만 처음에는 한글이나 공백이 들어간 폴더명보다 영어 소문자 위주로 만드는 편이 덜 헷갈립니다.

예를 들어 이런 구조로 시작합니다.

fastapi-first-api/

아직 파일은 없습니다.

가상환경 만들기

Python 프로젝트에서는 가상환경을 만들어 두는 편이 좋습니다.

가상환경은 프로젝트마다 패키지를 따로 설치할 수 있게 해주는 공간입니다. 예를 들어 A 프로젝트에서는 FastAPI를 쓰고, B 프로젝트에서는 Django를 쓰더라도 서로 영향을 덜 받습니다.

아래 명령어로 가상환경을 만듭니다.

python -m venv .venv

macOS나 Linux에서 python 명령어가 안 되면 아래처럼 입력합니다.

python3 -m venv .venv

이제 가상환경을 활성화합니다.

Windows PowerShell 기준입니다.

.venv\Scripts\activate.ps1

Windows 명령 프롬프트라면 아래 명령어를 사용합니다.

.venv\Scripts\activate

macOS, Linux에서는 아래처럼 실행합니다.

source .venv/bin/activate

활성화되면 터미널 앞쪽에 (.venv) 같은 표시가 붙습니다.

(.venv) fastapi-first-api %

이 표시가 보이면 현재 프로젝트 안의 가상환경을 사용 중이라는 뜻입니다.

FastAPI 설치하기

이제 FastAPI를 설치합니다.

2026년 5월 기준 FastAPI 공식 문서는 아래 명령어를 안내하고 있습니다.

pip install "fastapi[standard]"

예전 글에서는 아래처럼 설치하는 방식을 자주 볼 수 있습니다.

pip install fastapi uvicorn

이 방식이 아예 틀린 것은 아닙니다. 다만 처음 시작하는 입장에서는 공식 문서 흐름대로 fastapi[standard]를 설치하는 편이 덜 헷갈립니다.

fastapi[standard]로 설치하면 FastAPI를 실행하고 개발하는 데 필요한 표준 의존성이 함께 설치됩니다. 그래서 이 글에서도 이 방식을 기준으로 진행합니다.

설치가 끝났는지 확인하려면 아래 명령어를 입력합니다.

fastapi --version

버전 정보가 출력되면 설치가 된 것입니다.

첫 API 파일 만들기

이제 main.py 파일을 만듭니다.

프로젝트 폴더 안이 아래와 같은 구조가 되도록 파일을 생성해 주세요.

fastapi-first-api/
├── .venv/
└── main.py

main.py 파일에 아래 코드를 작성하고 저장합니다.

# main.py
from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def read_root():
    return {"message": "Hello FastAPI"}

코드는 짧지만 FastAPI의 기본 구조가 들어 있습니다.

코드에서 봐야 할 부분은 세 가지입니다. - from fastapi import FastAPI: FastAPI 클래스를 가져옵니다. - app = FastAPI(): API 서버 역할을 할 앱 객체를 만듭니다. - @app.get("/"): / 주소로 들어온 GET 요청을 아래 함수와 연결합니다.

마지막 함수는 실제 응답을 반환합니다.

def read_root():
    return {"message": "Hello FastAPI"}

여기서는 Python 딕셔너리를 반환했지만, 브라우저에서는 JSON 형태로 응답이 보입니다.

FastAPI 서버 실행하기

이제 서버를 실행합니다.

터미널에서 main.py가 있는 폴더 위치인지 확인한 뒤 아래 명령어를 입력합니다.

fastapi dev main.py

정상적으로 실행되면 터미널에 서버 주소가 표시됩니다.

보통 아래 주소를 사용합니다.

http://127.0.0.1:8000

브라우저 주소창에 아래 주소를 입력합니다.

http://127.0.0.1:8000

화면에 아래와 비슷한 응답이 나오면 성공입니다.

{
  "message": "Hello FastAPI"
}

이게 첫 번째 API입니다.

아직 데이터베이스도 없고, 로그인도 없고, 복잡한 구조도 없습니다. 하지만 브라우저가 API 서버에 요청을 보내고, FastAPI가 JSON 응답을 돌려주는 흐름은 이미 만들어졌습니다.

자동 API 문서 확인하기

FastAPI의 장점 중 하나는 API 문서를 자동으로 만들어준다는 점입니다.

서버가 실행 중인 상태에서 아래 주소로 접속해 봅니다.

http://127.0.0.1:8000/docs

그러면 Swagger UI 화면이 열립니다.

여기서 / API를 직접 실행해볼 수 있습니다.

**GET /** 항목을 클릭합니다.
**Try it out** 버튼을 누릅니다.
**Execute** 버튼을 누릅니다.
하단의 Response body에서 응답 결과를 확인합니다.

코드로 만든 API를 브라우저 문서 화면에서 바로 테스트할 수 있는 구조입니다.

ReDoc 문서도 기본으로 제공됩니다.

http://127.0.0.1:8000/redoc

/docs는 테스트하기 좋고, /redoc은 문서처럼 읽기 좋습니다. 처음 배울 때는 /docs를 더 자주 보게 됩니다.

경로를 하나 더 추가해보기

이번에는 API를 하나 더 만들어보겠습니다.

main.py를 아래처럼 수정합니다.

# main.py
from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def read_root():
    return {"message": "Hello FastAPI"}


@app.get("/items")
def read_items():
    return {
        "items": [
            {"id": 1, "name": "keyboard"},
            {"id": 2, "name": "mouse"},
        ]
    }

서버가 실행 중이라면 저장 후 다시 확인합니다.

http://127.0.0.1:8000/items

아래처럼 응답이 나옵니다.

{
  "items": [
    {
      "id": 1,
      "name": "keyboard"
    },
    {
      "id": 2,
      "name": "mouse"
    }
  ]
}

그리고 /docs에 다시 들어가면 GET /items API가 자동으로 추가되어 있습니다.

여기서 중요한 점은 문서를 따로 작성하지 않았다는 것입니다. FastAPI가 코드 구조를 보고 API 문서를 만들어줍니다.

쿼리 파라미터 받아보기

API는 보통 클라이언트에서 값을 받아 처리합니다.

이번에는 name 값을 받아서 응답하는 API를 만들어보겠습니다.

main.py를 아래처럼 수정합니다.

# main.py
from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def read_root():
    return {"message": "Hello FastAPI"}


@app.get("/items")
def read_items():
    return {
        "items": [
            {"id": 1, "name": "keyboard"},
            {"id": 2, "name": "mouse"},
        ]
    }


@app.get("/hello")
def say_hello(name: str = "FastAPI"):
    return {"message": f"Hello, {name}"}

브라우저에서 아래 주소로 접속합니다.

http://127.0.0.1:8000/hello

응답은 이렇게 나옵니다.

{
  "message": "Hello, FastAPI"
}

이번에는 주소 뒤에 name 값을 붙여봅니다.

http://127.0.0.1:8000/hello?name=Python

그러면 응답이 바뀝니다.

{
  "message": "Hello, Python"
}

name: str = "FastAPI" 부분이 핵심입니다.

def say_hello(name: str = "FastAPI"):

FastAPI는 함수 인자를 보고 쿼리 파라미터로 처리합니다. name 값이 들어오면 그 값을 사용하고, 없으면 기본값인 "FastAPI"를 사용합니다.

이 부분이 FastAPI를 처음 배울 때 꽤 중요한 감각입니다.

API 주소, 함수 인자, 응답 데이터가 어떻게 연결되는지 이해하면 이후 경로 파라미터, 요청 본문, 데이터 검증도 훨씬 쉽게 이어집니다.

서버와 가상환경 종료하기

개발 서버를 끄려면 터미널에서 아래 키를 누릅니다.

Ctrl + C

서버가 종료되면 브라우저에서 접속해도 응답이 나오지 않습니다.

다시 실행하려면 같은 명령어를 입력하면 됩니다.

fastapi dev main.py

서버를 종료한 뒤 가상환경에서도 빠져나가고 싶다면 아래 명령어를 입력합니다.

deactivate

다시 FastAPI 작업을 하려면 가상환경을 다시 활성화한 뒤 서버를 실행하면 됩니다.

자주 막히는 부분

`fastapi` 명령어를 찾을 수 없다고 나오는 경우

가상환경이 활성화되어 있는지 먼저 확인합니다.

터미널 앞에 (.venv) 표시가 없다면 다시 활성화합니다.

Windows PowerShell:

.venv\Scripts\activate.ps1

macOS, Linux:

source .venv/bin/activate

그래도 안 된다면 FastAPI가 현재 가상환경에 설치되지 않았을 수 있습니다.

pip install "fastapi[standard]"

`python` 명령어가 안 되는 경우

macOS나 Linux에서는 python3를 사용해야 할 수 있습니다.

python3 -m venv .venv

Windows에서는 Python 설치 시 Add python.exe to PATH 옵션이 빠졌을 가능성이 있습니다. 이 경우 Python을 다시 설치하거나 환경 변수를 확인해야 합니다.

브라우저에서 접속이 안 되는 경우

서버가 실행 중인지 확인합니다.

터미널에 서버 실행 로그가 떠 있어야 합니다. 서버를 실행한 터미널을 닫았거나 Ctrl + C로 종료했다면 다시 실행해야 합니다.

fastapi dev main.py

또 주소를 정확히 입력했는지도 확인합니다.

http://127.0.0.1:8000

https가 아니라 http입니다.

8000번 포트가 이미 사용 중이라고 나오는 경우

fastapi dev main.py를 실행했을 때 8000번 포트가 이미 사용 중이라는 에러가 나올 수 있습니다.

이전에 실행한 FastAPI 서버가 아직 종료되지 않았거나, 다른 프로그램이 같은 포트를 사용 중일 때 생깁니다.

먼저 기존 서버가 실행 중인 터미널에서 Ctrl + C를 눌러 종료해 봅니다.

그래도 문제가 계속되면 다른 포트로 실행할 수 있습니다.

fastapi dev main.py --port 8001

이 경우 브라우저에서는 아래 주소로 접속합니다.

http://127.0.0.1:8001

포트 번호만 바뀌었을 뿐, API 코드가 달라지는 것은 아닙니다.

처음에는 여기까지만 해도 충분하다

FastAPI를 처음 배울 때 바로 데이터베이스, 로그인, 배포까지 가면 구조가 복잡해집니다.

먼저 아래 흐름을 확실히 잡는 게 좋습니다.

가상환경 생성
→ FastAPI 설치
→ main.py 작성
→ fastapi dev main.py 실행
→ 브라우저에서 API 응답 확인
→ /docs에서 테스트

FastAPI는 처음 진입 장벽이 낮은 편이지만, 실제 백엔드 개발로 가면 구조 설계가 중요해집니다. 그래서 처음에는 많은 기능을 한 번에 외우기보다, API 하나가 요청을 받고 응답을 돌려주는 흐름부터 손에 익히는 편이 낫습니다.

FastAPI란? Flask·Django 차이와 파이썬 백엔드 선택 기준

notebase — Sat, 23 May 2026 20:03:16 +0900

FastAPI의 개념과 Flask, Django와의 차이를 API 개발, 비동기 처리, 내장 기능, 학습 난이도 기준으로 비교합니다.

FastAPI는 Python으로 API 서버를 만들 때 자주 쓰이는 웹 프레임워크입니다. Flask보다 API 개발에 특화되어 있고, Django보다 가볍게 시작할 수 있다는 점이 핵심입니다.

Python 웹 개발을 찾아보면 보통 세 가지 이름을 많이 보게 됩니다.

FastAPI, Flask, Django.

처음 보면 셋 다 “Python으로 웹 서버 만드는 도구”처럼 보입니다. 맞는 말이긴 합니다. 다만 실제로는 지향점이 꽤 다릅니다.

FastAPI는 API 서버를 빠르게 만들기 좋은 프레임워크에 가깝습니다.
Flask는 작고 유연한 마이크로 프레임워크입니다.
Django는 관리자 페이지, ORM, 인증 같은 기능까지 포함한 풀스택 웹 프레임워크에 가깝습니다.

이 차이를 모르고 시작하면 이런 상황이 생깁니다.

간단한 API 서버를 만들려고 Django를 골랐는데 설정이 무겁게 느껴질 수 있습니다. 반대로 회원 관리, 관리자 페이지, 게시판, 권한 기능까지 필요한 서비스를 Flask나 FastAPI로 만들면 직접 붙여야 할 게 많아집니다.

FastAPI란?

FastAPI는 Python 타입 힌트를 기반으로 API를 만드는 웹 프레임워크입니다. 공식 문서에서도 FastAPI를 “표준 Python 타입 힌트를 기반으로 API를 만들기 위한 현대적이고 빠른 웹 프레임워크”라고 설명합니다.

간단한 예시는 이런 식입니다.

from fastapi import FastAPI

app = FastAPI()

@app.get("/hello")
def hello():
    return {"message": "Hello FastAPI"}

이 코드만으로 /hello API를 만들 수 있습니다.

실행 후 브라우저에서 http://127.0.0.1:8000/docs에 접속하면 자동 생성된 API 문서를 바로 확인할 수 있습니다.
http://127.0.0.1:8000/redoc에서는 ReDoc 형식의 문서도 볼 수 있습니다.

FastAPI의 특징은 단순히 코드가 짧다는 데 있지 않습니다. 중요한 건 요청 데이터 검증, 응답 문서화, API 문서 생성이 자연스럽게 연결된다는 점입니다.

예를 들어 요청 바디를 받을 때 타입을 명확히 적어두면 FastAPI가 그 타입을 기준으로 데이터를 검증하고, OpenAPI 문서도 자동으로 만들어줍니다. FastAPI 공식 문서에 따르면 FastAPI는 OpenAPI 기반 문서를 만들고, /docs와 /redoc 형태의 대화형 문서 화면도 제공합니다.

API를 만들고 나서 프론트엔드 개발자나 앱 개발자에게 “이 API는 이런 값을 받고 이런 값을 반환한다”고 설명해야 할 때 이 차이가 꽤 큽니다.

FastAPI의 핵심은 API 개발 경험이다

FastAPI가 주목받는 이유는 “빠르다” 하나로만 설명하면 부족합니다.

실제로 개발할 때 체감되는 장점은 다음 쪽에 가깝습니다.

기준	FastAPI 특징
주 용도	REST API, 백엔드 API 서버, 마이크로서비스
문법	Python 타입 힌트 중심
문서화	OpenAPI, Swagger UI, ReDoc 자동 생성
데이터 검증	Pydantic 기반 검증
비동기 처리	`async`, `await` 사용에 적합
기본 성격	가볍지만 API 개발에 필요한 기능은 잘 갖춘 편

여기서 중요한 건 타입 힌트입니다.

Python은 원래 동적 타입 언어라서 변수 타입을 강제하지 않습니다. 그런데 API 서버에서는 “이 값은 문자열이어야 한다”, “이 값은 숫자여야 한다”, “이 필드는 필수다” 같은 규칙이 중요합니다.

FastAPI는 이런 규칙을 Python 타입 힌트와 Pydantic 모델로 표현합니다. Pydantic은 타입 힌트를 기반으로 데이터 검증과 직렬화를 처리하는 Python 라이브러리입니다.

from pydantic import BaseModel
from fastapi import FastAPI

app = FastAPI()

class Post(BaseModel):
    title: str
    content: str
    published: bool = True

@app.post("/posts")
def create_post(post: Post):
    return post

위 코드에서 title과 content는 문자열이어야 합니다. published는 Boolean 값이고, 기본값은 True입니다.

이런 구조 덕분에 API 스펙이 코드 안에 자연스럽게 남습니다. 문서를 따로 작성하지 않아도 기본적인 API 문서가 자동으로 만들어지는 것도 이 흐름과 연결됩니다.

FastAPI와 Flask 차이: API 서버 vs 마이크로 프레임워크

Flask는 Python 웹 프레임워크 중에서도 오래 쓰인 편이고, 구조가 단순합니다. 공식 문서에서도 Flask를 “가볍고 빠르게 시작할 수 있으며, 복잡한 애플리케이션으로 확장할 수 있는 WSGI 웹 애플리케이션 프레임워크”라고 설명합니다.

Flask의 기본 코드는 아주 짧습니다.

from flask import Flask

app = Flask(__name__)

@app.route("/")
def home():
    return "Hello Flask"

Flask의 장점은 자유도입니다.

데이터베이스는 뭘 쓸지, 인증은 어떻게 붙일지, 폴더 구조는 어떻게 만들지 개발자가 직접 선택할 수 있습니다. 공식 문서에서도 Flask의 “micro”는 기능이 부족하다는 뜻이 아니라, 핵심을 단순하게 유지하고 확장 가능하게 만든다는 의미라고 설명합니다. Flask는 어떤 데이터베이스를 쓸지 같은 결정을 많이 강제하지 않습니다.

반대로 말하면, 프로젝트가 커질수록 선택해야 할 게 많아집니다.

예를 들어 로그인, 관리자 페이지, ORM, API 문서화, 데이터 검증 같은 기능은 Flask 기본 기능만으로 해결되지 않습니다. 필요한 확장 패키지를 골라 붙여야 합니다.

FastAPI는 Flask보다 API 개발 쪽 기본 경험이 더 정리되어 있습니다. 요청 검증, 응답 모델, 자동 문서화가 처음부터 API 서버 개발 흐름에 맞춰 설계되어 있습니다.

Flask가 더 나은 경우

Flask가 FastAPI보다 항상 부족한 건 아닙니다.

작은 웹 페이지, 간단한 서버, Python 웹의 기본 구조를 배우는 용도라면 Flask가 더 편할 수 있습니다. 코드 흐름이 단순하고, 프레임워크가 많은 결정을 대신하지 않기 때문입니다.

다만 비동기 API 서버를 중심으로 만들 계획이라면 FastAPI 쪽이 더 자연스럽습니다. Flask도 async view를 지원하지만, 공식 문서에서는 Flask가 WSGI 애플리케이션이기 때문에 요청 하나를 처리할 때 워커 하나를 사용하고, async view는 스레드에서 이벤트 루프를 실행하는 방식이라고 설명합니다. Flask 설계 문서에서도 이 방식은 async-first ASGI 프레임워크와 비교해 성능 비용이 있을 수 있다고 안내합니다.

여기서 WSGI는 전통적인 Python 웹 서버 표준에 가깝고, ASGI는 비동기 처리까지 고려한 비교적 현대적인 표준이라고 보면 됩니다. 깊게 외울 필요는 없지만, FastAPI가 비동기 API 서버와 잘 맞는 이유를 이해할 때 중요한 배경입니다.

FastAPI와 Django 차이: 가벼운 API 서버 vs 풀스택 웹 프레임워크

Django는 FastAPI나 Flask보다 더 큰 프레임워크입니다.

Django 공식 사이트는 Django를 “빠른 개발과 깔끔하고 실용적인 디자인을 장려하는 고수준 Python 웹 프레임워크”라고 설명합니다.

Django는 기본 제공 기능이 많습니다.

대표적으로 이런 것들이 있습니다.

기능	Django
ORM	기본 제공
관리자 페이지	기본 제공
인증 시스템	기본 제공
템플릿	기본 제공
폼 처리	기본 제공
마이그레이션	기본 제공
API 개발	Django REST Framework 등을 주로 함께 사용

Django의 강점은 “웹 서비스를 만드는 데 자주 필요한 기능”을 한 세트로 제공한다는 점입니다. 공식 문서에서도 Django 튜토리얼이 모델, 관리자 사이트, 뷰, 템플릿, 폼, 테스트, 정적 파일, 서드파티 패키지 추가 흐름으로 이어집니다.

특히 관리자 페이지는 Django의 큰 장점입니다. Django admin은 기본 프로젝트 템플릿에서 활성화되어 있으며, 모델 데이터를 관리할 수 있는 관리자 인터페이스를 제공합니다.

회원가입, 로그인, 권한, 관리자 화면, 게시글 관리 같은 기능이 필요한 서비스라면 Django가 빠를 수 있습니다.

반면 FastAPI는 이런 풀세트 기능을 기본으로 제공하지 않습니다. 필요한 데이터베이스 라이브러리, 인증 방식, 관리자 도구를 직접 선택해 구성하는 쪽에 가깝습니다.

Django로도 API를 만들 수 있지 않나?

가능합니다.

Django로 API 서버를 만들 때는 보통 Django REST Framework, 줄여서 DRF를 많이 사용합니다. DRF 공식 문서는 Django REST Framework를 “웹 API를 만들기 위한 강력하고 유연한 도구”라고 설명합니다.

즉, “API 서버 = 무조건 FastAPI”는 아닙니다.

이미 Django 프로젝트가 있고, 그 안에 사용자 모델, 관리자 페이지, 권한 체계, 데이터베이스 모델이 잘 잡혀 있다면 DRF로 API를 추가하는 쪽이 더 자연스러울 수 있습니다.

반대로 처음부터 프론트엔드와 백엔드를 분리하고, 백엔드는 JSON API만 제공하는 구조라면 FastAPI가 더 가볍게 느껴질 가능성이 큽니다.

비동기 처리 기준으로 보면?

비동기 처리는 FastAPI를 이야기할 때 자주 나오는 포인트입니다.

FastAPI는 ASGI 기반의 현대적인 Python 웹 개발 흐름과 잘 맞습니다. async, await를 활용해 외부 API 호출, 네트워크 I/O, 비동기 DB 드라이버 같은 작업을 다루기 좋습니다.

Django도 비동기 지원이 있습니다. Django 6.0 공식 문서 기준으로 Django는 ASGI에서 실행할 경우 async view와 async-enabled request stack을 지원합니다. 다만 WSGI 환경에서도 async view가 동작할 수는 있지만 성능상 불리하고, 효율적인 장기 요청 처리에는 제한이 있다고 안내합니다.

Flask도 async view를 지원하지만, 앞에서 말한 것처럼 async-first 구조라기보다는 기존 WSGI 구조와의 호환성을 유지하면서 async를 지원하는 쪽에 가깝습니다.

정리하면 이렇습니다.

기준	FastAPI	Flask	Django
비동기 중심 API 서버	적합	가능하지만 주력은 아님	가능하지만 구조 확인 필요
전통적인 웹 페이지	가능하지만 주력은 아님	적합	매우 적합
관리자 페이지	직접 구성	직접 구성	기본 제공
ORM	직접 선택	직접 선택	기본 제공
API 문서 자동화	강점	확장 필요	DRF 등 추가 도구 활용
학습 난이도	중간	낮은 편	초반 설정은 많은 편

FastAPI를 선택하면 좋은 경우

FastAPI는 이런 상황에서 잘 맞습니다.

프론트엔드는 React, Vue, 앱 등으로 따로 만들고 백엔드는 API만 제공하는 경우
JSON API 서버를 빠르게 만들고 싶은 경우
요청/응답 데이터 검증이 중요한 경우
Swagger UI 같은 API 문서가 자동으로 필요할 때
외부 API 호출, 비동기 작업이 많은 서버를 만들 때
AI 모델 서버, 데이터 처리 API, 마이크로서비스를 만들 때

특히 AI나 데이터 관련 기능을 API로 감싸야 할 때 FastAPI가 자주 선택됩니다. 모델 추론 결과를 JSON으로 반환하거나, 내부 도구용 API를 만드는 식의 작업과 잘 맞습니다.

다만 주의할 점도 있습니다.

FastAPI는 Django처럼 관리자 페이지, ORM, 인증, 권한, 템플릿을 한 번에 제공하지 않습니다. 물론 필요한 라이브러리를 붙이면 구현할 수 있지만, 그 선택과 구조 설계는 개발자 몫입니다.

또 하나는 버전입니다. 2026년 5월 기준 FastAPI 최신 버전은 0.136.1이며, 공식 문서에서는 FastAPI가 아직 0.x 버전대이고 변경 가능성이 있을 수 있으므로 사용하는 버전을 고정하라고 안내합니다.

실무 프로젝트라면 requirements.txt나 pyproject.toml에서 버전을 명확히 고정하는 편이 안전합니다.

Flask를 선택하면 좋은 경우

Flask는 작게 시작하기 좋습니다.

간단한 웹 페이지, 테스트용 서버, 사내에서 잠깐 쓰는 도구, Python 웹의 기본 개념을 배우는 목적이라면 Flask가 부담이 적습니다.

Flask는 많은 걸 강제하지 않습니다. 이 점이 장점이기도 하고 단점이기도 합니다.

작을 때는 편합니다.
커지면 직접 정해야 할 게 많아집니다.

예를 들어 데이터베이스 ORM으로 SQLAlchemy를 쓸지, 인증은 어떤 확장을 쓸지, 프로젝트 구조는 어떻게 나눌지, API 문서는 어떻게 만들지 등을 직접 정해야 합니다.

그래서 Flask는 “작고 단순한 것부터 직접 조립해보고 싶은 경우”에 잘 맞습니다.

Django를 선택하면 좋은 경우

Django는 서비스 전체를 빠르게 만들고 싶을 때 강합니다.

예를 들어 이런 프로젝트라면 Django가 잘 맞습니다.

게시판, 블로그, 커뮤니티
관리자 페이지가 중요한 서비스
회원, 권한, 세션, 폼 처리가 필요한 서비스
데이터베이스 CRUD가 많은 서비스
백오피스, 내부 운영 도구
콘텐츠 관리형 웹사이트

Django는 기본 제공 기능이 많기 때문에 초반에는 배울 게 많아 보입니다. 하지만 일정 규모 이상에서는 오히려 편해질 수 있습니다.

특히 관리자 페이지가 필요한 프로젝트라면 차이가 큽니다. FastAPI나 Flask에서는 관리자 기능을 직접 만들거나 별도 도구를 붙여야 하지만, Django는 admin 기능이 기본 생태계 안에 들어와 있습니다.

다만 2026년 기준으로 Django 최신 버전인 6.0 계열은 Python 3.12, 3.13, 3.14를 지원합니다. 기존 프로젝트가 Python 3.10이나 3.11에 머물러 있다면 Django 6.0으로 올릴 때 호환성을 먼저 확인해야 합니다.

셋 중 하나를 고르는 기준

처음부터 너무 어렵게 생각할 필요는 없습니다.

“내가 만들려는 게 무엇인가?”를 먼저 보면 됩니다.

만들려는 것	추천
간단한 Python 웹 서버	Flask
JSON API 서버	FastAPI
AI 모델 호출 API	FastAPI
관리자 페이지가 필요한 웹 서비스	Django
회원·권한·게시판 중심 서비스	Django
작은 실험용 프로젝트	Flask 또는 FastAPI
프론트엔드 분리형 백엔드	FastAPI
기존 Django 서비스에 API 추가	Django + DRF

여기서 중요한 점은 성능만 보고 고르면 안 된다는 겁니다.

웹 서비스 성능은 프레임워크 하나로 결정되지 않습니다. 데이터베이스 쿼리, 캐시, 배포 구조, 네트워크, ORM 사용 방식, 서버 설정이 더 크게 작용할 때가 많습니다.

FastAPI가 API 개발에 유리한 건 맞지만, 모든 상황에서 무조건 FastAPI가 답은 아닙니다.

입문자는 무엇부터 배우는 게 좋을까?

웹 개발 자체가 처음이라면 Flask로 HTTP 요청과 응답의 기본을 가볍게 익히는 것도 괜찮습니다.

하지만 목표가 “실제 API 서버를 만들고 싶다”라면 FastAPI로 바로 시작해도 됩니다. 타입 힌트, 요청 검증, 자동 문서화 흐름을 처음부터 익힐 수 있기 때문입니다.

Django는 웹 서비스 전체 구조를 배우고 싶을 때 좋습니다. 모델, 뷰, 템플릿, 관리자 페이지, 인증, 권한 같은 요소를 한 프레임워크 안에서 경험할 수 있습니다.

다만 Django를 처음 배울 때는 “왜 이렇게 파일이 많지?”라는 느낌을 받을 수 있습니다. 그건 Django가 많은 기능을 미리 갖춘 프레임워크이기 때문입니다.

FastAPI, Flask, Django 차이 정리

짧게 정리하면 이렇습니다.

FastAPI는 API 서버 중심입니다.
Flask는 작고 유연한 마이크로 프레임워크입니다.
Django는 기능이 많이 포함된 웹 서비스 중심입니다.

FastAPI는 프론트엔드와 백엔드를 분리한 구조, 모바일 앱 API, AI API 서버, 마이크로서비스에 잘 맞습니다.

Flask는 작게 시작하고 직접 조립하면서 배우기 좋습니다.

Django는 회원, 관리자, 데이터베이스, 권한, 백오피스가 필요한 서비스에 강합니다.

실제로는 셋 중 하나가 절대적으로 좋은 게 아닙니다. 프로젝트 성격이 다를 뿐입니다.

API만 만든다면 FastAPI.
작은 웹 서버나 학습용이면 Flask.
서비스 전체를 빠르게 구성해야 한다면 Django.

이 기준으로 보면 선택이 훨씬 쉬워집니다.

바이브 코딩이란? AI가 만든 코드를 그대로 쓰면 안 되는 이유

notebase — Sat, 23 May 2026 18:49:17 +0900

바이브 코딩의 뜻과 최근 AI 코딩 흐름을 정리하고, AI가 만든 코드를 그대로 쓰면 안 되는 이유를 코드 품질, 보안, 유지보수 관점에서 설명합니다.

바이브 코딩은 AI에게 자연어로 원하는 기능을 설명하고, 생성된 코드를 바탕으로 빠르게 개발하는 방식이다. 코드 한 줄을 직접 고민하기보다 “이런 기능 만들어줘”에 가깝게 개발 흐름을 가져간다.

이름 그대로 세부 구현을 한 줄씩 통제하기보다, 전체적인 방향을 잡고 AI가 코드를 만들어가게 두는 방식에 가깝다. 개발자가 모든 코드를 직접 작성하는 대신, 구현의 흐름과 결과물을 조정하는 쪽으로 역할이 이동하는 것이다.

예전에는 개발자가 문법, 라이브러리, 구조를 직접 잡고 AI는 보조 역할을 했다. 지금은 흐름이 조금 달라졌다. Cursor, Claude Code, GitHub Copilot, ChatGPT 같은 도구를 쓰면 파일을 읽고, 코드를 고치고, 테스트 코드까지 제안한다.

그래서 바이브 코딩은 단순히 “AI에게 코드 물어보기”가 아니다. 개발자가 구현 방향을 말하면 AI가 상당한 양의 코드를 만들어내고, 사람은 그 결과를 보고 방향을 조정하는 방식에 가깝다.

이 방식 자체가 나쁜 것은 아니다. 문제는 AI가 만든 코드가 그럴듯해 보인다는 데 있다.

바이브 코딩은 왜 빠르게 퍼졌을까

바이브 코딩이 주목받은 이유는 명확하다. 개발 속도가 빨라진다.

간단한 CRUD, 관리자 페이지, API 연동, 스크립트 자동화, 테스트 코드 초안 같은 작업은 AI가 꽤 잘 처리한다. 특히 이미 구조가 잡힌 프로젝트에서는 “이 패턴을 따라 기능 하나 추가해줘”라고 요청했을 때 결과물이 생각보다 빨리 나온다.

개발자가 문서를 찾고, 예제 코드를 뒤지고, 보일러플레이트를 작성하는 시간을 줄일 수 있다. 이건 분명한 장점이다.

하지만 여기서 착각하기 쉽다.

AI가 코드를 빠르게 만든다는 말과, 그 코드가 제품에 바로 들어가도 된다는 말은 다르다. Stack Overflow 2025 개발자 설문에서도 AI 도구 출력의 정확성을 신뢰하지 않는 개발자가 신뢰하는 개발자보다 더 많았다. 즉, 개발자들은 AI를 쓰고 있지만 동시에 의심하고 있다.

실제로는 “작성 시간”이 줄어든 만큼 “검증 시간”이 생긴다. 이 검증을 건너뛰면 바이브 코딩은 생산성 도구가 아니라 부채 생성기가 된다.

AI 코드는 왜 위험할 수 있을까

AI가 만든 코드는 대체로 그럴듯하다. 함수 이름도 자연스럽고, 주석도 붙어 있고, 에러 처리까지 있는 것처럼 보인다.

그런데 코드는 겉모습보다 맥락이 중요하다.

예를 들어 로그인 기능을 만든다고 해보자. AI는 빠르게 인증 로직을 만들어줄 수 있다. 하지만 실제 서비스에서는 이런 질문이 따라온다.

토큰은 어디에 저장해야 하는가
만료 처리는 어떻게 할 것인가
refresh token은 어떤 조건에서 재발급할 것인가
실패 로그에 민감 정보가 남지 않는가
동일 계정 동시 로그인 정책은 어떻게 할 것인가
모바일 앱과 웹에서 같은 정책을 쓸 것인가

AI가 이런 맥락을 전부 알고 코드를 작성하는 경우는 드물다. 프롬프트에 명시하지 않은 조건은 조용히 빠진다. 프로젝트 내부 규칙을 충분히 제공하지 않았다면 일반적인 예제 코드에 가까운 결과를 낸다.

여기서 중요한 점은, AI가 틀린 코드를 만들 때도 대체로 자신감 있게 만든다는 것이다. 컴파일이 되고, 화면이 뜨고, 기본 케이스가 통과하면 문제 없어 보인다. 하지만 운영 환경에서는 예외 케이스가 더 중요하다.

“동작하는 코드”와 “운영 가능한 코드”는 다르다

바이브 코딩에서 가장 많이 생기는 착각은 이것이다.

“일단 실행되니까 괜찮다.”

개발에서는 실행되는 코드가 출발점이지, 도착점이 아니다. 운영 가능한 코드는 더 많은 조건을 만족해야 한다.

에러가 났을 때 복구 가능한가.
로그가 추적 가능하게 남는가.
권한 체크가 빠지지 않았는가.
데이터가 중복 저장되지 않는가.
장애 상황에서 재시도 로직이 문제를 키우지 않는가.
나중에 다른 개발자가 수정할 수 있는 구조인가.

AI가 만든 코드는 이런 부분에서 약해질 수 있다. 특히 비즈니스 규칙이 복잡한 서비스일수록 더 그렇다.

예를 들어 결제 취소 로직을 AI에게 맡겼다고 해보자. 표면적으로는 cancelPayment() 함수 하나면 끝난다. 하지만 실제로는 PG사 취소, 내부 주문 상태 변경, 쿠폰 복원, 포인트 환불, 재고 복구, 알림 발송, 중복 요청 방지까지 연결된다.

이 중 하나만 빠져도 서비스 장애가 된다.

AI는 코드를 만들 수 있지만, 그 코드가 조직의 정책과 데이터 흐름을 정확히 이해하고 있는지는 별개의 문제다.

AI가 만든 코드를 그대로 쓰면 안 되는 이유

1. 요구사항을 과하게 단순화한다

AI는 사용자가 말한 내용을 바탕으로 코드를 만든다. 문제는 사용자가 요구사항을 완벽하게 설명하지 않는다는 점이다.

사람 개발자라면 “이 부분은 정책이 더 필요해 보이는데요”라고 되묻는다. 반면 AI는 많은 경우 일단 구현한다. 빠르게 결과를 보여주는 쪽으로 움직인다.

그래서 AI 코드는 요구사항의 빈틈을 조용히 추정으로 채운다.

이 추정이 맞으면 편하다. 틀리면 위험하다. 더 큰 문제는 어떤 부분이 추정인지 코드만 보고 바로 알아차리기 어렵다는 점이다.

2. 보안 기본값이 항상 안전하지 않다

AI가 제안하는 코드는 인터넷에 공개된 예제, 일반적인 패턴, 문서의 샘플 코드와 비슷한 형태가 많다. 예제 코드는 이해를 돕기 위한 코드이지, 그대로 운영 서비스에 넣으라고 만든 코드가 아니다.

인증, 권한, 입력값 검증, 파일 업로드, SQL 쿼리, 외부 API 호출 같은 부분은 특히 조심해야 한다.

OWASP는 LLM 기반 애플리케이션에서 프롬프트 인젝션, 안전하지 않은 출력 처리, 공급망 취약점 등을 주요 위험으로 분류한다. AI 코딩 도구를 쓸 때도 이 문제는 그대로 이어진다.

예를 들어 AI가 만든 코드가 사용자 입력값을 그대로 쿼리에 넣거나, 업로드 파일의 확장자만 검사하거나, 관리자 권한 체크를 프론트엔드에서만 처리한다면 겉으로는 기능이 돌아가도 보안상 위험하다.

또 하나 조심할 부분은 AI 패키지 할루시네이션(AI Package Hallucination)이다. AI가 실제로 존재하지 않는 오픈소스 패키지를 그럴듯하게 추천하고, 공격자가 그 이름의 악성 패키지를 선점해 배포하면 공급망 공격으로 이어질 수 있다. 이런 흐름은 슬롭스쿼팅(slopsquatting)이라고도 불린다.

이 문제는 생각보다 현실적이다. 개발자는 AI가 추천한 패키지를 “문서에 있겠지”라고 넘기기 쉽고, 자동완성 도구나 에이전트형 도구가 설치 명령까지 제안하면 검증 없이 의존성이 추가될 수 있다. 특히 npm, PyPI처럼 패키지 설치가 쉬운 생태계에서는 패키지명 확인이 더 중요하다.

보안은 “나중에 한 번 점검”으로 해결하기 어렵다. 처음 구조를 잡을 때부터 들어가야 한다.

3. 프로젝트 컨벤션을 어긴다

실무 프로젝트에는 보이지 않는 규칙이 많다.

폴더 구조, 네이밍 규칙, 에러 응답 형식, 로깅 방식, 트랜잭션 처리 기준, 테스트 작성 방식, API 응답 포맷, 상태 관리 방식 같은 것들이다.

AI는 이런 규칙을 모르면 자기 방식대로 코드를 만든다. 당장은 기능이 추가되지만, 프로젝트 전체 일관성은 깨진다.

처음 한두 번은 괜찮아 보인다. 하지만 비슷한 방식으로 AI 코드를 계속 붙이면 코드베이스 안에 서로 다른 스타일이 섞인다. 이때부터 유지보수 비용이 올라간다.

AI 코드는 새 코드를 만드는 데 강하지만, 기존 코드의 맥락을 정확히 존중하는 데는 사람의 검토가 필요하다.

4. 테스트가 빈약하거나 엉뚱할 수 있다

AI는 테스트 코드도 만들어준다. 이 점은 유용하다.

다만 AI가 만든 테스트가 정말 중요한 케이스를 검증하는지는 따로 봐야 한다. 흔히 발생하는 문제는 “정상 케이스만 테스트하는 코드”다.

예를 들어 회원가입 기능이라면 정상 가입만 테스트하는 것이 아니라 이미 가입된 이메일, 잘못된 이메일 형식, 비밀번호 정책 위반, 인증 메일 발송 실패, DB 저장 실패 같은 케이스도 봐야 한다.

AI가 만든 테스트가 많다고 해서 안전한 것은 아니다. 테스트 개수보다 중요한 건 어떤 위험을 검증하느냐다.

5. 리뷰할 코드 양이 늘어난다

AI를 쓰면 코드 생산량이 늘어난다. 이 자체는 장점이다. 하지만 팀에서 리뷰할 수 있는 양은 무한하지 않다.

짧은 시간에 큰 PR이 만들어지고, 그 안에 AI가 생성한 파일이 많이 섞이면 리뷰어는 피로해진다. 사람이 직접 쓴 코드보다 의도를 파악하기 어려운 경우도 있다. 작성자는 “AI가 만든 코드라 나도 자세히는 모른다”는 상태가 될 수 있다.

이건 위험한 신호다.

코드의 최종 책임은 AI가 아니라 커밋한 사람에게 있다. 내가 설명하지 못하는 코드는 내가 소유한 코드라고 보기 어렵다.

바이브 코딩을 버려야 할까

그럴 필요는 없다.

바이브 코딩은 잘 쓰면 강력하다. 특히 다음 작업에서는 꽤 유용하다.

반복적인 보일러플레이트 작성
간단한 내부 도구 초안
테스트 코드 초안 생성
기존 코드 설명 요청
리팩터링 방향 탐색
문서 기반 API 사용 예제 작성
작은 스크립트 자동화
프로토타입 제작

문제는 “AI가 만들었으니 빠르게 배포하자”는 태도다. 바이브 코딩은 개발자를 없애는 방식이 아니라, 개발자의 검토 지점을 바꾸는 방식에 가깝다.

예전에는 직접 코드를 쓰는 능력이 중요했다. 지금은 코드를 읽고, 의심하고, 구조를 판단하고, 위험을 찾아내는 능력이 더 중요해지고 있다.

Google Cloud의 2025 DORA 보고서 소개 자료도 AI 도입이 넓게 확산됐지만, 소프트웨어 전달 안정성과는 여전히 부정적 관계가 있다고 설명한다. AI를 쓴다고 자동으로 더 좋은 개발 조직이 되는 것은 아니다.

AI 코드 검토할 때 봐야 할 기준

AI가 만든 코드를 받았다면 바로 붙여넣기보다 아래 기준으로 보는 게 낫다.

내가 설명할 수 있는 코드인가

가장 먼저 볼 것은 이해 여부다.

이 함수가 왜 필요한지, 어떤 입력을 받고, 어떤 상태를 바꾸며, 실패했을 때 어떻게 되는지 설명할 수 있어야 한다.

설명하지 못하는 코드는 아직 내 코드가 아니다. 그 상태로 커밋하면 나중에 장애가 났을 때 원인 분석도 어려워진다.

기존 구조와 맞는가

AI가 새 패턴을 만들고 있지는 않은지 봐야 한다.

기존 프로젝트에서 에러를 AppError로 감싸고 있는데 AI가 갑자기 일반 Error를 던진다면 문제가 된다. API 응답 형식이 정해져 있는데 AI가 다른 포맷을 만들었다면 나중에 프론트엔드나 클라이언트 앱에서 깨질 수 있다.

코드가 맞는지만 보지 말고, 프로젝트 안에서 자연스러운지도 봐야 한다.

실패 케이스가 처리되어 있는가

정상 흐름만 보면 대부분의 코드는 그럴듯하다.

실제로 봐야 할 것은 실패 흐름이다.

외부 API가 timeout이면 어떻게 되는가.
DB 저장 중 예외가 나면 롤백되는가.
중복 요청이 들어오면 한 번만 처리되는가.
권한 없는 사용자가 요청하면 어디서 막히는가.
로그에 개인정보가 남지는 않는가.

이 질문에 답하지 못하면 아직 운영 코드로 보기 어렵다.

테스트가 위험을 검증하는가

AI가 만든 테스트는 초안으로는 좋다. 하지만 테스트가 실제 위험을 잡는지는 사람이 판단해야 한다.

단순히 “성공한다”를 확인하는 테스트보다 “실패해야 할 때 실패하는지”를 보는 테스트가 더 중요하다.

권한이 없으면 실패해야 한다.
잘못된 입력이면 저장되지 않아야 한다.
중복 요청이면 두 번 처리되지 않아야 한다.
외부 연동 실패 시 내부 상태가 어긋나지 않아야 한다.

이런 테스트가 있어야 AI 코드도 어느 정도 신뢰할 수 있다.

실무에서는 이렇게 쓰는 게 낫다

바이브 코딩을 실무에 쓸 때는 AI에게 “전체를 알아서 만들어줘”보다 작업 범위를 좁히는 편이 낫다.

예를 들어 이렇게 요청하는 것이다.

기존 UserService 패턴을 유지해서 비밀번호 변경 기능을 추가해줘.
단, 아래 조건을 지켜줘.

- 현재 비밀번호 검증 필요
- 새 비밀번호는 기존 비밀번호와 같으면 안 됨
- 실패 응답은 기존 AppError 형식 사용
- DB 업데이트는 transaction 안에서 처리
- 테스트는 성공 케이스보다 실패 케이스 중심으로 작성

이렇게 주면 AI가 추정해야 하는 부분이 줄어든다.

반대로 아래처럼 요청하면 위험하다.

비밀번호 변경 기능 만들어줘.

너무 짧은 프롬프트는 빠른 결과를 주지만, 그만큼 많은 결정을 AI에게 넘긴다. 바이브 코딩의 핵심은 프롬프트를 길게 쓰는 것이 아니라, AI가 마음대로 결정하면 안 되는 부분을 명확히 고정하는 것이다.

개인과 팀은 무엇을 다르게 봐야 할까

개인 개발자라면 AI가 만든 코드를 붙여넣기 전에 “실패 케이스와 보안상 위험을 찾아줘”라고 한 번 더 물어보는 습관이 필요하다. AI에게 코드를 만들게 하는 것만큼, AI에게 자기 코드의 약점을 지적하게 하는 것도 중요하다.

팀 단위로 쓴다면 더 중요하다. AI 생성 코드에 대한 PR 기준, 의존성 검증 방식, 테스트 요구사항을 팀 규칙으로 정해두지 않으면 생산성 향상이 그대로 코드 부채로 바뀔 수 있다.

팀에서 바로 적용해 볼 수 있는 AI 코드 리뷰 규칙

의존성 검증: AI가 추가하거나 제안한 패키지는 공식 저장소와 다운로드 이력을 확인한다.
핵심 로직 리뷰: 인증, 결제, 권한, 개인정보 처리 코드는 AI가 작성했더라도 사람이 직접 한 줄씩 확인한다.
실패 중심 테스트: AI가 작성한 테스트는 정상 작동보다 예외 케이스를 제대로 검증하는지 우선 확인한다.
PR 단위 쪼개기: 큰 PR 하나보다 작은 기능 단위로 나눠 리뷰한다.
코드 소유권 확인: 작성자가 설명하지 못하는 코드는 병합하지 않는다.

이 정도만 정해도 바이브 코딩의 위험은 꽤 줄어든다.

바이브 코딩은 개발자의 실력을 더 중요하게 만든다

겉으로 보면 AI가 개발자의 일을 대신하는 것처럼 보인다. 하지만 실제로는 개발자의 판단이 더 중요해진다.

AI가 코드를 많이 만들수록 사람은 더 많은 코드를 검토해야 한다.
AI가 빠르게 기능을 붙일수록 사람은 구조가 망가지지 않는지 봐야 한다.
AI가 그럴듯한 답을 낼수록 사람은 틀린 부분을 더 잘 찾아야 한다.

그래서 바이브 코딩 시대의 개발자는 단순히 코드를 많이 치는 사람이 아니라, 코드의 방향과 품질을 판단하는 사람이 된다.

AI가 만든 코드를 그대로 쓰면 안 되는 이유도 여기에 있다. AI의 능력이 부족해서가 아니다. 좋은 소프트웨어는 잘 돌아가는 코드 조각을 이어 붙인 것만으로 완성되지 않는다.

서비스 정책, 사용자 데이터, 보안, 장애 대응, 팀의 유지보수 방식까지 함께 맞아야 한다.

바이브 코딩은 빠른 출발점으로 쓰기 좋다. 다만 최종 판단은 사람이 해야 한다.

AI에게 코드를 맡길 수는 있다.
하지만 책임까지 맡길 수는 없다.

Codex란? ChatGPT와 다른 개발용 AI 도구 이해하기

notebase — Sat, 23 May 2026 13:34:27 +0900

Codex가 무엇인지, ChatGPT와 어떤 점이 다른지 개발 작업 흐름 기준으로 정리했습니다. Codex CLI, 코드 수정, 리뷰, 테스트, 보안 주의사항까지 개발자가 알아야 할 핵심을 설명합니다.

Codex는 OpenAI가 제공하는 개발용 AI 코딩 에이전트다. ChatGPT가 코딩 질문에 답하고 개념을 설명해주는 도구에 가깝다면, Codex는 실제 프로젝트 안에서 코드를 읽고, 수정하고, 실행하는 흐름까지 도와주는 도구에 가깝다.

처음 들으면 “그냥 코딩 잘하는 ChatGPT 아닌가?” 싶을 수 있다.

틀린 말은 아니지만, 정확히는 조금 다르다.
ChatGPT가 대화창에서 개발을 도와주는 방식이라면, Codex는 개발 환경 안으로 들어와서 작업을 함께 처리하는 쪽에 더 가깝다.

여기서 말하는 Codex는 과거 OpenAI API에서 제공되던 단순 코드 생성 모델을 뜻하는 것이 아니다.
2026년 5월 기준으로는 Codex CLI, Codex app, IDE 연동처럼 개발 환경 안에서 동작하는 AI 코딩 에이전트 환경을 기준으로 설명한다.

중요한 차이는 “코딩을 더 잘하느냐”가 아니라, 어디에서 어떤 방식으로 개발을 돕느냐에 있다.

Codex는 무엇인가

Codex는 개발자가 요청한 작업을 바탕으로 코드 작성, 수정, 리뷰, 테스트 같은 일을 도와주는 AI 코딩 에이전트다.

OpenAI 공식 문서에서도 Codex는 소프트웨어 개발을 위한 코딩 에이전트라고 설명한다. 코드 작성, 낯선 코드베이스 이해, 코드 리뷰 같은 작업을 도울 수 있는 도구에 가깝다.

예를 들면 이런 작업을 맡길 수 있다.

기존 코드 구조 파악
새로운 기능 구현
버그 원인 분석
테스트 코드 작성
리팩터링
Pull Request 리뷰
터미널 명령 실행
프로젝트 파일 수정

여기서 중요한 건 Codex가 단순히 코드 조각만 보여주는 도구가 아니라는 점이다.

일반적인 ChatGPT 사용 방식은 이렇다.

이 에러가 왜 나는지 설명해줘.

그러면 ChatGPT는 원인을 설명하고, 예시 코드를 제안해준다.

반면 Codex에는 이런 식으로 요청할 수 있다.

이 프로젝트에서 로그인 후 리다이렉트가 안 되는 원인을 찾아서 수정해줘.
관련 테스트도 같이 확인해줘.

이 요청은 단순한 코드 작성이 아니다.
프로젝트 구조를 보고, 관련 파일을 찾고, 실제 수정이 필요한 부분을 판단해야 한다.

Codex는 이런 작업 흐름에 맞춰 만들어진 개발용 AI 도구라고 보면 된다.

ChatGPT와 Codex의 가장 큰 차이

ChatGPT도 코딩을 잘한다.
함수 하나를 작성하거나, 에러 메시지를 해석하거나, 새로운 기술 개념을 이해하는 용도로는 충분히 유용하다.

다만 실제 프로젝트 작업으로 들어가면 상황이 달라진다.

구분	ChatGPT	Codex
기본 목적	범용 AI 대화와 개발 상담	개발 작업 수행
사용 방식	대화창에 질문하고 답변 받기	프로젝트 안에서 작업 맡기기
코드 이해	사용자가 붙여넣은 코드 중심	파일 구조와 코드베이스를 함께 참고
코드 수정	수정 방향과 예시 코드 제안	실제 파일을 읽고 변경 가능
명령 실행	일반 대화창에서는 설명·제안 중심	Codex CLI에서 터미널 기반 작업 가능
적합한 상황	개념 설명, 코드 질문, 설계 상담	기능 구현, 버그 수정, PR 리뷰, 테스트 작성

한 줄로 보면
ChatGPT는 개발 방향을 정리할 때 편하고, Codex는 실제 프로젝트 안에서 코드를 고치고 확인하는 작업에 더 잘 맞는다.

예를 들어 이런 질문은 ChatGPT에 더 잘 맞는다.

React에서 useEffect가 두 번 실행되는 이유가 뭐야?

이 경우에는 개념 설명이 필요하다.
굳이 프로젝트 전체를 볼 필요는 없다.

반대로 이런 요청은 Codex에 더 잘 맞는다.

이 프로젝트에서 회원가입 폼의 유효성 검사를 추가해줘.
기존 코드 스타일을 유지하고, 테스트도 같이 수정해줘.

이 작업은 실제 파일 구조를 봐야 한다.
폼 컴포넌트가 어디 있는지, 유효성 검사 방식이 기존에 어떻게 되어 있는지, 테스트는 어떤 방식으로 작성되어 있는지 확인해야 한다.

이런 맥락을 따라가면서 작업하는 데 Codex가 더 적합하다.

Codex CLI는 무엇인가

Codex는 여러 방식으로 사용할 수 있다.
대표적으로는 Codex CLI, Codex app, IDE 확장, Codex web 같은 형태가 있다.

그중 개발자에게 특히 익숙한 방식은 Codex CLI다.
Codex CLI는 터미널에서 실행하는 방식이라, 기존 개발 흐름을 크게 바꾸지 않고도 AI에게 코드 수정이나 테스트 실행을 맡길 수 있다.

터미널에서 Codex를 실행하고 작업을 요청하는 흐름은 아래처럼 이해하면 된다.

$ codex
> 사용하지 않는 함수를 찾아 정리해줘. 테스트가 깨지지 않는지도 확인해줘.

그러면 Codex는 단순히 “이렇게 하면 됩니다”라고 답하는 데서 끝나지 않는다.
선택한 디렉터리 안의 프로젝트 파일을 살펴보고, 수정할 부분을 찾고, 필요한 경우 명령을 실행하면서 작업을 이어갈 수 있다.

이 차이가 꽤 크다.

ChatGPT는 보통 개발자가 가져온 정보를 바탕으로 답변한다.
Codex CLI는 개발자가 열어둔 프로젝트 안에서 필요한 정보를 직접 찾아가며 작업한다.

ChatGPT로도 코딩할 수 있는데 왜 Codex가 필요할까

작은 질문은 ChatGPT가 더 빠르고 편하다.

예를 들어 이런 질문은 ChatGPT만으로 충분하다.

파이썬에서 리스트 컴프리헨션이 뭐야?

JWT와 세션 인증 차이를 알려줘.

이 SQL 쿼리가 느린 이유를 설명해줘.

이런 질문은 개념 이해가 목적이다.
프로젝트 전체 맥락이 없어도 답변할 수 있다.

하지만 실제 개발에서는 코드가 여러 파일에 나뉘어 있다.

로그인 기능 하나만 봐도 API, 라우터, 상태 관리, UI 컴포넌트, 테스트 코드가 얽혀 있을 수 있다.
이걸 전부 ChatGPT에 복사해서 붙여넣는 방식은 금방 불편해진다.

또 어떤 파일을 보여줘야 하는지도 개발자가 직접 판단해야 한다.

Codex는 이 부분에서 장점이 있다.
프로젝트 구조를 보고, 관련 파일을 찾고, 기존 코드 스타일에 맞춰 작업을 이어갈 수 있기 때문이다.

실제로는 “AI가 코드를 잘 짜는가”만큼이나 내 프로젝트 맥락을 잘 따라오는가가 중요하다.

아무리 깔끔한 코드라도 기존 구조와 맞지 않으면 유지보수하기 어렵다.
Codex 같은 개발용 AI 도구는 이 문제를 줄이는 방향으로 설계되어 있다.

Codex app과 IDE 연동은 언제 쓸까

Codex CLI가 터미널 중심이라면, Codex app은 여러 작업을 한 곳에서 관리하는 쪽에 가깝다.

OpenAI 공식 문서 기준으로 Codex app은 여러 Codex 작업 스레드를 병렬로 다루고, worktree와 Git 기능을 함께 활용할 수 있는 데스크톱 경험으로 소개된다.

즉, 단순히 터미널 한 곳에서 작업하는 것보다 여러 작업을 나눠서 관리하고 싶을 때 Codex app이 더 편할 수 있다.

예를 들면 이런 상황이다.

버그 수정 작업과 리팩터링 작업을 나눠서 진행할 때
여러 에이전트 작업 결과를 비교하고 싶을 때
변경된 코드를 리뷰하고 Git 흐름과 함께 보고 싶을 때
프로젝트별 작업 스레드를 따로 관리하고 싶을 때

IDE 연동은 조금 더 익숙한 개발 환경 안에서 Codex를 쓰고 싶을 때 유용하다.
VS Code 같은 에디터 안에서 코드와 AI 작업 흐름을 함께 보고 싶다면 IDE 연동 방식이 더 자연스러울 수 있다.

처음 써본다면 Codex CLI로 작은 작업부터 시작하는 편이 부담이 적다.
이후 작업이 많아지고 여러 흐름을 나눠 관리해야 한다면 Codex app이나 IDE 연동을 살펴보면 된다.

Codex는 코드 리뷰에도 활용할 수 있다

Codex는 코드 작성뿐 아니라 리뷰에도 사용할 수 있다.

예를 들어 Pull Request를 올린 뒤, 변경된 코드에서 문제가 될 만한 부분을 확인하는 식이다.

혼자 개발하다 보면 놓치기 쉬운 부분이 있다.

예외 처리가 빠진 부분
테스트가 없는 변경
인증이나 권한 처리 문제
불필요하게 복잡한 코드
기존 코드 스타일과 맞지 않는 부분

Codex 리뷰를 활용하면 최소한 한 번 더 검토하는 단계를 만들 수 있다.

다만 AI 리뷰를 사람 리뷰의 완전한 대체로 보면 안 된다.
특히 보안, 결제, 개인정보, 권한 처리처럼 민감한 부분은 반드시 사람이 직접 확인해야 한다.

Codex는 검토를 도와주는 도구이지, 최종 책임을 대신 져주는 도구는 아니다.

Codex를 쓸 때 주의할 점

Codex는 프로젝트 파일을 읽고 수정할 수 있다.
이 점이 편리하지만, 동시에 조심해야 할 부분이기도 하다.

가장 먼저 봐야 할 것은 접근 범위다.

Codex CLI를 사용할 때는 실행 위치가 중요하다.
현재 열어둔 디렉터리를 기준으로 파일을 읽고 수정할 수 있기 때문에, 민감한 파일이 있는 폴더에서는 접근 범위를 먼저 확인하는 편이 좋다.

예를 들면 이런 파일이다.

.env
.env.local
credentials.json
private-key.pem
service-account.json

여기서 오해하기 쉬운 부분이 있다.

.gitignore에 넣었다고 해서 AI 도구가 해당 파일을 못 읽는 것은 아니다.
.gitignore는 Git에 올리지 않기 위한 설정이지, AI 도구의 접근을 막는 보안 설정은 아니다.

따라서 Codex를 사용할 때는 실행 위치, 접근 가능한 폴더, 민감 파일 관리 방식을 따로 신경 써야 한다.

또 하나는 변경 결과 검토다.

Codex가 코드를 수정했다고 해서 바로 배포하면 안 된다.
반드시 변경된 diff를 확인하고, 테스트를 실행하고, 예상하지 못한 수정이 들어갔는지 봐야 한다.

특히 아래 작업은 더 신중하게 다루는 편이 좋다.

인증/인가 로직 변경
결제 관련 코드 변경
데이터 삭제 또는 마이그레이션
배포 스크립트 수정
보안 정책 변경
대량 파일 수정

Codex는 개발 속도를 높여줄 수 있다.
하지만 최종 판단은 여전히 개발자의 몫이다.

어떤 상황에서 Codex를 쓰면 좋을까

Codex는 단순 질문보다 실제 작업에 더 잘 맞는다.

아래처럼 범위가 비교적 명확한 요청에 특히 유용하다.

이 API 응답 타입에 맞춰 프론트엔드 타입 정의를 수정해줘.

기존 Button 컴포넌트 스타일을 유지하면서 loading 상태를 추가해줘.

사용하지 않는 함수를 찾아 정리하고, 테스트가 깨지지 않는지 확인해줘.

이 PR에서 위험해 보이는 변경이 있는지 리뷰해줘.

반대로 이런 질문은 ChatGPT가 더 편하다.

OAuth가 뭔지 설명해줘.

Next.js App Router와 Pages Router 차이를 알려줘.

이 에러 메시지가 의미하는 게 뭐야?

정리하면 역할이 조금 다르다.

ChatGPT는 이해하고 판단할 때 좋다.
Codex는 실제 프로젝트를 고치고 반복 작업을 줄일 때 좋다.

둘 중 하나만 골라야 하는 관계는 아니다.
오히려 같이 쓰는 편이 더 자연스럽다.

먼저 ChatGPT로 방향을 잡고, Codex로 실제 코드 작업을 맡기는 식이다.

개발자가 보는 Codex의 핵심 의미

Codex를 단순한 코드 생성기로 보면 조금 아쉽다.

핵심은 개발 환경에 들어온 AI 에이전트라는 점이다.

예전의 AI 코딩 도구는 자동완성에 가까웠다.
개발자가 코드를 치면 다음 줄을 예측하거나, 함수 일부를 채워주는 방식이었다.

Codex는 그보다 한 단계 더 나아간다.

파일을 읽고, 수정하고, 명령을 실행하고, 리뷰까지 이어갈 수 있다.
개발자가 하던 작은 반복 작업을 하나의 흐름으로 처리하려는 도구에 가깝다.

물론 이 말이 개발자를 대체한다는 뜻은 아니다.

오히려 개발자의 역할이 조금 바뀐다고 보는 편이 맞다.
모든 코드를 직접 치는 시간은 줄어들 수 있지만, 요구사항을 정확히 설명하고, 결과를 검토하고, 위험한 변경을 걸러내는 능력은 더 중요해진다.

Codex를 잘 쓰려면 AI에게 모든 걸 맡기기보다 작업을 잘게 나누는 편이 좋다.

예를 들면 이런 식이다.

이 파일의 역할을 먼저 설명해줘.

이 함수에 테스트를 추가해줘.

이 컴포넌트의 중복 코드를 줄여줘.

변경한 부분만 요약하고, 위험한 부분이 있으면 알려줘.

이렇게 요청하면 결과를 검토하기 쉽고, AI가 엉뚱한 방향으로 크게 수정할 가능성도 줄어든다.

Codex와 ChatGPT, 무엇을 써야 할까

기준은 어렵지 않다.

개념을 알고 싶으면 ChatGPT가 편하다.
실제 프로젝트를 수정하고 싶으면 Codex가 더 잘 맞는다.

예를 들어 “JWT 인증이 뭔지 알려줘”는 ChatGPT에 묻는 게 좋다.
반면 “이 프로젝트의 JWT 만료 처리 버그를 찾아서 수정해줘”는 Codex에 맡기는 쪽이 자연스럽다.

처음부터 큰 작업을 맡기기보다는 작은 작업부터 시작하는 편이 좋다.
작은 수정, 테스트 추가, 코드 설명, 리팩터링처럼 결과를 확인하기 쉬운 작업부터 써보면 감을 잡기 쉽다.

Codex는 개발자를 대신하는 도구라기보다, 프로젝트 안에서 함께 움직이는 보조 개발자에 가깝다.
ChatGPT가 생각을 정리하는 도구라면, Codex는 그 생각을 실제 코드 작업으로 옮기는 도구에 가깝다.

이 차이를 알고 쓰면 두 도구의 역할이 훨씬 분명해진다.

Claude Code란? 터미널에서 사용하는 AI 코딩 도구 개념 정리

notebase — Sat, 23 May 2026 13:03:19 +0900

Claude Code가 무엇인지, 일반 AI 챗봇·코드 자동완성 도구와 무엇이 다른지, 터미널에서 파일 수정과 명령 실행까지 돕는 AI 코딩 에이전트의 개념을 정리합니다.

Claude Code는 Anthropic이 제공하는 AI 코딩 도구입니다. 단순히 코드를 추천해주는 챗봇이 아니라, 개발자가 작업 중인 코드베이스를 읽고, 파일을 수정하고, 터미널 명령어 실행 흐름까지 도와주는 AI 코딩 에이전트에 가깝습니다.

기존 AI 챗봇은 보통 이런 방식으로 사용했습니다.

코드를 복사합니다.
질문을 입력합니다.
답변을 다시 복사해서 IDE나 터미널에 붙여넣습니다.
에러가 나면 다시 설명합니다.

Claude Code는 이 중간 과정을 줄이는 데 초점이 있습니다. 개발자가 터미널에서 “이 버그 원인 찾아줘”, “테스트 실패 이유를 분석해줘”, “이 기능을 추가하기 전에 수정 범위를 정리해줘”처럼 요청하면, Claude가 프로젝트 파일을 읽고 관련 맥락을 바탕으로 작업을 도와줄 수 있습니다.

2026년 5월 기준 Anthropic 공식 문서에서는 Claude Code를 코드베이스를 읽고, 파일을 편집하고, 명령을 실행하며, 개발 도구와 통합되는 agentic coding tool로 설명합니다.

Claude Code는 왜 터미널 AI 코딩 도구라고 불릴까?

Claude Code의 핵심 특징은 개발자가 이미 사용하는 터미널 안에서 동작한다는 점입니다.

실제 개발 작업은 IDE 안에서만 끝나지 않습니다. Git 명령어를 실행하고, 패키지를 설치하고, 테스트를 돌리고, 빌드 로그를 확인하고, 에러 메시지를 추적합니다. 이런 작업은 대부분 터미널과 연결되어 있습니다.

Claude Code는 바로 이 흐름 안에 들어옵니다.

프로젝트 폴더에서 Claude Code를 실행한 뒤 다음처럼 요청할 수 있습니다.

이 프로젝트의 전체 구조를 설명해줘.
주요 디렉터리와 실행 흐름을 초보자 기준으로 정리해줘.

또는 이렇게 요청할 수도 있습니다.

로그인 실패 원인을 찾아줘.
관련 파일을 확인하고, 바로 수정하지 말고 수정 계획을 먼저 설명해줘.

여기서 중요한 점은 Claude Code가 단순히 “터미널에서 대화하는 AI”가 아니라는 것입니다. 프로젝트 파일을 읽고, 필요한 경우 파일 수정안을 만들고, 테스트나 빌드 같은 명령 실행 흐름까지 함께 다룰 수 있습니다.

즉, Claude Code는 터미널용 챗봇이라기보다 읽기·수정·실행 도구를 가진 코딩 에이전트에 가깝습니다.

Claude Code와 일반 AI 챗봇의 차이

Claude Code를 이해하려면 먼저 Claude 웹 채팅이나 ChatGPT 같은 일반 AI 챗봇과 비교해보는 것이 좋습니다.

구분	일반 AI 챗봇	Claude Code
사용 위치	웹, 앱	터미널, IDE 등 개발 환경
코드 이해 방식	사용자가 붙여넣은 코드 중심	프로젝트 파일을 직접 읽으며 파악
작업 범위	설명, 코드 예시, 문제 해결 조언	파일 수정, 명령 실행, 테스트 보조, Git 작업 보조
개발 흐름	복사·붙여넣기 필요	터미널 작업 흐름 안에서 사용
성격	코딩 상담 도구	코딩 에이전트 도구

일반 AI 챗봇은 설명에 강합니다. 코드 예시를 만들거나 에러 메시지를 해석하는 데도 유용합니다. 하지만 실제 프로젝트에 적용하려면 개발자가 코드를 복사하고, 붙여넣고, 수정하고, 다시 테스트해야 합니다.

Claude Code는 이 흐름을 줄이는 방향입니다. 프로젝트 구조를 확인하고, 여러 파일을 함께 읽고, 필요한 수정 범위를 제안할 수 있습니다. 경우에 따라 파일 변경과 명령 실행까지 개발 흐름 안에서 이어갈 수 있습니다.

다만 Claude Code도 최종 판단을 대신해주는 도구는 아닙니다. 제안된 변경 사항을 검토하고, 실제 반영 여부를 결정하는 책임은 여전히 개발자에게 있습니다.

Claude Code와 코드 자동완성 도구의 차이

GitHub Copilot 같은 코드 자동완성 도구는 개발자가 작성 중인 코드의 다음 줄이나 다음 블록을 추천하는 방식에 가깝습니다.

예를 들어 자동완성 도구는 이런 상황에 강합니다.

함수 이름과 일부 코드를 작성했을 때 다음 코드를 추천

반면 Claude Code는 작업 단위가 더 큽니다.

회원가입 API에 이메일 인증 단계를 추가하려고 해.
현재 구조를 먼저 파악하고, 수정해야 할 파일과 테스트 계획을 설명한 뒤 진행해줘.

자동완성 도구가 “지금 쓰는 코드의 다음 부분”을 돕는다면, Claude Code는 “개발 작업의 흐름”을 돕는 쪽에 가깝습니다.

그래서 Claude Code는 다음과 같은 작업에 더 잘 맞습니다.

기존 프로젝트 구조 파악
여러 파일에 걸친 기능 수정
버그 원인 추적
테스트 코드 작성
리팩터링 계획 수립
Git 변경 사항 요약
문서 업데이트

Claude Code의 핵심은 실행 권한에 있다

Claude Code를 기존 CLI 챗봇과 구분하는 중요한 지점은 도구 사용 권한입니다.

터미널에서 AI와 대화만 하는 도구라면, 결국 답변을 사람이 복사해서 실행해야 합니다. 하지만 Claude Code는 개발 작업에 필요한 도구를 사용할 수 있도록 설계되어 있습니다.

예를 들어 다음과 같은 흐름이 가능합니다.

테스트가 실패하는 원인을 찾아줘.
관련 파일을 확인하고, 필요한 경우 수정한 뒤 `npm test`로 다시 확인해줘.

이 요청에서 Claude Code는 단순히 테스트 실패 원인을 추측하는 데 그치지 않습니다. 프로젝트 파일을 읽고, 실패 원인을 추적하고, 수정안을 만들고, 테스트 실행 흐름까지 이어갈 수 있습니다.

다만 모든 작업을 자유롭게 실행한다는 뜻은 아닙니다. Claude Code는 권한 기반 구조를 사용합니다. 공식 보안 문서에 따르면 기본적으로 읽기 중심 권한을 사용하며, 파일 편집이나 테스트 실행, 명령 실행처럼 추가 작업이 필요할 때는 사용자의 명시적 승인을 요청합니다.

이 구조는 장점과 주의점이 함께 있습니다.

장점은 개발자가 반복 작업을 줄일 수 있다는 점입니다. 반대로 주의할 점은 AI가 실행하려는 명령과 변경하려는 파일을 개발자가 직접 확인해야 한다는 점입니다.

특히 다음과 같은 작업은 더 신중하게 검토해야 합니다.

인증·인가 로직 수정
결제 관련 코드 수정
데이터 삭제 또는 마이그레이션
배포 스크립트 변경
인프라 설정 변경
개인정보 처리 코드 수정

Claude Code로 파일을 수정했다면 바로 커밋하지 말고 git diff로 변경 내용을 확인하는 습관이 필요합니다.

git diff

AI가 만든 코드는 초안으로 보고, 최종 리뷰는 사람이 한다는 기준을 세워두는 편이 안전합니다.

Claude Code로 할 수 있는 일

Claude Code는 프로젝트 안에서 여러 개발 작업을 보조할 수 있습니다.

1. 코드베이스 구조 파악

새 프로젝트를 열었을 때 가장 먼저 막히는 부분은 구조 파악입니다.

이 프로젝트가 어떤 구조로 되어 있는지 설명해줘.
주요 폴더와 실행 흐름을 정리해줘.

Claude Code는 프로젝트 파일을 읽고 어떤 폴더가 어떤 역할을 하는지 설명할 수 있습니다. 낯선 코드베이스에 합류했을 때 유용합니다.

2. 버그 원인 분석

에러 메시지만 보고 원인을 찾기 어려울 때도 활용할 수 있습니다.

이 테스트가 실패하는 원인을 찾아줘.
실패 로그를 보고 관련 파일을 확인한 뒤 수정 방향을 제안해줘.

단순히 에러 메시지를 해석하는 수준을 넘어, 관련 파일을 함께 확인하면서 원인을 추적할 수 있다는 점이 장점입니다.

3. 리팩터링 계획 수립

여러 파일에 걸친 리팩터링도 Claude Code의 활용 범위에 들어갑니다.

중복된 API 응답 처리 로직을 공통 함수로 분리하고 싶어.
기존 동작을 바꾸지 않는 선에서 수정 계획을 먼저 작성해줘.

리팩터링은 한 파일만 고치는 작업이 아닌 경우가 많습니다. Claude Code는 코드베이스의 여러 파일을 함께 읽을 수 있기 때문에 수정 범위를 정리하는 데 도움이 됩니다.

4. 테스트 작성과 실행 보조

테스트가 없는 코드에 테스트를 추가하거나, 실패하는 테스트를 고치는 데도 사용할 수 있습니다.

userService의 예외 케이스 테스트를 추가해줘.
수정 후 npm test를 실행하고 실패하면 원인을 설명해줘.

테스트 명령어를 명확히 알려주면 Claude Code가 결과를 검증하기 쉬워집니다.

5. Git 작업 보조

Claude Code는 Git 작업 흐름에서도 활용할 수 있습니다.

현재 변경된 파일을 요약해줘.
커밋 메시지 후보를 3개 작성해줘.

또는 다음처럼 요청할 수 있습니다.

마지막 5개 커밋을 확인하고, 이번 변경 사항과 충돌 가능성이 있는 부분을 찾아줘.

단, 실제 커밋이나 브랜치 조작을 맡길 때는 변경 내용을 반드시 확인해야 합니다.

Claude Code 설치 방법

2026년 5월 기준 공식 문서에서는 Claude Code를 사용하기 위해 터미널, 작업할 코드 프로젝트, Claude 구독 계정 또는 Claude Console 계정 등이 필요하다고 안내합니다.

설치 명령어는 운영체제별로 구분해서 보는 것이 좋습니다.

macOS / Linux / WSL

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell

irm https://claude.ai/install.ps1 | iex

Windows CMD

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

설치 후에는 프로젝트 폴더로 이동해 Claude Code를 실행합니다.

cd /path/to/your/project
claude

처음 실행하면 로그인 절차가 필요합니다. 공식 문서에 따르면 Claude Pro, Max, Team, Enterprise 계정이나 Claude Console 계정 등을 사용할 수 있습니다.

Claude Code를 잘 쓰는 요청 방식

Claude Code는 강력하지만, “알아서 다 해줘”라고만 요청하면 기대한 결과가 나오지 않을 수 있습니다.

좋은 요청은 보통 다음 조건을 포함합니다.

1. 먼저 탐색하게 하기

바로 코드를 수정하게 하기보다, 먼저 구조를 파악하게 하는 것이 좋습니다.

src/auth 폴더를 읽고 현재 로그인 흐름을 설명해줘.
아직 파일은 수정하지 말고, 수정이 필요한 부분만 정리해줘.

이렇게 요청하면 Claude Code가 무리하게 코드를 바꾸기 전에 현재 구조를 설명합니다. 개발자는 그 설명을 보고 방향이 맞는지 먼저 판단할 수 있습니다.

2. 성공 기준을 명확히 주기

나쁜 예시

로그인 버그 고쳐줘.

이 요청은 증상, 관련 영역, 기대 결과가 분명하지 않아 작업 범위가 넓어질 수 있습니다.

더 나은 예시

세션 만료 후 다시 로그인할 때 401 에러가 발생해.
src/auth와 token refresh 로직을 확인해줘.
재현 테스트를 먼저 만들고, 테스트가 통과하도록 수정해줘.

증상, 관련 영역, 기대 결과를 함께 적으면 Claude Code가 작업 범위를 더 정확히 잡을 수 있습니다.

3. 테스트 명령어를 알려주기

프로젝트마다 테스트 실행 방식은 다릅니다.

수정 후 npm test를 실행해줘.
타입 체크는 npm run typecheck로 확인해줘.

또는 Python 프로젝트라면 이렇게 쓸 수 있습니다.

수정 후 pytest를 실행해줘.
실패하는 테스트가 있으면 원인을 설명하고 수정 방향을 제안해줘.

테스트 명령어를 알려주면 Claude Code가 작업 결과를 검증하기 쉬워집니다.

4. 큰 작업은 단계로 나누기

큰 기능을 한 번에 맡기면 결과를 검토하기 어렵습니다.

1단계로 현재 구조만 파악해줘.
2단계에서 수정 계획을 작성해줘.
3단계에서 내가 승인하면 코드 수정을 진행해줘.

이런 식으로 나누면 예상치 못한 변경을 줄일 수 있습니다.

CLAUDE.md 파일은 언제 쓸까?

Claude Code에는 프로젝트용 지침을 담는 CLAUDE.md 파일을 둘 수 있습니다.

이 파일에는 코드 스타일, 테스트 명령어, 브랜치 규칙, PR 작성 방식 같은 내용을 적어둘 수 있습니다.

예시는 다음과 같습니다.

# Code style
- TypeScript에서는 명시적인 타입을 선호한다.
- 공통 유틸 함수는 src/utils에 둔다.

# Workflow
- 코드 수정 후 `npm run typecheck`를 실행한다.
- 테스트는 가능하면 관련 테스트만 먼저 실행한다.
- 파일 수정 후 `git diff`로 변경 내용을 요약한다.

다만 CLAUDE.md를 너무 길게 작성하는 것은 좋지 않습니다. 항상 필요한 규칙만 짧게 적는 편이 낫습니다.

프로젝트마다 반복되는 작업 규칙이 있다면 CLAUDE.md에 넣고, 특정 상황에서만 필요한 긴 절차는 별도 문서나 스킬로 분리하는 방식이 더 관리하기 쉽습니다.

비용과 토큰 사용량도 주의해야 한다

Claude Code를 사용할 때는 비용과 사용량도 고려해야 합니다.

공식 비용 문서에 따르면 Claude Code 비용은 API 토큰 소비, 모델 선택, 코드베이스 크기, 사용 패턴 등에 따라 달라질 수 있습니다. Pro나 Max 같은 구독 플랜을 사용하는 경우와 API 기반으로 사용하는 경우의 비용 체감도 다를 수 있습니다.

특히 큰 코드베이스에서 여러 파일을 읽고, 테스트를 반복 실행하고, 긴 대화를 이어가면 사용량이 빠르게 늘 수 있습니다.

비용을 줄이려면 다음 습관이 도움이 됩니다.

작업 범위를 좁혀서 요청하기
관련 폴더나 파일을 명확히 지정하기
불필요하게 “전체 프로젝트를 다 읽어줘”라고 요청하지 않기
긴 작업은 단계별로 나누기
/usage 같은 사용량 확인 기능 활용하기
팀 단위라면 사용량과 비용 추적 기준을 정해두기

예를 들어 다음 요청은 범위가 너무 넓습니다.

범위가 넓은 예시

이 프로젝트 전체를 분석해서 다 고쳐줘.

다음처럼 좁히는 편이 낫습니다.

범위를 좁힌 예시

src/auth 폴더 안에서 로그인 실패와 관련된 파일만 확인해줘.
아직 수정하지 말고 원인 후보를 먼저 정리해줘.

범위를 좁히면 비용 관리뿐 아니라 결과 품질에도 도움이 됩니다.

`.gitignore`는 Claude Code 접근 제어 장치가 아니다

Claude Code를 사용할 때 민감한 파일이나 불필요한 경로를 어떻게 다룰지도 생각해야 합니다.

여기서 주의할 점이 있습니다. .gitignore는 Git이 추적하지 않을 파일을 지정하는 설정입니다. Claude Code의 파일 접근 권한을 제어하기 위한 장치로 이해하면 안 됩니다.

민감한 파일이나 특정 경로 접근을 제한하려면 Claude Code의 settings, permissions, sandbox 관련 설정을 확인하는 편이 안전합니다. 공식 설정 문서에서는 파일 시스템과 네트워크 제한을 sandbox.filesystem 설정과 permission rules로 구성할 수 있다고 설명합니다.

실무에서는 다음 기준을 두는 것이 좋습니다.

.env, 인증 키, 비밀 토큰 파일은 코드베이스에 두지 않기
민감한 파일은 Claude가 읽거나 수정할 필요가 없도록 작업 범위에서 제외하기
권한 설정으로 읽기·쓰기·웹 접근 범위 관리하기
신뢰하기 어려운 저장소에서는 자동 승인 모드 사용을 피하기
AI가 실행하려는 명령은 승인 전에 확인하기

Claude Code는 개발자의 생산성을 높이는 도구지만, 권한을 가진 도구이기 때문에 보안 기준도 함께 세워야 합니다.

Claude Code의 장점

Claude Code의 장점은 크게 세 가지입니다.

첫째, 기존 개발 흐름을 크게 바꾸지 않아도 됩니다.
터미널에서 바로 사용할 수 있고, Git이나 테스트 명령어 같은 기존 도구와 함께 사용할 수 있습니다.

둘째, 코드베이스 맥락을 기반으로 작업할 수 있습니다.
단일 코드 조각이 아니라 여러 파일과 프로젝트 구조를 함께 확인할 수 있습니다.

셋째, 반복적인 개발 작업을 줄일 수 있습니다.
테스트 작성, 에러 로그 분석, 리팩터링 후보 정리, 문서화 같은 작업에서 특히 유용합니다.

다만 이 장점은 개발자가 결과를 검토할 수 있을 때 더 의미가 있습니다. Claude Code는 개발자를 대체하는 도구라기보다, 개발자가 더 빠르게 탐색하고 수정할 수 있도록 돕는 도구에 가깝습니다.

Claude Code의 한계와 주의할 점

Claude Code가 프로젝트 파일을 읽고 수정할 수 있다고 해서 결과를 그대로 믿으면 안 됩니다.

AI 코딩 도구는 여전히 잘못된 판단을 할 수 있습니다. 프로젝트의 의도나 비즈니스 규칙을 완전히 이해하지 못한 상태에서 그럴듯한 코드를 만들 수도 있습니다.

특히 다음 작업은 반드시 사람이 검토해야 합니다.

인증·보안 로직 수정
결제 관련 코드
데이터 삭제 또는 마이그레이션
운영 배포 스크립트
인프라 설정 변경
개인정보 처리 코드
권한 정책 변경

또한 컨텍스트가 길어질수록 품질이 떨어질 수 있습니다. 대화가 길어지고 읽어야 할 파일이 많아질수록 AI가 이전 지시를 놓치거나, 작업 범위를 넓게 해석할 가능성이 있습니다.

큰 작업은 한 번에 맡기기보다 다음처럼 나누는 편이 안전합니다.

1단계: 현재 구조 파악
2단계: 수정 계획 작성
3단계: 핵심 파일만 수정
4단계: 테스트 실행
5단계: git diff 요약
6단계: 사람이 최종 리뷰

이 흐름을 지키면 Claude Code의 생산성은 활용하면서도 위험한 변경을 줄일 수 있습니다.

어떤 사람에게 Claude Code가 잘 맞을까?

Claude Code는 다음과 같은 개발자에게 잘 맞습니다.

터미널 사용에 익숙한 개발자
기존 프로젝트 구조를 빠르게 파악하고 싶은 사람
테스트, 리팩터링, 버그 수정 작업을 자주 하는 사람
AI에게 단순 코드 생성보다 작업 흐름 보조를 맡기고 싶은 사람
Git, 빌드, 테스트 명령어를 자주 사용하는 개발자
여러 파일에 걸친 변경 사항을 AI와 함께 검토하고 싶은 사람

반대로 터미널 사용이 낯설거나, 코드 수정 결과를 직접 검토하기 어려운 초보자라면 처음부터 큰 작업을 맡기기보다 설명·분석 용도로 시작하는 편이 안전합니다.

예를 들어 첫 사용은 이런 요청이 좋습니다.

이 프로젝트가 어떤 구조인지 설명해줘.
아직 파일은 수정하지 말고, 주요 폴더와 실행 흐름만 정리해줘.

또는 다음처럼 쓸 수 있습니다.

현재 변경된 파일을 읽고, 어떤 의도로 수정된 것처럼 보이는지 요약해줘.
코드는 수정하지 마.

이렇게 읽기 중심 작업부터 시작하면 Claude Code의 동작 방식을 이해하기 쉽습니다.

Claude Code는 챗봇보다 개발자 도구에 가깝다

Claude Code를 단순히 “코딩해주는 AI”로 보면 장점을 제대로 이해하기 어렵습니다.

핵심은 터미널 안에서 프로젝트를 읽고, 계획을 세우고, 파일을 수정하고, 테스트나 Git 같은 개발 명령 흐름까지 다룰 수 있다는 점입니다. 그래서 Claude Code는 질문에 답하는 챗봇이라기보다 개발자의 작업 공간 안에 들어온 AI 코딩 에이전트에 가깝습니다.

물론 모든 코드를 믿고 맡길 수 있는 도구는 아닙니다. 최종 책임은 여전히 개발자에게 있습니다. 하지만 구조 파악, 버그 분석, 테스트 작성, 리팩터링, 문서화처럼 시간이 많이 드는 작업에서는 충분히 생산성을 높일 수 있습니다.

처음 사용한다면 큰 기능 개발부터 맡기기보다, 현재 프로젝트를 설명하게 하거나 실패한 테스트 원인을 찾게 하는 작은 작업부터 시작하는 것이 좋습니다. 그 과정에서 요청 범위를 좁히고, 권한을 확인하고, git diff와 테스트로 결과를 검증하는 습관을 들이면 더 안정적으로 활용할 수 있습니다.

Context7이란? 최신 개발 문서를 AI가 참고하게 만드는 방법

notebase — Fri, 22 May 2026 20:30:24 +0900

Context7은 AI 코딩 도구가 최신 개발 문서와 코드 예제를 참고하도록 돕는 MCP 기반 도구입니다. Context7의 개념, MCP와의 관계, 사용 방식, 주의할 점을 초보자도 이해하기 쉽게 정리했습니다.

AI 코딩 도구를 쓰다 보면 Context7이 자주 언급됩니다. Context7은 AI가 오래된 기억만으로 코드를 작성하지 않도록, 최신 개발 문서와 코드 예제를 프롬프트에 넣어주는 MCP 기반 도구입니다.

개발자는 AI에게 질문합니다.

“Next.js 미들웨어 코드 작성해줘.”
“Supabase 로그인 구현해줘.”
“Cloudflare Workers 캐싱 예제 만들어줘.”

문제는 여기서 시작됩니다.

AI가 답은 해주지만, 그 답이 현재 버전과 맞지 않을 수 있습니다. 예전 문법을 쓰거나, 더 이상 존재하지 않는 API를 알려주거나, 특정 라이브러리의 최신 변경사항을 반영하지 못하는 경우가 있습니다.

Context7은 이 문제를 줄이기 위해 등장한 도구입니다.

2026년 5월 기준 Context7 공식 문서는 Context7을 최신 버전별 문서와 코드 예제를 AI 코딩 어시스턴트에 직접 가져오는 도구로 설명합니다. 공식 문서에서는 AI가 오래된 학습 데이터나 일반적인 답변에 의존하는 문제를 줄이는 것이 핵심 목적이라고 안내합니다.

AI 코딩 도구가 틀린 코드를 알려주는 이유

AI 코딩 도구는 매우 편리합니다.
하지만 개발 문서가 빠르게 바뀌는 분야에서는 한계가 있습니다.

예를 들어 다음과 같은 상황이 생길 수 있습니다.

최신 Next.js 버전과 맞지 않는 예제를 알려준다.
Supabase 인증 API를 예전 방식으로 설명한다.
React의 최신 권장 패턴을 반영하지 못한다.
라이브러리에 없는 함수를 있는 것처럼 말한다.
공식 문서에서는 바뀐 설정 방식을 예전 방식으로 안내한다.

이런 문제는 AI가 무능해서라기보다, AI가 답변할 때 참고하는 정보가 항상 최신 공식 문서와 연결되어 있는 것은 아니기 때문입니다.

특히 프레임워크, 클라우드 서비스, SDK, 인증 라이브러리는 업데이트가 잦습니다.
1년 전에는 맞던 코드가 지금은 경고를 띄우거나, 아예 작동하지 않을 수 있습니다.

그래서 AI 코딩에서는 단순히 “똑똑한 모델”만 중요한 것이 아닙니다.
AI가 어떤 문서를 참고하고 있는지도 중요합니다.

Context7이란?

Context7 홈페이지

Context7은 AI 코딩 도구가 최신 개발 문서를 참고할 수 있도록 돕는 문서 컨텍스트 도구입니다.

조금 쉽게 말하면, Context7은 AI에게 이렇게 말해주는 역할을 합니다.

“그냥 네가 기억하는 대로 답하지 말고, 지금 이 라이브러리의 최신 문서를 보고 답해.”

Context7 공식 문서에 따르면, Context7은 최신 문서와 버전별 코드 예제를 가져와 AI의 프롬프트 안에 직접 넣어줍니다. 사용자는 Cursor 같은 AI 코딩 도구에서 프롬프트 끝에 use context7을 붙여 사용할 수 있습니다.

예를 들면 이런 식입니다.

Create a Next.js middleware that checks for a valid JWT in cookies.
use context7

여기서 중요한 부분은 마지막의 use context7입니다. 이 문구는 AI에게 Context7을 통해 관련 문서를 참고하라는 신호로 쓰입니다.

또는 다음처럼 요청할 수 있습니다.

Configure a Cloudflare Worker script to cache JSON API responses for five minutes.
use context7

핵심은 단순합니다.

AI에게 질문만 던지는 것이 아니라, 해당 작업과 관련된 최신 문서까지 함께 참고하게 만드는 것입니다.

MCP와 Context7의 관계

Context7을 이해하려면 MCP도 함께 알아야 합니다.

MCP는 Model Context Protocol의 약자입니다.
AI 모델이나 AI 에이전트가 외부 도구, 데이터, 문서, 서비스와 연결될 수 있도록 만든 표준 방식에 가깝습니다.

일반적인 AI는 사용자가 입력한 프롬프트와 모델이 이미 알고 있는 지식을 바탕으로 답합니다.
반면 MCP를 사용하면 AI가 외부 도구를 통해 추가 정보를 가져올 수 있습니다.

Context7은 이 MCP 생태계에서 “최신 개발 문서 제공”에 초점을 둔 도구입니다.

즉, 관계를 단순하게 정리하면 이렇습니다.

구분	역할
MCP	AI와 외부 도구를 연결하는 방식
Context7	MCP를 통해 최신 개발 문서를 AI에게 전달하는 도구
AI 코딩 도구	Context7이 가져온 문서를 참고해 코드 작성

MCP 디렉터리에서도 Context7은 공식 MCP 서버로 소개되며, 공식 출처의 최신 버전별 코드 문서와 예제를 AI 프롬프트에 주입하는 도구로 설명됩니다.

Context7은 어떻게 동작할까?

Context7의 작동 방식은 복잡해 보이지만, 흐름은 비교적 단순합니다.

1. 사용자가 AI에게 개발 작업을 요청한다

예를 들어 Cursor에서 다음처럼 입력합니다.

Next.js 15 기준으로 middleware에서 인증 체크하는 예제 작성해줘. use context7

2. AI 코딩 도구가 Context7 MCP 서버를 호출한다

use context7이라는 지시가 있으면, AI 코딩 도구는 Context7을 통해 관련 문서를 찾습니다.

실제 사용 시에는 Cursor, Claude Code, Windsurf, Cline 같은 AI 코딩 도구의 MCP 설정 메뉴에서 Context7 MCP 서버를 등록한 뒤 사용합니다. 도구마다 설정 방식은 다르지만, 핵심은 AI 코딩 도구가 Context7 서버를 외부 문서 조회 도구로 호출할 수 있게 연결하는 것입니다.

설치 명령어나 설정 파일 형식은 사용하는 도구에 따라 달라질 수 있습니다. 따라서 개념을 먼저 이해한 뒤, 실제 적용 단계에서는 각 도구의 MCP 설정 문서를 함께 확인하는 것이 좋습니다.

3. Context7이 관련 라이브러리 문서를 가져온다

Context7은 요청과 관련된 라이브러리나 프레임워크 문서를 찾아 AI의 컨텍스트에 넣습니다.

공식 설명에 따르면 Context7은 최신 코드 예제와 문서를 LLM의 컨텍스트 안으로 가져와, 탭을 옮겨가며 문서를 찾거나 오래된 API를 기반으로 답변받는 문제를 줄이는 것을 목표로 합니다.

4. AI가 문서를 참고해 답변한다

AI는 이제 단순히 기억에만 의존하지 않고, Context7이 제공한 문서 내용을 바탕으로 답변합니다.

물론 이것이 모든 오류를 완전히 없앤다는 뜻은 아닙니다.
하지만 적어도 변화가 빠른 라이브러리에서는 오래된 코드가 나올 가능성을 줄이는 데 도움이 됩니다.

`use context7`은 무슨 뜻일까?

Context7을 검색하다 보면 use context7이라는 표현을 자주 보게 됩니다.

이 말은 AI에게 다음과 같이 지시하는 것과 비슷합니다.

“이 작업은 Context7을 사용해서 최신 문서를 참고한 뒤 답해줘.”

Context7 공식 문서에서도 자연어 프롬프트 끝에 use context7을 붙이는 방식을 예시로 안내하고 있습니다.

예를 들어 그냥 이렇게 묻는 것과,

Supabase 이메일 회원가입 코드 작성해줘

이렇게 묻는 것은 차이가 있을 수 있습니다.

Supabase 이메일 회원가입 코드 작성해줘. use context7

두 번째 요청은 AI가 Context7을 통해 Supabase 관련 최신 문서나 예제를 참고하도록 유도합니다.

특히 라이브러리 버전이 중요할 때는 더 구체적으로 쓰는 것이 좋습니다.

Supabase JavaScript client 최신 문서 기준으로 이메일 회원가입 예제를 작성해줘. use context7

또는 다음처럼 버전을 명시할 수도 있습니다.

Next.js 15 App Router 기준으로 middleware 인증 처리 예제를 작성해줘. use context7

좋은 프롬프트는 Context7의 효과를 더 높입니다.

Context7이 유용한 상황

Context7은 모든 질문에 반드시 필요한 도구는 아닙니다.
하지만 다음 상황에서는 꽤 유용할 수 있습니다.

1. 변화가 빠른 프레임워크를 사용할 때

Next.js, React, SvelteKit, Nuxt 같은 프레임워크는 버전에 따라 권장 방식이 자주 바뀝니다.

AI가 예전 방식으로 코드를 작성하면, 실행은 되더라도 현재 공식 문서와 맞지 않을 수 있습니다.

이럴 때 Context7을 사용하면 최신 문서 기반의 답변을 받을 가능성이 높아집니다.

2. 클라우드 서비스 SDK를 사용할 때

Supabase, Firebase, Cloudflare, Stripe, Vercel 같은 서비스는 SDK와 설정 방식이 바뀌는 경우가 많습니다.

특히 인증, 결제, 배포, 캐싱, 웹훅 같은 기능은 예전 코드가 그대로 통하지 않을 수 있습니다.

Context7은 이런 서비스형 개발 문서를 AI가 참고하게 만들 때 유용합니다.

3. AI가 없는 API를 만들어낼 때

AI 코딩 도구를 쓰다 보면 실제로는 존재하지 않는 함수나 옵션을 제안하는 경우가 있습니다.

이른바 “환각” 문제입니다.

Context7은 공식 문서 기반의 예제를 컨텍스트로 넣어주기 때문에, 이런 문제를 줄이는 데 도움이 됩니다.

공식 문서 역시 Context7의 목적 중 하나로 존재하지 않는 API를 만들어내는 문제를 줄이는 것을 언급합니다.

4. 문서를 직접 찾는 시간이 아까울 때

개발자는 종종 코드 작성보다 문서 탐색에 더 많은 시간을 씁니다.

공식 문서 탭을 열고, 버전을 확인하고, 예제를 찾고, 현재 프로젝트에 맞는지 비교해야 합니다.

Context7은 이 과정을 AI 코딩 흐름 안으로 가져옵니다.

즉, 문서를 아예 보지 않아도 된다는 뜻은 아닙니다.
다만 AI에게 초안을 맡길 때 참고 자료를 더 정확하게 넣어줄 수 있다는 의미입니다.

Context7을 쓴다고 항상 정답이 나올까?

그렇지는 않습니다.

Context7은 AI 답변의 근거를 최신 문서에 더 가깝게 만들어주는 도구입니다.
하지만 다음 한계는 여전히 있습니다.

1. 프로젝트 상황까지 완전히 이해하는 것은 아니다

Context7은 라이브러리 문서를 가져오는 데 강점이 있습니다.
하지만 내 프로젝트의 폴더 구조, 기존 코드 스타일, 내부 아키텍처, 팀 규칙까지 자동으로 완벽하게 이해하는 것은 아닙니다.

따라서 실무에서는 Context7과 함께 프로젝트 문맥도 같이 제공하는 것이 좋습니다.

예를 들면 다음처럼 요청할 수 있습니다.

현재 프로젝트는 Next.js 15 App Router를 사용하고 있어.
인증은 Supabase Auth를 쓰고 있고, middleware.ts에서 보호 라우트를 처리하려고 해.
공식 문서 기준으로 구현 방향을 제안해줘. use context7

2. 문서가 최신이어도 해석은 AI가 한다

Context7이 문서를 가져와도, 최종 코드를 작성하는 것은 AI입니다.

AI가 문서를 잘못 해석할 수도 있고, 프로젝트 상황에 맞지 않는 코드를 만들 수도 있습니다.

따라서 생성된 코드는 반드시 실행하고 검증해야 합니다.

3. 보안 관련 코드는 추가 검토가 필요하다

인증, 결제, 권한 처리, 토큰 검증, 개인정보 처리 같은 코드는 특히 조심해야 합니다.

문서 기반이라고 해도 바로 운영 환경에 넣기보다는 다음을 확인해야 합니다.

토큰 검증이 서버 측에서 안전하게 처리되는가
민감한 키가 클라이언트에 노출되지 않는가
권한 체크가 우회될 가능성은 없는가
에러 처리와 예외 상황이 충분한가

Context7은 문서 참고를 도와주는 도구이지, 보안 검토를 대신하는 도구는 아닙니다.

MCP, CLI, Skills와 비교하면 무엇이 다를까?

AI 개발 도구를 쓰다 보면 Context7 외에도 MCP, CLI, Skills 같은 용어를 접하게 됩니다.

각각의 역할은 다릅니다.

구분	핵심 역할	Context7과의 관계
MCP	AI와 외부 도구를 연결하는 표준 방식	Context7이 MCP 서버 형태로 제공됨
Context7	최신 개발 문서를 AI에게 제공	MCP를 활용한 문서 컨텍스트 도구
CLI	터미널에서 명령어로 실행하는 도구	설치, 실행, 자동화에 유리
Skills	특정 작업 방식을 AI에게 학습시키는 지침 묶음	문서 검색보다는 작업 절차 표준화에 가까움

쉽게 비유하면 이렇습니다.

MCP는 AI가 외부 도구와 연결되는 통로입니다.
Context7은 그 통로를 통해 최신 개발 문서를 가져오는 도구입니다.
CLI는 개발자가 직접 명령어로 실행하는 방식입니다.
Skills는 AI가 특정 작업을 더 일관되게 수행하도록 만드는 작업 규칙에 가깝습니다.

따라서 Context7은 “AI가 최신 문서를 참고하게 만드는 것”에 초점이 있습니다.

반면 Skills는 “AI가 특정 작업 방식을 따르게 만드는 것”에 더 가깝습니다.

둘 중 하나만 무조건 선택해야 하는 관계는 아닙니다.
실무에서는 함께 쓰는 방식이 더 자연스럽습니다.

예를 들어 다음과 같이 역할을 나눌 수 있습니다.

Context7: 최신 라이브러리 문서 참고
프로젝트 규칙 파일 또는 Skills: 코드 스타일, 테스트 방식, 폴더 구조 안내
CLI: 실제 빌드, 테스트, 린트 실행

Context7을 잘 쓰는 프롬프트 예시

Context7은 그냥 붙여도 되지만, 요청을 구체적으로 쓰면 더 좋습니다.

나쁜 예시

로그인 만들어줘. use context7

이 요청은 너무 넓습니다.
어떤 프레임워크인지, 어떤 인증 서비스를 쓰는지, 어떤 환경인지 알기 어렵습니다.

더 나은 예시

Next.js 15 App Router와 Supabase Auth를 사용해서
이메일/비밀번호 로그인 페이지를 만들고 싶어.
공식 문서 기준으로 필요한 파일 구조와 예제 코드를 제안해줘. use context7

더 실무적인 예시

현재 프로젝트는 Next.js 15 App Router, TypeScript, Supabase Auth를 사용해.
로그인하지 않은 사용자가 /dashboard에 접근하면 /login으로 보내고 싶어.
middleware.ts 구현 예제를 최신 문서 기준으로 작성해줘.
주의해야 할 보안 포인트도 함께 설명해줘. use context7

Context7은 문서를 가져오는 도구입니다.
하지만 어떤 문서를 참고해야 하는지 힌트를 주는 것은 여전히 사용자의 몫입니다.

Context7이 특히 잘 맞는 개발자

Context7은 다음 유형의 개발자에게 잘 맞습니다.

AI 코딩 도구를 자주 쓰는 개발자
최신 프레임워크를 빠르게 따라가야 하는 개발자
공식 문서를 매번 직접 뒤지는 시간이 부담스러운 사람
AI가 오래된 코드 예제를 주는 것에 불편함을 느낀 사람
Cursor, Claude Code, Windsurf, Cline 같은 도구를 실무에 쓰는 사람

반대로 다음 상황에서는 필요성이 낮을 수 있습니다.

거의 변하지 않는 사내 레거시 코드만 다루는 경우
인터넷 문서보다 내부 문서와 코드베이스 규칙이 더 중요한 경우
AI 코딩 도구를 거의 쓰지 않는 경우
단순한 문법 질문 위주로만 AI를 사용하는 경우

Context7을 사용할 때의 현실적인 기준

Context7은 AI 코딩의 정확도를 높이는 데 도움이 될 수 있습니다.
하지만 “AI가 알아서 최신 문서를 완벽히 보고, 완벽한 코드를 작성한다”로 이해하면 안 됩니다.

현실적인 사용 기준은 이렇습니다.

최신 API가 중요한 작업에 적용합니다.

Next.js, Supabase, Stripe, Cloudflare, React 관련 작업은 문서 변경 영향이 크기 때문에 Context7을 붙여볼 만합니다.

버전과 환경을 함께 명시합니다.

“최신 기준”보다 “Next.js 15 App Router 기준”처럼 쓰는 편이 좋습니다.

생성된 코드는 반드시 실행해봅니다.

Context7은 참고 문서를 보강해주는 도구이지, 테스트를 대신하지 않습니다.

보안과 결제 코드는 공식 문서를 다시 확인합니다.

인증, 권한, 결제, 토큰 검증처럼 민감한 코드는 AI가 작성한 결과를 그대로 운영 환경에 넣지 않는 편이 안전합니다.

Cursor나 Claude Code를 사용하고 있다면, 자주 쓰는 프레임워크부터 Context7을 적용해보는 것이 좋습니다. 특히 Next.js, Supabase, Cloudflare처럼 문서 변화가 빠른 도구부터 테스트해보면 차이를 체감하기 쉽습니다.

정리

Context7은 AI 코딩 도구가 최신 개발 문서를 참고하도록 도와주는 MCP 기반 도구입니다.

AI가 오래된 학습 데이터에만 의존하면, 최신 라이브러리와 맞지 않는 코드가 나올 수 있습니다. Context7은 관련 문서와 코드 예제를 AI의 컨텍스트에 넣어 이런 문제를 줄이는 데 도움을 줍니다.

핵심은 단순합니다.

질문 + 구체적인 기술 조건 + use context7

이 조합을 사용하면 AI가 더 최신 문서에 가까운 답변을 만들 가능성이 높아집니다.

다만 Context7이 모든 문제를 해결하는 것은 아닙니다.
프로젝트 구조, 보안 요구사항, 팀 규칙, 실제 실행 결과는 개발자가 직접 확인해야 합니다.

AI 코딩 도구를 실무에 쓰고 있다면 Context7은 한 번쯤 적용해볼 만한 도구입니다. 특히 변화가 빠른 프레임워크와 SDK를 다룰 때, AI 답변의 기준점을 최신 문서 쪽으로 옮겨주는 역할을 합니다.

MCP란 무엇인가? AI 에이전트가 외부 도구와 연결되는 방식

notebase — Fri, 22 May 2026 19:53:02 +0900

MCP(Model Context Protocol)가 무엇인지, AI 에이전트가 외부 도구와 데이터를 어떻게 연결하는지 초보자도 이해할 수 있게 정리합니다.

MCP란 AI 에이전트가 외부 도구, 데이터, 앱과 연결될 수 있도록 만든 표준 프로토콜이다. 정식 명칭은 Model Context Protocol이다.

쉽게 말하면, AI가 혼자 대화만 하는 수준을 넘어 파일을 읽고, 데이터베이스를 조회하고, 개발 도구를 다루고, 업무 앱과 연결될 수 있게 해주는 연결 규칙이다.

Anthropic 공식 문서에서는 MCP를 “AI 애플리케이션을 위한 USB-C 포트”에 비유한다. USB-C가 여러 기기와 주변기기를 하나의 방식으로 연결하듯, MCP는 AI 모델과 다양한 데이터·도구를 표준화된 방식으로 연결한다.

MCP는 왜 등장했을까?

기존 AI 챗봇은 기본적으로 대화창 안에서만 작동했다.

사용자가 질문하면 AI는 학습된 지식이나 입력된 문맥을 바탕으로 답변했다. 하지만 실제 업무에서는 이것만으로 부족하다.

예를 들어 AI에게 이런 일을 시키고 싶을 수 있다.

내 로컬 파일에서 문서 찾기
GitHub 이슈 확인하기
Notion 문서 요약하기
데이터베이스에서 고객 정보 조회하기
Slack 메시지 기반으로 할 일 정리하기
코드 에디터에서 프로젝트 구조 분석하기

이런 작업을 하려면 AI가 외부 시스템과 연결되어야 한다.

문제는 서비스마다 연결 방식이 다르다는 점이다. GitHub, Slack, Google Drive, 데이터베이스, 로컬 파일 시스템은 모두 다른 API와 인증 방식을 가진다. AI 앱마다 각각 별도 연동을 만들면 개발 비용이 커지고, 유지보수도 어려워진다.

MCP는 이 문제를 줄이기 위해 만들어졌다. Anthropic은 MCP를 AI 시스템과 데이터 소스를 연결하기 위한 개방형 표준으로 소개했고, 2024년 11월 처음 공개했다.

AI 에이전트와 MCP의 관계

AI 에이전트는 단순히 답변만 하는 AI가 아니다.

목표를 이해하고, 필요한 단계를 나누고, 외부 도구를 사용해 작업을 수행하는 AI에 가깝다.

예를 들어 사용자가 이렇게 요청했다고 해보자.

“지난주 회의록을 찾아서 핵심 결정사항을 정리하고, 관련 GitHub 이슈까지 확인해줘.”

일반 챗봇이라면 사용자가 회의록과 GitHub 내용을 직접 붙여넣어야 한다.

하지만 MCP로 외부 도구가 연결된 AI 에이전트라면 흐름이 달라질 수 있다.

회의록이 저장된 위치를 찾는다.
문서를 읽는다.
결정사항을 요약한다.
GitHub 이슈를 조회한다.
회의 내용과 이슈를 연결해 정리한다.

예를 들어 파일 시스템 MCP 서버가 연결되어 있다면, AI는 허용된 범위 안에서 meeting-notes/2026-05.md 같은 문서를 찾아 읽고 요약할 수 있다.

여기서 MCP는 AI가 직접 외부 세계에 접근할 수 있도록 돕는 연결 계층이다.

즉, AI 에이전트가 일하는 사람이라면 MCP는 그 사람이 업무 도구에 접근하는 표준 인터페이스에 가깝다.

MCP는 어떻게 외부 도구와 연결될까?

MCP는 기본적으로 클라이언트-서버 구조를 따른다.

공식 MCP 소개 문서에서도 핵심 구조를 MCP Host, MCP Client, MCP Server, 로컬 데이터 소스, 원격 서비스로 설명한다.

MCP Host, Client, Server 구조

구조를 쉽게 풀면 다음과 같다.

구성 요소	역할
MCP Host	AI가 실행되는 앱. 예: Claude Desktop, IDE, AI 도구
MCP Client	MCP 서버와 연결을 유지하는 클라이언트
MCP Server	특정 도구나 데이터 소스를 AI에게 노출하는 프로그램
Local Data Source	내 컴퓨터의 파일, 로컬 DB 등
Remote Service	GitHub, Slack, Notion 같은 외부 서비스

핵심은 MCP 서버다.

MCP 서버는 특정 도구를 AI가 사용할 수 있는 형태로 포장해준다.

예를 들어 GitHub MCP 서버가 있다면, AI는 GitHub의 이슈, PR, 저장소 정보를 정해진 방식으로 요청할 수 있다. 파일 시스템 MCP 서버가 있다면, AI는 허용된 범위 안에서 파일을 읽거나 검색할 수 있다.

AI 모델이 모든 서비스의 API 사용법을 직접 알아야 하는 것이 아니다. MCP 서버가 중간에서 “이 도구는 이런 기능을 제공한다”고 알려주는 구조다.

MCP 서버와 MCP 클라이언트는 무엇인가?

MCP를 이해할 때 가장 헷갈리는 부분이 서버와 클라이언트다.

일반적인 웹 서비스에서는 사용자가 브라우저를 열고 서버에 접속한다. MCP에서도 비슷하게 볼 수 있다.

AI 앱이 MCP 클라이언트 역할을 하고, 외부 도구를 감싼 프로그램이 MCP 서버 역할을 한다.

예를 들어 Claude Desktop이나 Cursor 같은 도구가 MCP를 지원한다고 해보자. 사용자가 파일 시스템 MCP 서버를 연결하면, AI 앱은 그 서버를 통해 로컬 파일 관련 기능을 사용할 수 있다.

정리하면 다음과 같다.

구분	쉽게 말하면
MCP 클라이언트	AI 앱 안에서 MCP 서버와 통신하는 쪽
MCP 서버	외부 도구나 데이터를 AI가 쓸 수 있게 열어주는 쪽
도구	AI가 실제로 호출하는 기능. 예: 파일 읽기, 이슈 조회, 검색

이 구조 덕분에 AI 앱은 모든 도구를 직접 내장하지 않아도 된다.

필요한 MCP 서버만 연결하면 된다.

MCP 서버가 제공하는 3가지 요소

MCP 서버는 단순히 외부 서비스를 연결하는 통로만 제공하지 않는다. 보통 다음과 같은 요소를 AI 클라이언트에 노출한다.

요소	의미	예시
Resources	AI가 읽을 수 있는 데이터나 문서	회의록 파일, 데이터베이스 조회 결과, 문서 내용
Tools	AI가 직접 호출할 수 있는 기능	파일 검색, GitHub 이슈 조회, 테스트 실행
Prompts	자주 쓰는 프롬프트나 작업 템플릿	코드 리뷰 요청 양식, 회의록 요약 템플릿

이 중 Tools는 AI 에이전트와 특히 밀접하다. AI가 단순히 정보를 읽는 데 그치지 않고, 필요한 기능을 호출해 작업을 진행할 수 있기 때문이다.

반면 Resources는 AI가 참고할 수 있는 문맥을 제공하는 데 가깝다. 예를 들어 특정 문서, 파일 내용, 데이터 조회 결과를 AI가 읽을 수 있게 한다.

Prompts는 반복적으로 쓰는 작업 방식을 템플릿처럼 제공하는 요소다. 사용자가 매번 긴 지시문을 작성하지 않아도, 미리 정의된 흐름을 바탕으로 작업을 시작할 수 있다.

API와 MCP는 무엇이 다를까?

MCP를 처음 들으면 “그냥 API랑 같은 거 아닌가?”라고 생각할 수 있다.

비슷한 부분은 있다. 둘 다 시스템 사이의 연결을 다룬다.

하지만 관점이 다르다.

API는 보통 특정 서비스가 외부 개발자에게 기능을 제공하는 방식이다. 예를 들어 GitHub API, Slack API, Google Drive API처럼 서비스마다 사용법이 다르다.

MCP는 AI 애플리케이션이 여러 도구를 일관된 방식으로 발견하고 사용할 수 있게 만드는 프로토콜이다.

비유하면 API는 각 가게의 개별 출입문이고, MCP는 AI가 여러 가게에 들어갈 때 사용할 수 있는 공통 출입 방식에 가깝다.

구분	API	MCP
목적	특정 서비스 기능 제공	AI와 외부 도구 연결 표준화
사용 주체	개발자, 서버, 앱	AI 앱, AI 에이전트
연결 방식	서비스마다 다름	공통 프로토콜 기반
예시	GitHub API 직접 호출	GitHub MCP 서버를 통해 AI가 사용

MCP가 API를 대체한다기보다는, 기존 API를 AI가 사용하기 좋은 형태로 감싸는 역할에 가깝다.

플러그인과 MCP는 무엇이 다를까?

MCP는 AI 플러그인과도 비교된다.

플러그인은 특정 AI 서비스에 붙는 확장 기능으로 이해할 수 있다. 예를 들어 어떤 챗봇에만 작동하는 전용 확장 기능이 있을 수 있다.

반면 MCP는 특정 앱 하나에만 묶이기보다, 여러 AI 앱과 도구 사이에서 사용할 수 있는 표준을 지향한다.

이 차이가 중요하다.

플러그인 방식은 편하지만, 특정 플랫폼에 종속되기 쉽다. 반면 MCP 방식은 같은 MCP 서버를 여러 AI 클라이언트에서 활용할 가능성이 있다.

실제로 MCP는 Claude뿐 아니라 ChatGPT, Cursor, Gemini, Microsoft Copilot, Visual Studio Code 등 주요 AI 제품과 개발 환경으로 확산되었다고 Anthropic은 2025년 말 발표했다.

MCP를 사용하면 무엇이 좋아질까?

MCP의 가장 큰 장점은 연결 방식의 표준화다.

AI 앱마다 도구 연동을 따로 만들 필요가 줄어든다. MCP 서버를 만들면 MCP를 지원하는 여러 클라이언트에서 재사용할 수 있다.

개발자 입장에서는 다음과 같은 장점이 있다.

같은 도구 연동을 여러 AI 앱에서 활용 가능
로컬 파일, DB, API 연동 구조를 표준화 가능
AI 에이전트 개발 시 도구 연결 비용 감소
Claude, Cursor, VS Code 같은 개발 환경과 연결 가능

사용자 입장에서는 AI가 더 실질적인 작업을 할 수 있게 된다.

단순히 “방법을 알려주는 AI”에서 “도구를 사용해 작업을 도와주는 AI”로 바뀌는 것이다.

예를 들어 개발자는 코드베이스를 분석하는 AI 에이전트를 만들 수 있고, 회사는 내부 문서 검색이나 업무 자동화에 MCP를 활용할 수 있다.

MCP가 중요한 이유

MCP가 주목받는 이유는 AI 사용 방식이 바뀌고 있기 때문이다.

이전의 AI는 주로 질문에 답하는 도구였다. 하지만 AI 에이전트는 점점 실제 작업 흐름 안으로 들어오고 있다.

코딩 도구에서는 저장소를 읽고, 파일을 수정하고, 테스트를 실행한다. 업무 도구에서는 문서를 찾고, 회의 내용을 정리하고, 외부 서비스와 연결한다.

이런 흐름에서 중요한 것은 “AI 모델이 얼마나 똑똑한가”만이 아니다.

AI가 어떤 도구에 접근할 수 있는지, 어떤 권한으로 접근하는지, 그 연결이 얼마나 안정적이고 안전한지도 중요해진다.

MCP는 이 연결 방식을 표준화하려는 시도다.

2025년 12월에는 Anthropic이 MCP를 Linux Foundation 산하 Agentic AI Foundation에 기부한다고 발표했다. Linux Foundation도 AAIF 출범과 함께 MCP, goose, AGENTS.md 같은 프로젝트를 주요 기여 프로젝트로 소개했다. 이는 MCP가 특정 회사의 단독 기술이 아니라, 더 중립적인 에이전트 AI 생태계 표준으로 발전하려는 흐름으로 볼 수 있다.

MCP를 사용할 때 주의할 점

MCP가 편리하다고 해서 아무 서버나 연결해도 되는 것은 아니다.

MCP 서버는 AI에게 외부 도구 접근 권한을 열어주는 역할을 한다. 파일 시스템, 데이터베이스, GitHub, 사내 문서 같은 민감한 자원과 연결될 수 있다.

따라서 보안 설정이 중요하다.

특히 다음 항목은 반드시 확인해야 한다.

MCP 서버가 어떤 권한을 요구하는가
로컬 파일 접근 범위가 어디까지인가
인증 토큰이나 API 키가 안전하게 관리되는가
신뢰할 수 있는 MCP 서버인가
AI가 실행할 수 있는 작업 범위가 제한되어 있는가
로그와 실행 기록을 확인할 수 있는가

AI 에이전트는 사용자의 요청을 해석해 도구를 호출한다. 이 과정에서 잘못된 프롬프트, 악의적인 문서, 불필요하게 넓은 권한이 결합되면 보안 문제가 생길 수 있다.

MCP 보안과 유지보수에 관한 연구들도 MCP 서버의 취약점, 도구 오염, 권한 검증 문제 등을 지적하고 있다. 따라서 실제 업무 환경에서는 최소 권한 원칙, 신뢰할 수 있는 서버 사용, 실행 로그 관리가 필요하다.

MCP는 개발자에게만 필요한 개념일까?

현재 MCP는 개발자 도구에서 특히 많이 언급된다.

Claude Desktop, Claude Code, Cursor, VS Code, 로컬 파일 시스템, GitHub 연동 같은 사례가 많기 때문이다.

하지만 MCP의 의미는 개발자에게만 한정되지 않는다.

앞으로 AI 에이전트가 업무 도구, 문서 관리, 데이터 분석, 고객 지원, 자동화 시스템과 연결될수록 MCP 같은 연결 표준은 더 중요해질 수 있다.

비개발자라도 MCP의 개념을 이해해두면 AI 도구를 볼 때 다음 질문을 할 수 있다.

이 AI는 어떤 외부 도구와 연결되는가?
내 데이터에 접근할 때 어떤 권한을 사용하는가?
연결 방식이 특정 서비스에 종속되어 있는가?
사내 도구와 연결할 수 있는 구조인가?
보안과 접근 제어는 어떻게 처리되는가?

즉, MCP는 단순한 개발 용어가 아니라 AI 에이전트 시대의 연결 방식에 관한 개념이다.

정리

MCP는 Model Context Protocol의 약자다.

AI 에이전트가 외부 도구, 데이터, 앱과 연결될 수 있도록 만든 표준 프로토콜이다.

기존에는 AI 앱마다 도구 연동을 따로 만들어야 했다. MCP는 이 연결 방식을 표준화해 AI가 파일, 데이터베이스, API, 업무 도구를 더 일관된 방식으로 사용할 수 있게 한다.

핵심 구조는 MCP Host, MCP Client, MCP Server로 나눌 수 있다. 이 중 MCP 서버는 특정 도구나 데이터를 AI가 사용할 수 있는 형태로 제공하는 역할을 한다.

MCP 서버는 Resources, Tools, Prompts 같은 요소를 통해 AI에게 읽을 자료, 실행할 기능, 반복 가능한 작업 템플릿을 제공할 수 있다.

MCP가 중요한 이유는 AI가 단순한 챗봇에서 실제 작업을 수행하는 에이전트로 바뀌고 있기 때문이다.

다만 MCP는 외부 도구 접근 권한을 다루기 때문에 보안 설정이 중요하다. 신뢰할 수 없는 MCP 서버를 연결하거나, 지나치게 넓은 권한을 주는 방식은 피해야 한다.

AI 에이전트를 제대로 이해하려면 모델 성능뿐 아니라 “AI가 외부 도구와 어떻게 연결되는가”도 함께 봐야 한다. 그 중심에 있는 대표적인 표준이 MCP다.

AI 코딩 에이전트란? 코드 자동완성과 무엇이 다를까

notebase — Fri, 22 May 2026 19:02:24 +0900

AI 코딩 에이전트가 무엇인지, 기존 코드 자동완성과 어떤 차이가 있는지 초보자도 이해할 수 있게 정리했습니다. 실제 개발 업무에서 맡길 수 있는 일과 주의할 점까지 함께 설명합니다.

AI 코딩 에이전트는 단순히 코드를 추천하는 도구가 아닙니다. 개발자가 목표를 주면 코드베이스를 읽고, 파일을 수정하고, 테스트를 실행하며, 경우에 따라 PR까지 제안하는 AI 개발 도구에 가깝습니다.

기존 코드 자동완성이 “다음 줄을 추천하는 도구”였다면, AI 코딩 에이전트는 “작업을 맡길 수 있는 도구”에 가깝습니다.

2026년 5월 기준으로 Claude Code, Cursor Agent, OpenAI Codex, GitHub Copilot coding agent 같은 도구들이 이 흐름을 대표합니다. 이들은 단순히 코드를 제안하는 수준을 넘어, 코드베이스를 탐색하고 여러 파일을 수정하며 테스트나 명령어 실행까지 연결되는 방식으로 발전하고 있습니다.

AI 코딩 에이전트란?

AI 코딩 에이전트는 개발자가 자연어로 지시한 작업을 이해하고, 코드 작업을 여러 단계로 나누어 수행하는 AI 도구입니다.

예를 들어 개발자가 이렇게 요청할 수 있습니다.

로그인 실패 시 에러 메시지가 너무 불친절해.
프론트엔드 화면과 API 응답 처리를 확인해서 사용자에게 더 명확한 메시지가 나오도록 수정해줘.

일반적인 코드 자동완성 도구라면 현재 작성 중인 파일 안에서 다음 코드를 추천하는 수준에 머무는 경우가 많습니다.

반면 AI 코딩 에이전트는 보통 다음과 같은 흐름으로 움직입니다.

관련 파일을 찾는다.
기존 코드 구조를 읽는다.
수정 계획을 세운다.
여러 파일을 함께 수정한다.
필요한 경우 테스트나 빌드 명령어를 실행한다.
오류가 나면 다시 수정한다.
변경 내용을 개발자가 검토할 수 있게 정리한다.

즉, AI 코딩 에이전트의 핵심은 코드 생성 자체가 아니라 작업 수행입니다.

최근 AI 코딩 에이전트가 주목받는 배경에는 LLM이 한 번에 참고할 수 있는 정보량, 즉 컨텍스트 윈도우(Context Window) 확대도 있습니다. 여기에 코드 검색, 파일 탐색, RAG 같은 방식이 결합되면서 하나의 파일이 아니라 여러 파일의 관계를 파악하고 수정하는 흐름이 가능해졌습니다.

다만 컨텍스트 윈도우가 커졌다고 해서 AI가 프로젝트 전체를 항상 정확히 이해한다는 뜻은 아닙니다. 관련 없는 파일을 잘못 참고하거나, 오래된 패턴을 따라가거나, 프로젝트의 숨은 규칙을 놓칠 수 있습니다. 그래서 에이전트형 도구일수록 명확한 지시와 결과 검토가 중요합니다.

코드 자동완성과 무엇이 다를까?

코드 자동완성은 개발자가 코드를 작성하는 순간에 도움을 줍니다.

예를 들어 함수 이름을 입력하면 이어질 코드를 추천하거나, 반복적인 패턴을 자동으로 채워줍니다. 개발자가 직접 방향을 잡고, AI는 그 옆에서 빠르게 보조하는 방식입니다.

AI 코딩 에이전트는 한 단계 더 나아갑니다.

개발자가 “이 기능을 추가해줘”, “이 버그를 찾아서 고쳐줘”, “이 구조를 리팩토링해줘”처럼 목표를 주면, AI가 코드베이스 안에서 필요한 작업을 찾아 진행합니다.

정리하면 차이는 다음과 같습니다.

구분	코드 자동완성	AI 코딩 에이전트
역할	작성 중인 코드 보조	개발 작업 단위 수행
작업 범위	한 줄, 함수, 파일 중심	여러 파일, 테스트, PR까지 확장
사용 방식	개발자가 직접 입력하며 추천 받음	목표를 설명하고 작업을 위임
장점	빠르고 가볍다	복잡한 작업을 맡길 수 있다
주의점	맥락이 좁을 수 있다	변경 범위가 커서 검토가 중요하다

가장 중요한 차이는 주도권의 위치입니다.

코드 자동완성에서는 개발자가 거의 모든 흐름을 직접 통제합니다.
AI 코딩 에이전트에서는 개발자가 목표와 기준을 제시하고, AI가 중간 작업을 수행합니다.

물론 최종 책임은 여전히 개발자에게 있습니다.

핵심은 코드 생성 능력이 아니라 작업 방식의 변화입니다. 코드 자동완성은 개발자의 입력을 보조하고, AI 코딩 에이전트는 목표 단위의 작업을 수행합니다.

왜 “에이전트”라고 부를까?

여기서 에이전트라는 말은 단순한 챗봇과 구분하기 위해 사용됩니다.

챗봇은 질문에 답하거나 코드를 보여주는 데 그칠 수 있습니다. 하지만 에이전트는 도구를 사용해 작업을 진행합니다.

AI 코딩 에이전트는 보통 다음과 같은 도구 사용 능력을 가집니다.

프로젝트 파일 읽기
코드 검색
파일 수정
터미널 명령어 실행
테스트 실행
빌드 결과 확인
Git 변경 사항 정리
PR 생성 또는 제안

이런 점에서 AI 코딩 에이전트는 “코드를 알려주는 AI”라기보다 개발 환경 안에서 작업하는 AI에 가깝습니다.

AI 코딩 에이전트가 할 수 있는 일

AI 코딩 에이전트가 잘 맞는 작업은 비교적 목표가 분명하고, 결과를 검증할 수 있는 개발 작업입니다.

예를 들면 다음과 같습니다.

1. 작은 기능 추가

예를 들어 관리자 페이지에 검색 필터를 추가하거나, API 응답 필드를 화면에 표시하는 작업이 있습니다.

이런 작업은 관련 파일이 여러 개일 수 있습니다.

API 타입 정의
화면 컴포넌트
상태 관리 코드
테스트 코드
문서

코드 자동완성은 각 파일을 수정할 때 도움을 줄 수 있습니다.
하지만 AI 코딩 에이전트는 관련 파일을 찾아 한 번에 작업 흐름을 구성할 수 있습니다.

즉, 여러 파일 수정이 필요한 작업에서는 자동완성보다 에이전트 방식이 더 자연스러울 수 있습니다.

2. 버그 수정

에러 로그나 재현 조건을 주면 AI 코딩 에이전트가 관련 코드를 찾아 원인을 추정하고 수정안을 만들 수 있습니다.

다만 이 부분은 반드시 사람이 검토해야 합니다.

AI가 테스트를 통과시켰다고 해서 비즈니스 로직까지 정확히 이해했다고 볼 수는 없습니다. 특히 결제, 인증, 보안, 권한 처리처럼 영향이 큰 영역은 더 조심해야 합니다.

3. 리팩토링

AI 코딩 에이전트는 반복적인 리팩토링에 유용할 수 있습니다.

예를 들어 다음과 같은 작업입니다.

오래된 함수명을 새 이름으로 변경
중복 로직을 공통 함수로 분리
타입 정의 정리
폴더 구조 이동
테스트 코드 보강

이런 작업은 사람이 하면 단순 반복이 많지만, 실수하면 사이드 이펙트가 생기기 쉽습니다.

AI 에이전트에게 맡길 때는 범위를 좁히는 것이 좋습니다.

좋은 예시는 다음과 같습니다.

userProfile 관련 컴포넌트 안에서만 중복된 날짜 포맷팅 로직을 공통 함수로 분리해줘.
다른 화면의 동작은 바꾸지 말고, 기존 테스트가 깨지지 않는지 확인해줘.

나쁜 예시는 다음과 같습니다.

전체 프로젝트 구조를 깔끔하게 바꿔줘.

요청이 넓을수록 AI가 불필요한 변경을 만들 가능성이 커집니다.

4. 테스트 코드 작성

AI 코딩 에이전트는 기존 코드와 테스트 스타일을 읽고 비슷한 방식으로 테스트를 추가하는 데 도움을 줄 수 있습니다.

예를 들어 다음과 같은 요청이 가능합니다.

paymentService의 예외 케이스 테스트가 부족해.
기존 테스트 스타일을 유지해서 실패 응답, 타임아웃, 잘못된 입력 케이스를 추가해줘.

테스트는 AI 에이전트와 궁합이 좋은 편입니다.

이유는 결과를 비교적 명확하게 확인할 수 있기 때문입니다. 테스트가 통과하는지, 커버해야 할 조건이 포함됐는지 개발자가 검토하기 쉽습니다.

코드 자동완성이 여전히 유용한 경우

AI 코딩 에이전트가 등장했다고 해서 코드 자동완성이 필요 없어지는 것은 아닙니다.

오히려 두 도구는 쓰임새가 다릅니다.

코드 자동완성은 다음 상황에서 여전히 유용합니다.

짧은 함수 작성
반복적인 문법 입력
타입 기반 코드 추천
간단한 변환 로직 작성
개발자가 직접 흐름을 통제하고 싶은 경우

예를 들어 배열을 필터링하거나, DTO를 변환하거나, UI 이벤트 핸들러를 작성하는 정도라면 에이전트까지 쓸 필요가 없을 수 있습니다.

이런 작업은 코드 자동완성이 더 빠르고 자연스럽습니다.

반면 AI 코딩 에이전트는 작업 단위가 커질수록 유용합니다.

여러 파일을 함께 수정해야 할 때
기존 구조를 먼저 파악해야 할 때
테스트 실행이 필요한 작업일 때
반복적인 리팩토링이 필요할 때
PR 단위로 작업을 나누고 싶을 때

간단히 말하면, 코드 자동완성은 손을 빠르게 해주고, AI 코딩 에이전트는 작업 흐름을 줄여줍니다.

AI 코딩 에이전트 사용 시 주의할 점

AI 코딩 에이전트를 사용할 때 가장 중요한 것은 검토 책임입니다.

에이전트가 코드를 수정하고 테스트까지 실행할 수 있다고 해도, 그 결과가 항상 안전하다는 뜻은 아닙니다.

특히 다음 부분은 사람이 직접 확인해야 합니다.

1. 변경 범위가 과도하지 않은가

AI 에이전트는 요청을 해결하려다 예상보다 많은 파일을 수정할 수 있습니다.

간단한 버그 수정 요청이었는데 폴더 구조를 바꾸거나, 관련 없는 코드 스타일을 함께 수정하는 경우도 생길 수 있습니다.

따라서 작업을 맡길 때는 범위를 제한하는 것이 좋습니다.

이 파일과 관련 테스트만 수정해줘.
공개 API 스펙은 변경하지 마.
UI 문구 외의 동작은 바꾸지 마.

이런 조건을 함께 주면 결과가 더 안정적입니다.

2. 테스트 통과가 정답은 아니다

테스트가 부족한 프로젝트에서는 AI가 만든 코드가 테스트를 통과해도 실제 서비스에서는 문제가 생길 수 있습니다.

테스트가 검증하지 않는 영역은 AI도 놓치기 쉽습니다.

따라서 에이전트에게 작업을 맡기기 전에 다음을 확인하는 편이 좋습니다.

핵심 로직 테스트가 있는가
실패 케이스 테스트가 있는가
권한, 보안, 결제 관련 테스트가 있는가
변경 후 사람이 직접 확인해야 할 시나리오가 정리되어 있는가

테스트 통과가 정답은 아닙니다.
테스트가 확인하지 않는 부분은 여전히 개발자가 직접 봐야 합니다.

3. 보안 정보 노출에 주의해야 한다

AI 코딩 에이전트가 코드베이스, 터미널, 외부 도구와 연결될수록 권한 관리가 중요해집니다.

API 키, 인증 토큰, 고객 정보, 내부 인프라 정보가 노출되지 않도록 주의해야 합니다.

특히 회사 프로젝트에서는 다음을 확인해야 합니다.

어떤 저장소에 접근할 수 있는지
어떤 명령어를 실행할 수 있는지
인터넷 접근이 허용되는지
비밀 정보가 프롬프트나 로그에 포함되지 않는지
생성된 코드가 라이선스나 보안 정책을 위반하지 않는지

AI 코딩 에이전트는 강력한 도구일수록 접근 권한도 중요해집니다.

4. 아키텍처 판단은 개발자가 해야 한다

AI는 코드를 빠르게 수정할 수 있지만, 제품의 방향이나 시스템 설계 의도를 완전히 이해한다고 보기 어렵습니다.

예를 들어 다음과 같은 판단은 개발자가 주도해야 합니다.

이 기능을 어디에 배치할 것인가
기존 구조를 유지할 것인가, 바꿀 것인가
성능과 유지보수성 중 무엇을 우선할 것인가
보안상 허용 가능한 방식인가
장기적으로 기술 부채가 늘어나지 않는가

AI 코딩 에이전트는 실행 도구로는 유용하지만, 설계 책임까지 넘기기는 어렵습니다.

AI 코딩 에이전트는 강력한 개발 보조 도구이지만, 변경 범위와 결과의 안전성은 여전히 개발자가 판단해야 합니다.

AI 코딩 에이전트를 잘 쓰는 방법

AI 코딩 에이전트를 잘 쓰려면 요청을 구체적으로 작성해야 합니다.

막연한 요청보다 조건이 있는 요청이 좋습니다.

예를 들어 다음처럼 작성할 수 있습니다.

회원가입 폼에서 이메일 형식 검증을 추가해줘.
기존 UI 스타일은 유지하고, 검증 실패 시 입력창 아래에 에러 메시지를 보여줘.
관련 테스트가 있다면 함께 수정하고, 없으면 최소한의 테스트를 추가해줘.

이 요청에는 목표, 범위, UI 조건, 테스트 조건이 포함되어 있습니다.

반대로 다음 요청은 위험합니다.

회원가입 기능 개선해줘.

무엇을 개선해야 하는지 불명확합니다.
AI가 임의로 판단할 여지가 커집니다.

좋은 요청에는 보통 다음 요소가 들어갑니다.

해결하고 싶은 문제
수정해도 되는 범위
수정하면 안 되는 범위
따라야 할 코드 스타일
테스트 실행 방법
완료 기준

프로젝트에 따라 AGENTS.md, CLAUDE.md 같은 지침 파일을 두는 경우도 있습니다. 이런 파일은 에이전트가 매번 같은 기준으로 작업하도록 돕는 역할을 합니다.

예시는 다음과 같습니다.

# AI coding agent instructions

- 기존 코드 스타일을 유지한다.
- 수정 범위는 요청받은 기능과 관련 파일로 제한한다.
- 테스트 명령어는 `npm test`를 사용한다.
- API 응답 형식은 변경하지 않는다.
- 보안 관련 파일은 사용자 확인 없이 수정하지 않는다.
- 대규모 리팩토링이 필요하면 먼저 변경 계획을 제안한다.

이런 지침 파일이 있으면 에이전트가 프로젝트의 기본 규칙을 더 잘 따를 수 있습니다.

물론 지침 파일이 모든 문제를 해결하지는 않습니다. 그래도 테스트 명령어, 수정 금지 영역, 코드 스타일 같은 반복 규칙을 명시해 두면 매번 같은 설명을 반복하지 않아도 됩니다.

개발자는 앞으로 무엇을 해야 할까?

AI 코딩 에이전트가 발전하면 개발자의 역할은 단순 코딩에서 점점 더 넓어질 가능성이 큽니다.

코드를 한 줄씩 직접 작성하는 능력도 여전히 중요합니다.
하지만 앞으로는 다음 능력이 더 중요해질 수 있습니다.

문제를 정확히 정의하는 능력
작업 범위를 나누는 능력
AI가 만든 변경 사항을 리뷰하는 능력
테스트와 검증 기준을 설계하는 능력
아키텍처 방향을 판단하는 능력
보안과 운영 리스크를 관리하는 능력

AI 코딩 에이전트는 개발자를 대체한다기보다, 개발자가 다루는 작업 단위를 바꾸고 있습니다.

이전에는 개발자가 직접 코드를 작성하는 시간이 많았다면, 이제는 AI에게 작업을 맡기고 결과를 검토하는 시간이 늘어날 수 있습니다.

그렇다고 개발 지식이 덜 중요해지는 것은 아닙니다.

오히려 AI가 만든 코드가 맞는지 판단하려면 더 정확한 이해가 필요합니다.
기초가 부족하면 AI가 만든 결과를 그대로 받아들이게 되고, 그만큼 위험도 커집니다.

정리

AI 코딩 에이전트는 코드 자동완성의 확장판처럼 보이지만, 실제로는 사용 방식이 다릅니다.

코드 자동완성은 개발자가 작성 중인 코드를 빠르게 완성하도록 돕습니다.
AI 코딩 에이전트는 개발자가 맡긴 작업을 코드베이스 안에서 직접 수행합니다.

따라서 둘 중 하나만 선택해야 하는 관계는 아닙니다.

짧고 명확한 코드는 자동완성이 편합니다.
여러 파일을 수정하거나 테스트까지 확인해야 하는 작업은 AI 코딩 에이전트가 유용할 수 있습니다.

다만 에이전트가 강력해질수록 검토 책임도 커집니다.

AI에게 코딩을 맡길 수는 있지만, 무엇을 만들지, 어디까지 바꿀지, 결과가 안전한지는 여전히 개발자가 판단해야 합니다.

HBM이란? 초보자도 이해하는 고대역폭 메모리 개념

notebase — Fri, 22 May 2026 13:46:11 +0900

HBM이란 고대역폭 메모리로, 여러 개의 D램을 수직으로 쌓아 GPU와 AI 반도체에 빠르게 데이터를 전달하는 메모리입니다. HBM의 뜻, 원리, D램과의 차이, 장단점을 초보자 기준으로 쉽게 정리합니다.

HBM이란 High Bandwidth Memory의 줄임말로, 한국어로는 고대역폭 메모리라고 부릅니다. AI 반도체와 GPU가 많은 데이터를 빠르게 처리할 수 있도록 돕는 고성능 메모리입니다.

뉴스에서 HBM이라는 단어가 자주 나오는 이유는 간단합니다.

AI가 발전할수록 연산해야 할 데이터가 많아지고, 그 데이터를 빠르게 공급해 줄 메모리가 중요해졌기 때문입니다. GPU가 아무리 빠르게 계산할 수 있어도, 필요한 데이터를 제때 받지 못하면 성능을 제대로 내기 어렵습니다.

HBM은 이 문제를 줄이기 위해 등장한 메모리입니다.

HBM 뜻부터 이해하기

HBM은 High Bandwidth Memory의 약자입니다.

여기서 중요한 단어는 Bandwidth, 즉 대역폭입니다. 대역폭은 한 번에 데이터를 얼마나 많이 보낼 수 있는지를 뜻합니다.

쉽게 말하면 도로의 차선 수와 비슷합니다.

차선이 좁으면 차가 많이 막힙니다.
차선이 넓으면 더 많은 차가 동시에 지나갈 수 있습니다.
메모리도 마찬가지로 데이터가 지나가는 길이 넓을수록 더 많은 데이터를 빠르게 보낼 수 있습니다.

HBM은 이 데이터 통로를 크게 넓힌 메모리라고 보면 됩니다.

HBM은 왜 빠른 메모리라고 불릴까?

일반적인 메모리는 메모리 칩을 기판 위에 옆으로 배치하는 방식이 많습니다. 반면 HBM은 여러 개의 D램 칩을 위로 쌓는 구조를 사용합니다.

즉, 평면으로 넓게 펼치는 대신 수직으로 쌓는 방식입니다.

이렇게 쌓은 D램 칩들은 내부 연결 기술을 통해 짧은 거리에서 데이터를 주고받습니다. 데이터가 이동하는 거리가 짧고, 통로가 넓기 때문에 많은 데이터를 빠르게 전달할 수 있습니다.

HBM을 이해할 때 핵심은 다음 3가지입니다.

1. 여러 개의 D램을 위로 쌓는다. 2. 칩 사이를 촘촘하게 연결한다. 3. GPU나 AI 가속기 가까이에 배치해 데이터를 빠르게 주고받는다.

이 구조 덕분에 HBM은 일반 D램보다 높은 대역폭을 제공할 수 있습니다.

일반 D램과 HBM의 차이

일반 D램과 HBM은 모두 데이터를 임시로 저장하는 메모리입니다. 하지만 구조와 사용 목적이 다릅니다.

일반 D램 / HBM 구조 비교

구분	일반 D램	HBM
구조	칩을 주로 평면적으로 배치	여러 D램 칩을 수직으로 적층
강점	가격 경쟁력, 범용성, 대용량 구성	높은 대역폭, 전력 효율, 공간 효율
주 사용처	PC, 노트북, 일반 서버 메모리	GPU, AI 가속기, 슈퍼컴퓨터
핵심 특징	표준화된 범용 메모리	고성능 반도체 패키지에 함께 탑재되는 특수 메모리
단점	물리적인 대역폭 한계	높은 제조 난도와 비싼 가격

초보자 관점에서는 이렇게 이해하면 됩니다.

일반 D램은 넓게 쓰이는 범용 메모리이고, HBM은 AI·GPU 같은 고성능 연산을 위해 데이터 통로를 넓힌 특수 메모리입니다.

다만 HBM이 일반 D램의 완전한 대체재라는 뜻은 아닙니다. HBM은 대역폭이 중요한 고성능 환경에 적합하고, 일반 D램은 가격과 범용성이 중요한 환경에 적합합니다.

HBM이 AI 반도체에서 중요한 이유

AI 모델은 엄청난 양의 데이터를 반복해서 읽고 계산합니다.

예를 들어 생성형 AI가 문장을 만들거나 이미지를 생성할 때, 내부적으로는 수많은 숫자 계산이 계속 일어납니다. 이때 GPU나 AI 가속기는 계산을 담당하고, 메모리는 계산에 필요한 데이터를 계속 공급합니다.

문제는 연산 장치가 빨라질수록 메모리도 빨라져야 한다는 점입니다.

연산 장치가 데이터를 기다리느라 멈추는 시간이 길어지면 전체 성능이 떨어집니다. 이것을 쉽게 표현하면 데이터 병목이라고 할 수 있습니다.

HBM은 이 병목을 줄이는 데 중요한 역할을 합니다.

AI 모델이 커질수록 필요한 데이터 양이 늘어납니다.
GPU는 더 많은 데이터를 빠르게 받아야 합니다.
HBM은 넓은 대역폭으로 데이터를 공급합니다.
결과적으로 AI 연산 성능을 끌어올리는 데 도움을 줍니다.

그래서 HBM은 AI 반도체, GPU, 데이터센터 관련 뉴스에서 자주 함께 언급됩니다.

HBM의 장점

1. 데이터 전송 속도가 빠르다

HBM의 가장 큰 장점은 높은 대역폭입니다.

한 번에 많은 데이터를 이동시킬 수 있기 때문에 GPU나 AI 가속기가 데이터를 기다리는 시간을 줄일 수 있습니다. 특히 AI 학습, AI 추론, 고성능 컴퓨팅처럼 데이터 이동량이 많은 작업에서 유리합니다.

2. 전력 효율이 좋다

HBM은 칩 사이의 거리가 짧고, 넓은 통로로 데이터를 전달합니다. 이 구조는 같은 양의 데이터를 처리할 때 전력 효율을 높이는 데 도움이 됩니다.

AI 데이터센터에서는 성능만큼 전력 소비도 중요합니다. 서버가 많아질수록 전기요금과 냉각 비용이 커지기 때문입니다.

3. 공간을 적게 차지한다

HBM은 D램을 수직으로 쌓는 구조입니다.

같은 면적에서 더 많은 메모리 용량과 높은 대역폭을 구현할 수 있습니다. 공간이 제한된 GPU 패키지 안에서 고성능 메모리를 넣어야 할 때 유리합니다.

HBM의 단점과 한계

HBM이 항상 좋은 선택인 것은 아닙니다. 장점이 뚜렷한 만큼 단점도 있습니다.

1. 제조 난도가 높다

HBM은 여러 개의 D램을 수직으로 쌓고 정밀하게 연결해야 합니다.

단순히 메모리 칩을 많이 붙이는 문제가 아닙니다. 적층, 연결, 패키징, 발열 관리까지 모두 높은 기술 수준이 필요합니다.

2. 가격이 비싸다

제조 공정이 복잡하고 수율 관리가 어렵기 때문에 일반 D램보다 가격이 비쌉니다.

그래서 HBM은 일반 소비자용 PC보다는 AI 서버, 데이터센터, 고성능 GPU 같은 기업형·고성능 분야에 주로 사용됩니다.

3. 발열 관리가 어렵다

D램을 위로 쌓으면 공간 효율은 좋아지지만, 열을 관리하기는 더 어려워질 수 있습니다.

특히 층수가 높아질수록 내부에서 발생한 열을 밖으로 빼내는 설계가 중요해집니다. HBM이 발전할수록 성능뿐 아니라 냉각과 안정성도 함께 중요해지는 이유입니다.

4. 공급을 빠르게 늘리기 어렵다

HBM은 일반 D램보다 생산 과정이 복잡합니다. 고객사 요구에 맞춘 검증과 패키징 과정도 중요합니다.

따라서 수요가 갑자기 늘어나도 공급량을 단기간에 크게 늘리기 어렵습니다. HBM 관련 뉴스에서 수율, 양산, 고객사 인증, 공급 계약 같은 표현이 자주 나오는 이유입니다.

HBM 세대는 어떻게 발전했나

HBM은 한 번에 완성된 기술이 아닙니다. 세대를 거치면서 속도, 용량, 효율이 계속 개선되어 왔습니다.

대표적인 흐름은 다음과 같습니다.

세대	설명
HBM	1세대 고대역폭 메모리
HBM2	대역폭과 용량 개선
HBM2E	HBM2의 확장형 성격
HBM3	AI·고성능 컴퓨팅 수요에 맞춰 성능 향상
HBM3E	HBM3의 확장형으로, 2026년 기준 AI 반도체 분야에서 많이 언급
HBM4	차세대 고성능 AI·HPC 환경을 겨냥한 세대

단, 세대 이름만 보고 무조건 “최신이면 항상 좋다”고 판단하면 안 됩니다.

실제 성능은 용량, 대역폭, 전력 효율, 발열, 고객사 요구사항, 패키징 방식에 따라 달라집니다. 또한 어떤 GPU나 AI 가속기에 탑재되는지도 중요합니다.

HBM3E와 HBM4는 무엇인가

HBM3E는 HBM3의 확장형 세대로 볼 수 있습니다. AI 서버와 고성능 GPU 수요가 커지면서 더 높은 대역폭과 용량을 제공하기 위해 등장했습니다.

2026년 기준으로 HBM3E는 AI 반도체 시장에서 자주 언급되는 핵심 메모리입니다. 삼성전자, SK하이닉스, 마이크론 같은 메모리 업체들이 관련 제품과 기술을 경쟁적으로 개발하고 있습니다.

HBM4는 그다음 세대입니다.

HBM4는 더 높은 대역폭과 효율, 더 큰 용량을 목표로 합니다. AI 모델이 계속 커지고 데이터센터의 연산 수요가 늘어나면서 HBM4 같은 차세대 메모리의 중요성도 커지고 있습니다.

다만 일반 독자 입장에서는 세부 규격까지 모두 외울 필요는 없습니다.

핵심은 이것입니다.

HBM3E와 HBM4는 AI 반도체가 더 많은 데이터를 더 빠르게 처리하기 위해 발전 중인 고성능 메모리 세대입니다.

HBM은 GPU인가, RAM인가, SSD인가?

HBM을 처음 접하면 다른 부품과 헷갈리기 쉽습니다.

HBM은 GPU가 아니다

GPU는 연산을 담당하는 반도체입니다. HBM은 GPU 옆에서 데이터를 공급하는 메모리입니다.

즉, GPU가 계산하는 엔진이라면 HBM은 그 엔진에 연료를 빠르게 공급하는 장치에 가깝습니다.

HBM은 일반 RAM과 같은 역할을 하지만 구조가 다르다

HBM도 넓은 의미에서는 D램 계열 메모리입니다. 데이터를 임시로 저장하고 빠르게 읽고 쓰는 역할을 합니다.

다만 PC에 꽂는 일반 RAM과는 구조, 가격, 사용처가 다릅니다.

HBM은 SSD가 아니다

SSD는 데이터를 장기간 저장하는 저장장치입니다. 컴퓨터를 꺼도 파일이 남아 있습니다.

반면 HBM은 연산 중 필요한 데이터를 빠르게 주고받기 위한 메모리입니다. 전원이 꺼지면 데이터가 유지되는 저장장치가 아닙니다.

HBM이 모든 컴퓨터에 들어가지 않는 이유

HBM이 빠르다면 모든 컴퓨터에 넣으면 좋을 것 같지만, 현실은 그렇지 않습니다.

가장 큰 이유는 비용과 필요성입니다.

일반적인 문서 작업, 웹서핑, 영상 시청, 가벼운 게임에서는 HBM의 높은 대역폭이 꼭 필요하지 않습니다. 일반 D램만으로도 충분한 경우가 많습니다.

HBM은 다음과 같은 환경에서 가치가 커집니다.

대규모 AI 모델 학습
생성형 AI 추론 서버
고성능 GPU
슈퍼컴퓨터
고성능 데이터센터
전문 그래픽·연산 장비

즉, HBM은 모든 기기에 필요한 메모리라기보다 데이터를 매우 빠르게 처리해야 하는 고성능 영역에 적합한 메모리입니다.

HBM 관련 뉴스를 읽을 때 봐야 할 포인트

HBM 관련 뉴스를 볼 때는 단순히 “HBM을 만든다”는 표현만 보면 부족합니다. 아래 요소를 함께 보면 기사 내용을 더 정확하게 이해할 수 있습니다.

몇 세대 HBM인가?

HBM3인지, HBM3E인지, HBM4인지에 따라 의미가 다릅니다. 세대가 높아질수록 일반적으로 더 높은 성능을 목표로 하지만, 실제 경쟁력은 세부 사양을 함께 봐야 합니다.

몇 단으로 쌓았는가?

HBM은 여러 개의 D램을 쌓는 구조입니다. 8단, 12단, 16단처럼 적층 수가 언급되는 경우가 많습니다. 적층 수가 늘어나면 용량을 키우는 데 유리하지만, 제조 난도와 발열 관리도 함께 중요해집니다.

어떤 칩과 결합하는가?

HBM은 혼자 쓰이는 부품이 아닙니다. GPU나 AI 가속기와 함께 사용됩니다. 따라서 어떤 GPU 또는 AI 가속기에 탑재되는지, 어떤 고객사와 연결되는지가 중요합니다.

개발인지, 샘플 공급인지, 양산인지 구분했는가?

반도체 뉴스에서 개발 성공, 샘플 공급, 양산, 공급 계약은 각각 의미가 다릅니다. 개발에 성공했다는 말이 곧바로 대량 양산과 매출 발생을 뜻하지는 않습니다.

수율과 패키징 이슈가 언급되는가?

HBM은 성능뿐 아니라 안정적인 생산도 중요합니다. 따라서 수율, 고객사 인증, 패키징 기술, 발열 관리 같은 표현이 함께 등장하면 눈여겨볼 필요가 있습니다.

초보자를 위한 한 문장 정리

HBM은 여러 개의 D램을 수직으로 쌓아 데이터가 지나가는 통로를 넓힌 고성능 메모리입니다.

AI 반도체에서 HBM이 중요한 이유는 GPU와 AI 가속기가 더 많은 데이터를 더 빠르게 받아야 하기 때문입니다. 연산 장치가 빨라질수록 메모리의 역할도 커지고, HBM은 그 병목을 줄이는 핵심 부품으로 주목받고 있습니다.

다만 HBM은 제조가 어렵고 가격이 비싸며, 모든 컴퓨터에 필요한 메모리는 아닙니다. 일반 PC보다 AI 서버, 데이터센터, 고성능 GPU처럼 대규모 데이터를 빠르게 처리해야 하는 분야에서 가치가 큽니다.

HBM을 이해하면 AI 반도체 뉴스를 읽을 때 왜 메모리 기업들이 함께 주목받는지 훨씬 쉽게 파악할 수 있습니다.

FAQ

HBM은 일반 RAM보다 무조건 좋은가요?

용도에 따라 다릅니다. HBM은 높은 대역폭이 필요한 AI 연산, GPU, 고성능 컴퓨팅에 유리합니다. 하지만 일반 PC 작업에서는 가격과 구조상 일반 D램이 더 적합한 경우가 많습니다.

HBM은 SSD와 같은 저장장치인가요?

아닙니다. SSD는 데이터를 장기간 저장하는 장치이고, HBM은 연산 중 데이터를 빠르게 주고받는 메모리입니다.

HBM이 AI 반도체에서 중요한 이유는 무엇인가요?

AI 연산은 많은 데이터를 계속 읽고 계산해야 합니다. HBM은 GPU나 AI 가속기에 데이터를 빠르게 공급해 병목을 줄이는 역할을 합니다.

HBM3E와 HBM4는 무엇이 다른가요?

HBM3E는 HBM3의 확장형 세대이고, HBM4는 그다음 세대입니다. HBM4는 더 높은 대역폭과 효율, 용량을 목표로 하는 차세대 규격입니다. 다만 실제 제품 성능은 제조사, 적층 수, 패키징, 탑재되는 시스템에 따라 달라질 수 있습니다.

참고 자료

Samsung Semiconductor, HBM3E 제품 소개: https://semiconductor.samsung.com/dram/hbm/hbm3e/
Samsung Newsroom, HBM3E 12H DRAM 발표 자료: https://news.samsung.com/global/samsung-develops-industry-first-36gb-hbm3e-12h-dram
SK hynix Newsroom, HBM 기술 및 AI 메모리 관련 자료: https://news.skhynix.co.kr/
JEDEC HBM3 표준 발표 자료: https://www.businesswire.com/news/home/20220127005320/en/JEDEC-Publishes-HBM3-Update-to-High-Bandwidth-Memory-HBM-Standard

AI 반도체가 주목받는 이유: GPU와 HBM이 중요한 진짜 이유

notebase — Fri, 22 May 2026 13:29:12 +0900

AI 반도체가 주목받는 이유를 GPU, HBM, 데이터센터, 생성형 AI 수요 관점에서 쉽게 정리했습니다. 기존 반도체와 다른 점, 산업 변화, 주의할 점까지 함께 설명합니다.

AI 반도체가 주목받는 이유는 단순히 인공지능이 유행하기 때문만은 아닙니다. 생성형 AI, 데이터센터, 클라우드 서비스가 커지면서 기존 반도체보다 훨씬 많은 연산과 메모리 성능이 필요해졌기 때문입니다.

예전에는 반도체 시장을 이야기할 때 스마트폰, PC, 자동차가 중심이었습니다.

지금은 여기에 AI 데이터센터가 강하게 들어왔습니다.
ChatGPT 같은 생성형 AI 서비스, 이미지 생성 AI, AI 검색, 코딩 도구, 기업용 AI 솔루션이 늘어나면서 서버 안에서 엄청난 계산을 처리할 반도체가 필요해졌습니다.

이때 필요한 반도체가 바로 AI 반도체입니다.

다만 AI 반도체는 GPU 하나만을 뜻하지 않습니다. GPU, NPU, HBM, AI 가속기, 첨단 패키징까지 포함한 AI 연산 인프라 전체로 보는 것이 더 정확합니다.

AI 반도체란 무엇인가

AI 반도체는 인공지능 연산을 빠르고 효율적으로 처리하기 위해 설계된 반도체를 말합니다.

일반적인 CPU도 AI 연산을 할 수는 있습니다.
하지만 대규모 AI 모델을 학습시키거나, 많은 사용자의 요청을 동시에 처리하기에는 효율이 떨어집니다.

AI는 같은 계산을 대량으로 반복하는 작업이 많습니다.
그래서 병렬 연산에 강한 반도체가 유리합니다.

대표적인 AI 반도체는 다음과 같습니다.

구분	설명	주로 쓰이는 곳
GPU	대규모 병렬 연산에 강한 칩	AI 학습, 데이터센터
NPU	AI 연산에 특화된 칩	스마트폰, 노트북, 엣지 기기
TPU·ASIC	특정 AI 작업에 맞게 설계된 칩	클라우드, 대형 플랫폼
HBM	AI 칩에 데이터를 빠르게 공급하는 고대역폭 메모리	AI 서버, 고성능 GPU

여기서 중요한 점은 AI 반도체가 단일 부품만을 의미하지 않는다는 것입니다.

GPU만 좋아도 충분하지 않습니다.
메모리, 패키징, 네트워크, 전력 관리, 냉각 기술까지 함께 맞물려야 AI 서버가 제대로 작동합니다.

AI 반도체가 갑자기 중요해진 이유

1. 생성형 AI는 연산량이 매우 크다

생성형 AI는 질문에 답하거나 이미지를 만들 때마다 많은 계산을 수행합니다.

특히 대규모 언어 모델은 수많은 파라미터, 즉 AI가 학습한 판단 기준을 바탕으로 다음 단어를 예측합니다.
사용자가 많아질수록 서버는 더 많은 요청을 처리해야 합니다.

AI 서비스가 커질수록 필요한 것은 두 가지입니다.

첫째, AI 모델을 학습시키는 연산 성능입니다.
둘째, 실제 사용자의 요청을 빠르게 처리하는 추론 성능입니다. 추론은 이미 학습된 AI 모델을 실제 서비스에서 사용하는 단계를 말합니다.

초기에는 학습용 GPU 수요가 크게 주목받았습니다.
하지만 AI 서비스가 실제 제품에 들어가면서 추론용 반도체 수요도 점점 커지고 있습니다.

즉, AI 반도체 수요는 “AI를 개발할 때”만 생기는 것이 아닙니다.
AI를 서비스하고 운영하는 과정에서도 계속 발생합니다.

2. 데이터센터 투자가 빠르게 늘고 있다

AI 반도체 수요의 중심에는 데이터센터가 있습니다.

AI 모델은 개인 PC 한 대에서 처리하기 어렵습니다.
대부분의 대형 AI 서비스는 클라우드 데이터센터에서 작동합니다.

데이터센터에는 GPU, HBM, 네트워크 장비, 저장장치, 전력 설비, 냉각 시스템이 함께 들어갑니다.

특히 엔비디아의 실적을 보면 AI 데이터센터 수요가 얼마나 큰지 확인할 수 있습니다. NVIDIA는 2026년 1월 25일 종료된 2026 회계연도 4분기 실적에서 데이터센터 매출이 623억 달러, 전년 대비 75% 증가했다고 발표했습니다.

이 숫자는 AI 반도체가 단순한 기술 트렌드가 아니라 실제 매출로 연결되고 있다는 점을 보여줍니다.

3. GPU만큼 HBM도 중요해졌다

AI 반도체를 이야기할 때 GPU만 주목하기 쉽습니다.
하지만 실제로는 HBM도 핵심 부품입니다.

HBM은 High Bandwidth Memory의 약자입니다.
말 그대로 데이터를 매우 빠르게 주고받을 수 있는 고대역폭 메모리입니다.

AI 연산에서는 칩이 아무리 빨라도 데이터를 제때 공급받지 못하면 성능이 떨어집니다.
GPU가 계산을 담당한다면, HBM은 계산할 데이터를 빠르게 전달하는 역할을 합니다.

AI 모델이 커질수록 더 많은 데이터를 동시에 처리해야 합니다.
그래서 AI 서버에는 일반 메모리보다 훨씬 비싼 HBM이 사용됩니다.

이 때문에 SK하이닉스, 삼성전자, 마이크론 같은 메모리 기업도 AI 반도체 흐름에서 중요한 위치를 차지하게 됐습니다.

4. 기존 반도체 시장의 중심이 바뀌고 있다

과거 반도체 수요는 스마트폰, PC, TV, 가전, 자동차가 중심이었습니다.

물론 지금도 이 시장은 중요합니다.
하지만 성장의 중심은 AI 인프라 쪽으로 이동하고 있습니다.

Gartner는 2026년 전 세계 반도체 매출이 1조 3천억 달러를 넘을 것으로 전망했습니다. 또한 AI 반도체가 전체 반도체 매출의 약 30%를 차지할 것으로 봤습니다.

이는 AI 반도체가 일부 고성능 서버에만 쓰이는 특수 부품이 아니라, 반도체 산업 전체의 성장 방향을 바꾸는 핵심 분야가 됐다는 의미입니다.

기존 반도체와 AI 반도체는 무엇이 다를까

기존 반도체는 범용성이 중요했습니다.

CPU는 운영체제 실행, 문서 작업, 웹 브라우징, 앱 실행처럼 다양한 작업을 처리합니다.
하지만 AI 연산은 성격이 다릅니다.

AI는 대규모 행렬 계산, 반복 연산, 병렬 처리 비중이 큽니다.
그래서 범용 CPU보다 GPU나 AI 전용 칩이 더 효율적입니다.

쉽게 비유하면 이렇습니다.

CPU는 여러 일을 골고루 처리하는 사무직에 가깝습니다.
GPU는 같은 유형의 계산을 수천 개씩 동시에 처리하는 대규모 작업반에 가깝습니다.
NPU나 ASIC은 특정 AI 업무에 맞춰 설계된 전용 장비에 가깝습니다.

AI 시대에는 “어떤 반도체가 가장 빠른가”보다 “어떤 작업을 가장 효율적으로 처리하는가”가 더 중요해지고 있습니다.

AI 반도체가 중요한 산업들

AI 반도체는 데이터센터에만 쓰이지 않습니다.

앞으로는 여러 산업으로 확산될 가능성이 큽니다.

클라우드와 검색 서비스

AI 검색, 챗봇, 문서 요약, 코드 생성 서비스는 대부분 클라우드에서 작동합니다.
사용자가 질문할 때마다 서버에서는 AI 연산이 발생합니다.

이 분야에서는 GPU, AI 가속기, HBM, 네트워크 반도체가 중요합니다.

스마트폰과 PC

스마트폰과 노트북에도 AI 기능이 들어가고 있습니다.
사진 보정, 음성 인식, 실시간 번역, 문서 요약 같은 기능은 기기 안에서 직접 처리될 수 있습니다.

이때는 서버용 GPU보다 저전력 NPU가 중요합니다.

자동차

자율주행과 운전자 보조 시스템에도 AI 반도체가 필요합니다.
차량은 카메라, 레이더, 라이다 등에서 들어오는 데이터를 실시간으로 처리해야 합니다.

속도뿐 아니라 안정성, 전력 효율, 발열 관리도 중요합니다.

로봇과 산업 자동화

로봇은 주변 환경을 인식하고, 움직임을 판단하고, 상황에 맞게 반응해야 합니다.
이 과정에서도 AI 연산이 필요합니다.

AI 반도체는 로봇이 클라우드에만 의존하지 않고 현장에서 빠르게 판단하도록 돕는 역할을 할 수 있습니다.

왜 엔비디아가 자주 언급될까

AI 반도체 뉴스에서 엔비디아가 자주 나오는 이유는 GPU 시장에서 강한 위치를 갖고 있기 때문입니다.

엔비디아는 단순히 GPU만 파는 회사가 아닙니다.
AI 개발에 필요한 소프트웨어 생태계, 개발 도구, 서버 시스템, 네트워크 기술까지 함께 제공합니다.

AI 기업 입장에서는 칩 성능만 보는 것이 아닙니다.

개발 환경이 안정적인지, 기존 AI 프레임워크와 잘 맞는지, 대규모 서버 운영이 쉬운지도 중요합니다.
이 부분에서 엔비디아는 강한 생태계를 구축해 왔습니다.

다만 AI 반도체 시장이 엔비디아만의 시장으로 고정된 것은 아닙니다.
구글, 아마존, 마이크로소프트 같은 빅테크 기업은 자체 AI 칩을 개발하고 있습니다. AMD, 브로드컴, 인텔 등도 AI 반도체 시장을 공략하고 있습니다.

앞으로는 범용 GPU와 맞춤형 AI 칩이 함께 경쟁하는 구조가 될 가능성이 큽니다.

AI 반도체가 계속 성장하려면 필요한 조건

AI 반도체 시장이 커지려면 단순히 AI에 대한 관심만으로는 부족합니다.

실제 서비스에서 비용 대비 효과가 나와야 합니다.

AI 모델을 운영하려면 막대한 서버 비용이 필요합니다.
전기료, 냉각 비용, 장비 비용, 유지보수 비용도 함께 증가합니다.

기업이 AI 인프라에 계속 투자하려면 AI 서비스가 실제 매출 증가, 비용 절감, 업무 효율 개선으로 이어져야 합니다.

또 하나의 변수는 공급망입니다.

AI 반도체는 설계만 잘한다고 바로 만들 수 없습니다.
첨단 파운드리, HBM 공급, 첨단 패키징, 반도체 장비, 소재가 모두 필요합니다.

특정 공정이나 부품에서 병목이 생기면 전체 공급이 제한될 수 있습니다.
최근 AI 수요가 커지면서 HBM, 첨단 패키징, 반도체 장비 쪽이 함께 주목받는 이유도 여기에 있습니다.

AI 반도체를 볼 때 주의할 점

AI 반도체가 중요한 것은 맞지만, 모든 반도체 기업이 같은 방식으로 수혜를 받는 것은 아닙니다.

AI 반도체 시장은 크게 보면 성장하고 있지만, 기업별 위치는 다릅니다.

어떤 기업은 GPU를 설계합니다.
어떤 기업은 HBM을 만듭니다.
어떤 기업은 파운드리에서 생산을 담당합니다.
또 어떤 기업은 반도체 장비나 설계 소프트웨어를 제공합니다.

따라서 AI 반도체를 이해할 때는 단순히 “AI 관련주”처럼 넓게 묶기보다, 어느 단계에서 어떤 역할을 하는지 보는 것이 중요합니다.

또한 AI 인프라 투자가 빠르게 늘어난 만큼, 향후에는 투자 대비 수익성에 대한 검증도 더 강해질 수 있습니다.
AI 서비스가 실제로 돈을 벌 수 있는지, 데이터센터 비용을 감당할 수 있는지, 전력 공급은 충분한지 같은 질문이 중요해질 것입니다.

정리: AI 반도체는 AI 시대의 기반 인프라다

AI 반도체가 주목받는 이유는 명확합니다.

AI 모델은 더 커지고 있고, 사용자는 더 많아지고 있으며, 기업들은 AI를 실제 서비스와 업무에 적용하려고 합니다.
이 흐름을 뒷받침하려면 막대한 연산 성능과 빠른 메모리, 안정적인 데이터센터 인프라가 필요합니다.

그래서 GPU, HBM, NPU, AI 가속기 같은 반도체가 중요해졌습니다.

AI 반도체는 단순히 반도체 업계의 유행어가 아닙니다.
생성형 AI가 실제 서비스로 확산되는 과정에서 반드시 필요한 기반 기술입니다.

다만 모든 기업이 같은 수혜를 받는 것은 아니므로, AI 반도체를 볼 때는 다음 세 가지를 함께 보는 것이 좋습니다.

1. 어떤 연산을 처리하는 반도체인가 2. 데이터센터, 기기, 자동차 중 어디에 쓰이는가 3. GPU, 메모리, 파운드리, 장비 중 어떤 위치에 있는가

이 기준으로 보면 AI 반도체 뉴스가 훨씬 쉽게 읽힙니다.

온디바이스 AI 뜻과 장단점, 클라우드 AI와 무엇이 다를까?

notebase — Fri, 22 May 2026 13:25:34 +0900

온디바이스 AI의 뜻과 장단점을 쉽게 정리했습니다. 클라우드 AI와의 차이, 개인정보 보호, 속도, 오프라인 사용 가능 여부, NPU와 AI PC 흐름까지 함께 설명합니다.

온디바이스 AI는 스마트폰, 노트북, 태블릿 같은 기기 안에서 직접 AI 연산을 처리하는 기술입니다. 인터넷 서버로 데이터를 보내지 않고 기기 자체에서 AI 기능을 실행한다는 점이 핵심입니다.

최근 스마트폰과 AI PC에서 온디바이스 AI가 자주 언급되는 이유도 여기에 있습니다.

AI 기능을 더 빠르게 쓰고, 개인정보를 덜 외부로 보내며, 일부 기능은 인터넷 없이도 사용할 수 있기 때문입니다.

다만 온디바이스 AI가 클라우드 AI보다 항상 더 좋은 것은 아닙니다. 기기 성능, 배터리, 모델 크기, 기능 범위에 따라 장단점이 뚜렷하게 갈립니다.

온디바이스 AI 뜻

온디바이스 AI는 말 그대로 기기 위에서 실행되는 AI를 뜻합니다.

기존 AI 서비스는 보통 사용자의 입력을 서버로 보낸 뒤, 서버에서 AI 모델이 답변을 만들고 다시 사용자에게 결과를 보내는 방식으로 작동합니다.

반면 온디바이스 AI는 가능한 작업을 기기 내부에서 처리합니다.

예를 들어 스마트폰에서 다음과 같은 작업을 한다고 가정해 보겠습니다.

사진 속 인물이나 사물 인식
음성 명령 처리
실시간 번역
키보드 문장 추천
사진 보정
문서 요약
개인 일정 기반 추천

이 중 일부 작업은 서버 도움 없이 스마트폰 내부 칩셋과 AI 모델만으로 처리될 수 있습니다. 이런 방식이 온디바이스 AI입니다.

실제 예시로는 삼성 Galaxy AI의 Live Translate처럼 통화나 메시지 상황에서 번역을 도와주는 기능, Apple Intelligence처럼 기기 안의 개인 맥락을 활용해 알림이나 문장 작업을 처리하는 기능을 들 수 있습니다.

다만 모든 AI 작업을 무조건 기기 안에서만 처리하는 것은 아닙니다. 작업 난이도와 기기 성능에 따라 온디바이스와 클라우드를 함께 쓰는 구조도 많습니다.

클라우드 AI와 온디바이스 AI의 차이

온디바이스 AI를 이해하려면 클라우드 AI와 비교하면 쉽습니다.

구분	온디바이스 AI	클라우드 AI
처리 위치	스마트폰, PC 등 사용자 기기 내부	외부 서버, 데이터센터
인터넷 연결	일부 기능은 오프라인 가능	대부분 인터넷 필요
속도	짧은 작업은 빠를 수 있음	네트워크 상태에 영향
개인정보	외부 전송을 줄일 수 있음	서버 전송 과정이 필요할 수 있음
성능 한계	기기 성능에 제한	대형 모델 사용 가능
대표 예시	사진 보정, 음성 인식, 간단한 요약	고성능 챗봇, 대규모 문서 분석, 복잡한 생성 작업

쉽게 말하면 온디바이스 AI는 내 기기 안에서 빠르게 반응하는 개인 비서에 가깝고, 클라우드 AI는 더 큰 서버 자원을 활용하는 고성능 AI 서비스에 가깝습니다.

물론 실제 서비스는 둘 중 하나만 쓰지 않는 경우가 많습니다. 간단한 작업은 기기에서 처리하고, 복잡한 작업은 클라우드로 보내는 하이브리드 방식이 늘고 있습니다.

온디바이스 AI가 주목받는 이유

온디바이스 AI가 주목받는 가장 큰 이유는 AI 기능이 스마트폰과 PC의 기본 기능처럼 들어오기 시작했기 때문입니다.

과거에는 AI를 쓰려면 별도 앱이나 웹사이트에 접속하는 경우가 많았습니다. 하지만 이제는 운영체제, 카메라, 키보드, 메모 앱, 검색 기능 안에 AI가 들어가고 있습니다.

최근 모바일 칩셋과 노트북 프로세서에는 NPU라는 AI 연산 전용 장치가 들어가는 경우도 많습니다.

NPU는 Neural Processing Unit의 약자로, AI 계산을 효율적으로 처리하기 위한 칩입니다. 쉽게 말해 CPU가 모든 일을 혼자 처리하지 않도록, AI 연산만 따로 맡아주는 보조 엔진에 가깝습니다.

이 흐름은 스마트폰뿐 아니라 노트북 시장에서도 중요해지고 있습니다. Microsoft의 Copilot+ PC는 AI 작업을 위한 NPU를 핵심 요소로 설명하며, 40 TOPS 이상의 NPU 성능을 기준으로 제시합니다.

즉, 온디바이스 AI는 단순한 소프트웨어 기능이 아니라 스마트폰, 노트북, 반도체 시장과도 연결된 흐름입니다.

온디바이스 AI 장점

1. 개인정보 보호에 유리하다

온디바이스 AI의 가장 큰 장점은 개인정보 보호입니다.

AI 기능을 사용할 때 입력한 문장, 음성, 사진, 위치 정보, 일정 정보가 모두 서버로 전송된다면 사용자는 불안할 수밖에 없습니다.

온디바이스 AI는 필요한 데이터를 기기 내부에서 처리할 수 있기 때문에 외부 서버로 보내는 정보를 줄일 수 있습니다.

예를 들어 다음과 같은 정보는 민감할 수 있습니다.

개인 사진
통화 내용
음성 명령
메모 내용
일정 정보
업무 문서
위치 정보

이런 데이터를 기기 안에서 처리할 수 있다면 보안과 프라이버시 측면에서 장점이 있습니다.

다만 “온디바이스 AI = 모든 데이터가 절대 외부로 나가지 않는다”는 뜻은 아닙니다. 기능에 따라 클라우드 처리가 함께 쓰일 수 있습니다. 그래서 실제 서비스별 개인정보 처리 방식을 확인하는 것이 중요합니다.

2. 반응 속도가 빠를 수 있다

온디바이스 AI는 서버에 요청을 보내고 다시 결과를 받을 필요가 줄어듭니다.

그래서 간단한 작업은 더 빠르게 처리될 수 있습니다.

예를 들어 카메라 앱에서 실시간으로 배경을 분리하거나, 음성 명령을 즉시 인식하거나, 키보드가 다음 단어를 추천하는 기능은 빠른 반응이 중요합니다.

이런 작업은 서버 왕복 시간이 줄어들수록 사용자 경험이 좋아집니다.

특히 네트워크가 불안정한 환경에서는 차이가 더 커질 수 있습니다.

3. 인터넷이 없어도 일부 기능을 쓸 수 있다

클라우드 AI는 대부분 인터넷 연결이 필요합니다.

반면 온디바이스 AI는 기기 안에 AI 모델이 들어가 있기 때문에 일부 기능은 오프라인에서도 작동할 수 있습니다.

예를 들어 다음과 같은 상황에서 유용할 수 있습니다.

비행기 안
지하철이나 터널
해외여행 중 데이터 연결이 불안정한 상황
보안상 외부망 연결이 제한된 업무 환경

물론 모든 기능이 오프라인으로 작동하는 것은 아닙니다. 고성능 생성형 AI 기능이나 최신 정보 검색 기능은 여전히 인터넷 연결이 필요할 수 있습니다.

4. 개인화 기능에 유리하다

온디바이스 AI는 사용자의 기기 안에 있는 정보를 바탕으로 개인화된 기능을 제공하기 쉽습니다.

예를 들어 스마트폰 안에는 사용자의 일정, 연락처, 사진, 앱 사용 패턴, 알림 기록 등이 있습니다.

이 정보를 외부 서버로 많이 보내지 않고 기기 안에서 분석할 수 있다면 더 안전하면서도 개인화된 기능을 만들 수 있습니다.

예를 들면 다음과 같은 기능입니다.

자주 연락하는 사람 기반 추천
일정과 위치를 고려한 알림
사진 앨범 자동 분류
자주 쓰는 문장 스타일 반영
사용자 습관 기반 앱 추천

개인화 기능은 사용자가 자주 쓰는 기기와 결합될수록 가치가 커집니다. 단순히 똑똑한 AI가 아니라, 내 사용 패턴과 상황을 반영하는 AI에 가까워지기 때문입니다.

5. 서비스 제공 비용을 줄일 수 있다

AI 서비스를 클라우드에서만 운영하면 서버 비용이 많이 듭니다.

사용자가 많아질수록 데이터센터, GPU, 네트워크 비용이 커집니다.

온디바이스 AI는 일부 연산을 사용자 기기에서 처리하기 때문에 서비스 제공자 입장에서는 서버 부담을 줄일 수 있습니다.

사용자 입장에서도 장기적으로는 더 많은 AI 기능이 기본 기능으로 제공될 가능성이 있습니다.

다만 이 비용 절감이 항상 사용자 가격 인하로 이어진다고 단정할 수는 없습니다. 기기 가격, 칩셋 비용, 소프트웨어 구독 모델 등 여러 요소가 함께 작용하기 때문입니다.

온디바이스 AI 단점

1. 고성능 AI 작업에는 한계가 있다

온디바이스 AI는 기기 안에서 작동하기 때문에 성능 제한이 있습니다.

스마트폰이나 노트북은 데이터센터 서버보다 전력, 발열, 메모리, 연산 능력에서 한계가 있습니다.

그래서 매우 큰 AI 모델을 돌리거나 복잡한 작업을 처리하는 데는 클라우드 AI가 더 유리할 수 있습니다.

예를 들어 다음 작업은 클라우드 AI가 더 적합한 경우가 많습니다.

긴 문서 여러 개를 동시에 분석
고해상도 이미지나 영상 생성
복잡한 코딩 작업
대규모 데이터 분석
최신 웹 정보 기반 답변
긴 대화 맥락 유지

온디바이스 AI는 빠르고 가벼운 작업에는 좋지만, 모든 AI 작업을 대체하기는 어렵습니다.

2. 기기 성능에 따라 사용 경험이 달라진다

온디바이스 AI는 사용자의 기기 성능에 영향을 많이 받습니다.

최신 스마트폰이나 AI PC에서는 잘 작동하는 기능이 구형 기기에서는 느리거나 아예 지원되지 않을 수 있습니다.

특히 생성형 AI 기능은 메모리와 AI 연산 성능을 많이 요구합니다.

그래서 같은 AI 기능이라도 다음 요소에 따라 차이가 날 수 있습니다.

스마트폰 칩셋
NPU 성능
메모리 용량
운영체제 버전
제조사의 AI 지원 정책
배터리 상태

이 때문에 온디바이스 AI 기능을 기대하고 기기를 구매한다면, 단순히 “AI 지원”이라는 문구만 볼 것이 아니라 어떤 기능이 실제로 기기 안에서 작동하는지 확인하는 것이 좋습니다.

3. 배터리와 발열 문제가 생길 수 있다

AI 연산은 일반적인 앱 실행보다 더 많은 계산을 요구할 수 있습니다.

기기 안에서 AI를 계속 실행하면 배터리 소모가 늘어나거나 발열이 발생할 수 있습니다.

특히 다음 기능은 부담이 클 수 있습니다.

실시간 음성 인식
실시간 번역
영상 분석
이미지 생성
긴 문서 요약
로컬 LLM 실행

물론 최신 칩셋은 AI 연산을 효율적으로 처리하도록 설계되고 있습니다. 하지만 기기 내부에서 연산하는 이상 배터리와 발열 문제를 완전히 피하기는 어렵습니다.

4. 모델 업데이트가 제한될 수 있다

클라우드 AI는 서버의 모델만 업데이트하면 많은 사용자에게 빠르게 새 기능을 제공할 수 있습니다.

반면 온디바이스 AI는 기기 안에 모델이 들어가거나 운영체제 업데이트를 통해 기능이 제공되는 경우가 많습니다.

그래서 업데이트 속도가 느리거나, 제조사 지원이 끊긴 기기에서는 최신 AI 기능을 쓰기 어려울 수 있습니다.

또한 기기 저장공간 문제도 있습니다.

AI 모델이 기기 내부에 저장되면 그만큼 저장공간을 차지할 수 있습니다.

5. 기능이 제한적으로 제공될 수 있다

온디바이스 AI라는 표현이 붙어 있어도 모든 기능이 기기 내부에서 처리되는 것은 아닙니다.

실제로는 다음처럼 나뉠 수 있습니다.

완전 온디바이스 처리
일부 온디바이스 처리
클라우드 보조 처리
대부분 클라우드 처리

사용자 입장에서는 이 구분이 명확하게 보이지 않을 때가 있습니다.

예를 들어 문장 요약은 기기 안에서 처리되지만, 복잡한 이미지 생성은 클라우드로 넘어갈 수 있습니다.

그래서 “이 기능이 온디바이스 AI인가?”를 볼 때는 단순한 마케팅 문구보다 실제 처리 방식과 개인정보 안내를 확인하는 것이 중요합니다.

온디바이스 AI가 유용한 경우

온디바이스 AI는 다음 상황에서 특히 유용합니다.

개인정보가 중요한 작업
빠른 반응이 필요한 기능
인터넷 연결이 불안정한 환경
반복적으로 자주 쓰는 간단한 AI 기능
스마트폰 기본 기능과 결합된 AI 기능
사진, 음성, 키보드, 알림처럼 실시간 처리가 필요한 기능

예를 들어 사진 앱에서 인물을 자동 분류하거나, 키보드가 문장을 추천하거나, 음성 명령을 빠르게 처리하는 기능은 온디바이스 AI와 잘 맞습니다.

반대로 복잡한 보고서 작성, 긴 문서 분석, 최신 정보 검색, 고품질 이미지 생성처럼 큰 연산이 필요한 작업은 클라우드 AI가 더 적합할 수 있습니다.

온디바이스 AI와 클라우드 AI, 어느 쪽이 더 좋을까?

둘 중 하나가 무조건 더 좋다고 보기는 어렵습니다.

온디바이스 AI는 빠르고, 개인 정보 보호에 유리하며, 일부 기능을 오프라인으로 사용할 수 있다는 장점이 있습니다.

클라우드 AI는 더 큰 모델을 사용할 수 있고, 복잡한 작업을 처리하기 좋으며, 최신 기능을 빠르게 적용하기 쉽습니다.

따라서 앞으로는 둘 중 하나만 쓰는 방식보다 하이브리드 AI가 더 일반적일 가능성이 큽니다.

간단하고 민감한 작업은 기기 안에서 처리하고, 복잡하고 큰 연산이 필요한 작업은 클라우드에서 처리하는 방식입니다.

Apple Intelligence도 이런 흐름을 보여주는 사례입니다. 기본적으로 온디바이스 처리를 강조하면서도, 더 복잡한 요청에는 Private Cloud Compute를 함께 활용하는 구조를 제시하고 있습니다.

온디바이스 AI를 볼 때 확인할 점

AI 스마트폰이나 AI PC를 구매할 때는 다음을 확인하는 것이 좋습니다.

1. 어떤 AI 기능이 실제로 온디바이스로 작동하는가? 2. 인터넷 없이 사용할 수 있는 기능은 무엇인가? 3. 구형 기기에서도 지원되는가? 4. 개인정보가 외부 서버로 전송되는 경우는 언제인가? 5. 배터리 소모나 발열은 어느 정도인가? 6. 운영체제 업데이트를 얼마나 오래 받을 수 있는가? 7. AI 기능이 무료인지, 구독이 필요한지 확인했는가? 8. AI PC라면 NPU 성능과 메모리 조건을 함께 확인했는가?

특히 “AI 기능 지원”이라는 문구만으로는 충분하지 않습니다.

실제로 어떤 기능이 지원되는지, 어떤 조건에서 작동하는지, 어떤 데이터가 처리되는지까지 확인해야 합니다.

예를 들어 Copilot+ PC처럼 AI PC를 표방하는 제품은 단순히 AI 기능이 있다는 점보다 NPU 성능, 메모리, 저장공간 같은 조건이 함께 중요합니다.

정리

온디바이스 AI는 스마트폰, 노트북, 태블릿 같은 기기 안에서 직접 AI를 실행하는 기술입니다.

가장 큰 장점은 개인정보 보호, 빠른 반응 속도, 오프라인 사용 가능성, 개인화입니다.

반면 기기 성능에 영향을 받고, 고성능 AI 작업에는 한계가 있으며, 배터리와 발열 문제가 생길 수 있습니다.

앞으로 AI 기능은 온디바이스와 클라우드 중 하나로만 나뉘기보다, 두 방식을 함께 쓰는 방향으로 발전할 가능성이 높습니다.

사용자 입장에서는 “온디바이스 AI가 들어갔다”는 표현만 보기보다, 실제로 어떤 기능이 기기 안에서 처리되는지 확인하는 것이 중요합니다.

파이썬으로 반복 작업 자동화하는 예시 4가지

notebase — Fri, 22 May 2026 13:17:33 +0900

파이썬으로 파일 이름 변경, 폴더 정리, 텍스트 검색, 엑셀 처리 같은 반복 작업을 자동화하는 초보자용 예제를 정리합니다.

파이썬 반복 작업 자동화는 사람이 매번 손으로 하던 파일 정리, 텍스트 검색, 엑셀 처리 같은 일을 코드로 처리하는 방법입니다. 복잡한 프로그램을 만들지 않아도, 작은 스크립트 하나만으로 반복 업무를 줄일 수 있습니다.

파이썬을 처음 배울 때는 변수, 조건문, 반복문 같은 문법이 따로 떨어져 보일 수 있습니다. 하지만 자동화 예제를 보면 이런 문법을 왜 배우는지 조금 더 쉽게 이해할 수 있습니다.

반복 작업 자동화는 파이썬을 실생활이나 업무에 적용하기 좋은 첫 단계입니다.

파이썬 자동화란?

파이썬 자동화는 일정한 규칙이 있는 반복 작업을 코드로 처리하는 것을 말합니다.

예를 들어 이런 작업이 있습니다.

파일 이름을 일정한 규칙으로 한 번에 바꾸기
폴더 안의 파일을 확장자별로 분류하기
여러 텍스트 파일에서 특정 단어 찾기
엑셀 파일의 데이터를 읽고 조건에 맞게 정리하기
반복적으로 생성해야 하는 문서나 로그 만들기

핵심은 단순합니다.

사람이 반복해서 하는 일을 파이썬이 대신 반복하게 만드는 것입니다.

파이썬의 for, if, pathlib, shutil, openpyxl 같은 기능을 조합하면 초보자도 간단한 자동화 코드를 만들 수 있습니다.

반복 작업 자동화가 필요한 상황

어떤 작업을 자동화하면 좋을지 모르겠다면, 아래 기준에 해당하는지 먼저 확인해보세요.

1. 같은 작업을 여러 번 반복한다

파일 100개의 이름을 하나씩 바꾸거나, 매번 같은 형식의 파일을 정리하는 작업이 여기에 해당합니다.

2. 작업 규칙이 명확하다

예를 들어 .jpg 파일은 이미지 폴더로, .pdf 파일은 문서 폴더로 옮기는 식입니다.

규칙이 명확할수록 코드로 자동화하기 쉽습니다.

3. 단순하지만 실수하기 쉽다

반복 작업은 지루하고, 지루한 작업일수록 실수가 생기기 쉽습니다.

이런 작업은 사람이 계속 처리하기보다 코드로 일정하게 처리하는 편이 더 안전할 수 있습니다.

예시 1: 여러 파일 이름 한 번에 바꾸기

가장 흔한 자동화 예시는 파일 이름 변경입니다.

예를 들어 폴더 안에 있는 이미지 파일 이름을 아래처럼 바꾸고 싶다고 가정해보겠습니다.

IMG_001.jpg -> photo_1.jpg
IMG_002.jpg -> photo_2.jpg
IMG_003.jpg -> photo_3.jpg

파이썬의 pathlib 모듈을 사용하면 몇 줄로 처리할 수 있습니다.

from pathlib import Path

# 작업할 폴더 지정
folder = Path("images")

# glob() 결과 순서는 고정되지 않을 수 있으므로 이름순으로 정렬합니다.
for index, file in enumerate(sorted(folder.glob("*.jpg")), start=1):
    # 새 파일 이름 규칙: photo_1.jpg, photo_2.jpg, ...
    new_name = folder / f"photo_{index}.jpg"

    # 같은 이름의 파일이 이미 있으면 덮어쓰기나 오류를 피하기 위해 건너뜁니다.
    if new_name.exists():
        print(f"건너뜀: {new_name.name} 파일이 이미 있습니다.")
        continue

    file.rename(new_name)

이 코드는 images 폴더 안에 있는 .jpg 파일을 찾아서 이름순으로 정렬한 뒤, 순서대로 새 이름을 붙입니다.

여기서 중요한 부분은 sorted(), for 반복문, enumerate()입니다.

for index, file in enumerate(sorted(folder.glob("*.jpg")), start=1):

folder.glob("*.jpg")는 폴더 안의 jpg 파일을 찾고, sorted()는 그 결과를 이름 기준으로 정렬합니다. enumerate()는 파일마다 번호를 붙여줍니다.

파일이 3개든 300개든 같은 방식으로 처리할 수 있습니다.

주의: 파일 이름 변경 코드는 되돌리기 번거로울 수 있습니다. 처음에는 반드시 복사본 폴더에서 테스트해보세요.

예시 2: 폴더 안의 파일을 확장자별로 정리하기

다운로드 폴더에는 여러 종류의 파일이 섞이기 쉽습니다.

report.pdf
photo.jpg
memo.txt
data.xlsx

이런 파일을 확장자별 폴더로 자동 정리할 수 있습니다.

from pathlib import Path
import shutil

folder = Path("downloads")

for file in folder.iterdir():
    if file.is_file():
        # 확장자 추출: .pdf -> pdf
        extension = file.suffix.lower().replace(".", "")

        if extension:
            # 확장자 이름의 폴더가 없으면 생성
            target_folder = folder / extension
            target_folder.mkdir(exist_ok=True)

            # 파일 이동
            shutil.move(str(file), str(target_folder / file.name))

이 코드는 파일 확장자를 기준으로 폴더를 만들고, 해당 파일을 그 폴더로 이동합니다.

예를 들어 report.pdf는 pdf 폴더로, photo.jpg는 jpg 폴더로 이동합니다.

실행 후 구조는 대략 이렇게 됩니다.

downloads/
├── pdf/
│   └── report.pdf
├── jpg/
│   └── photo.jpg
├── txt/
│   └── memo.txt
└── xlsx/
    └── data.xlsx

이런 자동화는 다운로드 폴더, 이미지 폴더, 문서 폴더를 정리할 때 유용합니다.

다만 실제 파일을 이동하는 코드이기 때문에 처음에는 테스트용 폴더에서 실행하는 것이 안전합니다.

또한 대상 폴더에 이미 같은 이름의 파일이 있다면 환경에 따라 오류가 발생하거나 의도와 다르게 처리될 수 있습니다. 중요한 파일이 있는 폴더에서는 실행 전에 백업을 만들어두는 편이 좋습니다.

예시 3: 텍스트 파일에서 특정 단어 찾기

여러 텍스트 파일에서 특정 단어가 들어간 파일을 찾는 작업도 자동화할 수 있습니다.

예를 들어 logs 폴더 안의 .txt 파일에서 error라는 단어를 찾는 코드입니다.

from pathlib import Path

folder = Path("logs")
keyword = "error"

for file in folder.glob("*.txt"):
    content = file.read_text(encoding="utf-8")

    if keyword in content:
        print(f"{file.name} 파일에 '{keyword}' 단어가 있습니다.")

이 코드는 logs 폴더 안의 텍스트 파일을 하나씩 읽고, 특정 단어가 포함되어 있는지 확인합니다.

로그 파일, 메모 파일, 문서 초안 등을 검색할 때 활용할 수 있습니다.

예를 들어 여러 로그 파일에서 에러 메시지를 찾아야 한다면 사람이 하나씩 열어보는 것보다 빠르게 확인할 수 있습니다.

예시 4: 엑셀 파일 읽어서 데이터 필터링하기

업무 자동화에서 자주 나오는 것이 엑셀 처리입니다.

파이썬에서는 openpyxl 라이브러리를 사용하면 엑셀 파일을 읽고 수정할 수 있습니다.

openpyxl은 파이썬 표준 라이브러리가 아니라 외부 패키지입니다. 먼저 설치가 필요합니다.

pip install openpyxl

예를 들어 sales.xlsx 파일에 아래와 같은 데이터가 있다고 가정해보겠습니다.

상품명	판매금액
키보드	50000
마우스	30000
모니터	200000

이 데이터에서 판매금액이 100,000원 이상인 항목만 출력해보겠습니다.

from openpyxl import load_workbook

# 엑셀 파일 불러오기
workbook = load_workbook("sales.xlsx")
sheet = workbook.active

# 두 번째 줄부터 데이터 읽기
# 첫 번째 줄은 제목 행이라고 가정
for row in sheet.iter_rows(min_row=2, values_only=True):
    name = row[0]
    amount = row[1]

    if amount >= 100000:
        print(f"{name}: {amount}원")

실행 결과는 다음과 비슷하게 나옵니다.

모니터: 200000원

이 코드는 엑셀 파일의 두 번째 줄부터 데이터를 읽고, 판매금액이 100,000원 이상인 항목만 출력합니다.

엑셀 자동화는 조금만 익숙해져도 반복 업무에 바로 활용하기 좋습니다.

팁: 코드를 실행하기 전에 대상 엑셀 파일을 닫아두는 것이 좋습니다. 파일이 열려 있으면 환경에 따라 PermissionError가 발생할 수 있습니다.

자동화 코드를 작성할 때 주의할 점

파이썬 자동화는 편리하지만, 파일을 수정하거나 이동하는 작업에서는 주의가 필요합니다.

코드는 사람이 직접 클릭하는 것보다 훨씬 빠르게 여러 파일을 처리합니다. 그래서 작은 실수도 여러 파일에 한꺼번에 반영될 수 있습니다.

다음 내용은 자동화 코드를 실행하기 전에 꼭 확인하는 것이 좋습니다.

1. 처음에는 테스트 폴더에서 실행하기

파일 이름 변경, 이동, 삭제 코드는 실제 자료에 바로 실행하지 않는 것이 좋습니다.

먼저 복사본이나 테스트 폴더를 만들어서 코드가 원하는 대로 동작하는지 확인해야 합니다.

권장하지 않음: 원본 폴더에서 바로 실행
권장: 복사한 테스트 폴더에서 먼저 실행

이 습관만 있어도 실수로 중요한 파일을 잃을 가능성을 줄일 수 있습니다.

2. 삭제보다 이동을 먼저 사용하기

초보자라면 delete, unlink 같은 삭제 기능보다 이동 기능을 먼저 사용하는 편이 안전합니다.

파일을 지우는 대신 backup 폴더나 trash 폴더로 옮기면 문제가 생겼을 때 되돌리기 쉽습니다.

import shutil
from pathlib import Path

file = Path("sample.txt")
backup_folder = Path("backup")

backup_folder.mkdir(exist_ok=True)

shutil.move(str(file), str(backup_folder / file.name))

자동화 코드는 빠르게 실행되기 때문에, 한 번 잘못 실행하면 여러 파일이 동시에 변경될 수 있습니다.

삭제 작업은 충분히 테스트한 뒤 사용하는 것이 좋습니다.

3. 경로를 정확히 확인하기

자동화 코드에서 자주 발생하는 실수 중 하나가 경로 문제입니다.

from pathlib import Path

# 이 경로는 현재 작업 디렉터리(cwd)를 기준으로 해석됩니다.
folder = Path("downloads")
print("현재 작업 디렉터리 기준:", folder.resolve())

# 현재 파이썬 파일이 있는 위치를 기준으로 삼고 싶다면 이렇게 씁니다.
script_folder = Path(__file__).parent
download_folder = script_folder / "downloads"
print("스크립트 파일 기준:", download_folder.resolve())

Path("downloads")는 현재 작업 디렉터리를 기준으로 찾습니다. 반대로 Path(__file__).parent / "downloads"는 현재 파이썬 파일이 있는 폴더를 기준으로 경로를 만듭니다.

파일 자동화 작업 전에는 어떤 기준 경로를 쓰고 있는지 먼저 출력해보는 습관이 좋습니다.

처음에는 작은 작업부터 자동화하기

파이썬 자동화를 처음 배울 때부터 큰 프로그램을 만들 필요는 없습니다.

오히려 작은 작업부터 시작하는 것이 좋습니다.

예를 들어 다음 정도면 충분합니다.

파일 이름 앞에 날짜 붙이기
특정 확장자 파일만 목록으로 출력하기
텍스트 파일에서 특정 단어 찾기
엑셀에서 특정 조건의 행만 출력하기
반복적으로 작성하는 문장 자동 생성하기

중요한 것은 “이 작업을 사람이 반복하고 있는가?”를 생각해보는 것입니다.

반복되는 규칙이 있다면 파이썬으로 자동화할 가능성이 있습니다.

마무리

파이썬으로 반복 작업을 자동화하면 파일 정리, 텍스트 검색, 엑셀 처리 같은 단순 작업을 줄일 수 있습니다.

파일을 하나씩 정리하거나, 문서를 일일이 열어 확인하거나, 엑셀 데이터를 반복해서 검사하는 작업은 실수하기 쉽습니다. 이런 작업을 코드로 처리하면 더 빠르고 일정한 결과를 얻을 수 있습니다.

처음에는 파일 이름 바꾸기처럼 작은 예제부터 시작하는 것이 좋습니다.

그다음 폴더 정리, 텍스트 검색, 엑셀 처리처럼 조금씩 범위를 넓혀가면 파이썬을 실제 작업에 활용하는 감각을 익힐 수 있습니다.

Gemini, ChatGPT, Claude 차이점 비교: 어떤 AI를 언제 쓰면 좋을까

notebase — Fri, 22 May 2026 11:41:32 +0900

Gemini, ChatGPT, Claude의 차이를 2026년 5월 기준 공식 정보와 실사용 관점으로 비교합니다. 글쓰기, 검색, 문서 정리, 코딩, Google 연동, 멀티모달 작업 기준으로 어떤 AI가 맞는지 정리했습니다.

하나만 먼저 추천하면 범용성은 ChatGPT, Google 작업 흐름은 Gemini, 긴 문서 정리와 문장 다듬기는 Claude입니다.

다만 이 세 AI는 단순 순위로 고르기보다, 내가 자주 하는 작업에 어디가 더 잘 맞는지로 비교하는 편이 훨씬 실용적입니다.

이 글은 2026년 5월 22일 기준 OpenAI, Google, Anthropic의 공식 가격 페이지와 도움말을 바탕으로 정리했습니다. 다만 기능, 한도, 국가별 제공 범위는 자주 바뀔 수 있습니다.

세 AI를 단순 순위로 비교하면 안 되는 이유

“셋 중에 뭐가 제일 좋아요?”라고 묻는 경우가 많지만, 실제로는 이 질문만으로 답하기 어렵습니다.

이유는 간단합니다. AI는 용도에 따라 체감 장점이 크게 달라지기 때문입니다.

여러 작업을 한곳에서 처리하고 싶다면 ChatGPT가 편할 수 있습니다.
Gmail, Docs, Drive 중심으로 일한다면 Gemini가 더 자연스럽게 붙습니다.
긴 PDF, 보고서, 회의록처럼 긴 텍스트를 읽고 다듬는 작업은 Claude가 더 잘 맞을 수 있습니다.

게다가 AI 서비스는 업데이트 속도가 매우 빠릅니다. 플랜 이름, 사용량 제한, 제공 기능, 국가별 지원 범위가 수시로 바뀝니다. 그래서 “무조건 A가 B보다 낫다”처럼 단정하면 글이 금방 낡습니다.

이 글에서는 순위보다 아래 기준에 집중하겠습니다.

범용적으로 쓰기 좋은 AI는 무엇인가
Google 서비스와 함께 쓰기 좋은 AI는 무엇인가
긴 문서 정리에 강한 AI는 무엇인가
자료 조사와 검색 흐름에 잘 맞는 AI는 무엇인가
무료로 먼저 써보기 좋은 AI는 무엇인가

한눈에 비교하면

AI	잘 맞는 상황	강점	먼저 확인할 점
ChatGPT	범용 작업, 초안 작성, 파일 분석, 코딩 보조	검색, 파일 업로드, 음성, 이미지 도구를 한 서비스 안에서 폭넓게 쓰기 좋음	플랜별 기능과 사용 한도가 자주 바뀜
Gemini	Gmail, Docs, Drive, Android, 멀티모달 작업	Google 서비스 연동, 이미지 생성·편집, 실시간 조사 계열 기능	국가, 개인 계정/Workspace 계정, 플랜별 차이가 큼
Claude	긴 PDF, 보고서, 회의록, 장문 초안 정리	긴 맥락 유지, 문장 정리, 장문 읽기와 구조화에 강점	사용량은 대화 길이, 첨부파일 크기, 모델에 따라 달라짐

이 표만 먼저 기억해도 선택이 훨씬 쉬워집니다.

ChatGPT는 어떤 용도에 적합할까

ChatGPT는 가장 무난한 출발점에 가깝습니다.

OpenAI 공식 가격 페이지 기준으로 무료 플랜에서도 웹 검색, 파일 업로드, 음성, 이미지 도구를 제한적으로 써볼 수 있습니다. 유료 플랜에서는 사용 한도가 늘어나고 deep research 같은 고급 기능 접근이 넓어집니다.

즉, ChatGPT의 핵심 장점은 한 서비스 안에서 할 수 있는 일이 넓다는 점입니다.

ChatGPT가 잘 맞는 사람

여러 작업을 한 AI 안에서 처리하고 싶은 사람
글쓰기, 요약, 번역, 아이디어 정리를 자주 하는 사람
파일을 올려 분석하거나 표 형태로 정리하고 싶은 사람
코딩 질문, 오류 분석, 구조 정리를 함께 하고 싶은 사람
처음 AI를 시작하면서 가장 무난한 선택지를 찾는 사람

특히 ChatGPT는 “초안 만들기 -> 다시 써달라고 하기 -> 더 쉽게 설명해달라고 하기 -> 표로 정리해달라고 하기” 같은 대화형 작업 흐름에 강합니다.

ChatGPT 사용 시 주의할 점

범용성이 높다고 해서 항상 가장 정확한 것은 아닙니다.

가격, 정책, 법률, 세금, 최신 제품 정보처럼 바뀌는 내용은 공식 페이지 재확인이 필요합니다.
유료 플랜이라고 해도 모든 기능이 무제한은 아닙니다.
플랜 구성은 공식 가격 페이지와 도움말 기준으로 세부 안내가 달라질 수 있으니 결제 전 실제 화면 확인이 안전합니다.

정리하면 ChatGPT는 하나만 먼저 써봐야 한다면 가장 추천하기 쉬운 AI입니다.

Gemini는 어떤 용도에 적합할까

Gemini는 Google 생태계를 자주 쓰는 사람에게 강점이 더 분명합니다.

Google 공식 도움말 기준으로 Gemini 앱의 유료 업그레이드는 현재 Google AI Pro와 Google AI Ultra 체계로 안내됩니다. Google One AI Premium이라는 옛 이름에 익숙한 사람도 있지만, 현재 공식 안내에서는 Pro와 Ultra 명칭을 쓰고 있습니다.

또한 Google은 Gemini를 단순 채팅 도구가 아니라, Gmail, Docs, Vids, Drive 같은 서비스와 연결되는 작업 도구로 계속 확장하고 있습니다.

Gemini가 잘 맞는 사람

Gmail, Docs, Drive, Sheets 등 Google 서비스를 많이 쓰는 사람
검색 흐름과 AI 답변을 함께 활용하고 싶은 사람
Android나 Google 계정 중심으로 작업하는 사람
이미지, 영상, 음성 등 멀티모달 작업에도 관심이 있는 사람
Google Workspace 흐름 안에서 AI를 쓰고 싶은 사람

Gemini의 핵심은 Google 안에서 이어지는 작업 흐름입니다. 메일, 문서, 파일, 일정, 검색이 이미 Google 중심이라면 별도 도구를 붙이는 느낌보다 “기존 작업 환경에 AI가 들어온다”는 체감이 큽니다.

Gemini의 멀티모달 장점

Google 공식 도움말상 Gemini는 텍스트 답변뿐 아니라 이미지 생성과 편집 기능도 적극적으로 밀고 있습니다.

Gemini에서 만든 이미지를 다시 수정할 수 있습니다.
사용자가 올린 이미지를 편집하거나 여러 이미지를 합쳐 새 이미지를 만들 수 있습니다.
Storybook 기능처럼 삽화가 있는 이야기 형태의 창작도 지원합니다.

즉 Gemini는 단순 검색형 AI라기보다, Google 연동 + 멀티모달 제작 도구 쪽으로 이해하는 편이 맞습니다.

Gemini 사용 시 주의할 점

일부 기능은 국가, 연령, 계정 유형, 플랜에 따라 제공 여부가 다릅니다.
개인 Google 계정과 회사/학교 Workspace 계정은 접근 가능한 기능이 다를 수 있습니다.
“Google 서비스 연동이 강점”이라는 말은 반대로, Google을 거의 쓰지 않으면 장점 체감이 줄 수 있다는 뜻이기도 합니다.

정리하면 Gemini는 Google 생태계에 깊게 들어가 있는 사용자에게 특히 잘 맞는 AI입니다.

Claude는 어떤 용도에 적합할까

Claude는 긴 문서를 읽고 정리하는 작업에서 강점을 느끼는 사용자가 많습니다.

Anthropic 공식 도움말 기준으로 개인용 Claude는 Free, Pro, Max 체계로 안내됩니다. Pro는 유료 기본형이고, Max는 더 높은 사용량이 필요한 사용자를 위한 상위 단계입니다.

Claude를 이해할 때 중요한 점은 “몇 번까지 쓸 수 있나”가 고정 숫자가 아니라는 점입니다. 공식 도움말도 사용량이 메시지 길이, 첨부파일 크기, 현재 대화 길이, 사용하는 모델과 기능에 따라 달라진다고 설명합니다.

Claude가 잘 맞는 사람

긴 PDF나 보고서를 자주 읽고 요약하는 사람
기획서, 제안서, 회의록 초안을 정리하는 사람
문장을 덜 기계적으로 다듬고 싶은 사람
긴 맥락을 유지하면서 대화해야 하는 사람
코드 설명이나 리팩터링 방향을 차분하게 검토하고 싶은 사람

Claude는 짧은 한두 줄 답보다, 장문을 구조화하고 흐름을 정리하는 작업에서 만족도가 높은 편입니다.

예를 들어 아래 같은 요청에 잘 맞습니다.

이 보고서의 핵심 주장만 뽑아줘
회의록에서 결정 사항과 할 일을 분리해줘
이 초안을 더 자연스럽고 덜 딱딱하게 다듬어줘
긴 문서에서 빠진 논리나 리스크를 찾아줘

Claude 사용 시 주의할 점

사용량 제한은 플랜이 같아도 대화 방식에 따라 크게 달라질 수 있습니다.
긴 대화와 큰 파일 첨부는 사용량을 더 빨리 소모할 수 있습니다.
최신 정보 검색이나 외부 서비스 연동은 사용 환경에 따라 체감 차이가 있을 수 있습니다.

정리하면 Claude는 긴 문서와 자연스러운 문장 정리에 강한 AI로 이해하면 가장 맞습니다.

용도별로 추천하면

“누가 더 뛰어난가”보다 “무슨 작업을 하느냐”로 보면 훨씬 실용적입니다.

용도	먼저 추천할 AI	이유
하나의 AI로 여러 작업 시작하기	ChatGPT	범용성이 높고 시작 장벽이 낮음
블로그 글 초안 잡기	ChatGPT	구조 잡기, 요약, 재작성 요청이 편함
긴 초안 문장 다듬기	Claude	장문 정리와 문장 흐름 보정에 유리
Gmail, Docs, Drive와 함께 쓰기	Gemini	Google 작업 흐름 안에서 연결성이 좋음
긴 PDF, 보고서, 회의록 정리	Claude	긴 문맥 유지와 구조화가 강점
이미지와 텍스트를 같이 다루기	Gemini 또는 ChatGPT	멀티모달 작업 접근성이 좋음
코딩 질문과 범용 작업 병행	ChatGPT	코딩 보조와 일반 작업을 함께 쓰기 편함

실제로는 하나만 고르기보다 역할을 나눠 쓰는 사람이 많습니다.

일상 질문과 범용 작업은 ChatGPT
Google 연동과 멀티모달 작업은 Gemini
긴 문서 읽기와 문장 다듬기는 Claude

이 조합이 현실적으로 가장 설명이 잘 됩니다.

무료 버전과 유료 버전은 어떻게 고르면 될까

처음부터 결제할 필요는 없습니다.

세 서비스 모두 무료로 기본 작업을 시험해볼 수 있으니, 먼저 아래 질문으로 판단하는 편이 좋습니다.

매일 업무에 AI를 쓰는가
긴 문서나 파일을 자주 올리는가
사용량 제한에 자주 걸리는가
deep research, 고급 모델, 이미지 편집 같은 기능이 꼭 필요한가
내 작업 흐름에 Google 연동이나 장문 처리 같은 특정 강점이 중요한가

아래에 가깝다면 유료 플랜을 고려할 만합니다.

AI를 거의 매일 쓴다
긴 파일과 장문 대화를 자주 다룬다
답변 속도와 사용량 한도가 중요하다
고급 기능을 실제 업무에 넣어야 한다

반대로 가끔 질문하거나 초안만 만드는 정도라면 무료 버전부터 시작해도 충분합니다.

핵심은 “좋아 보이니까 결제”가 아니라, 내가 자주 막히는 작업을 해결해 주는가입니다.

결국 어떤 AI부터 써보면 좋을까

하나만 먼저 시작해야 한다면 ChatGPT가 가장 무난합니다.

하지만 이미 업무 대부분이 Google 안에서 돌아간다면 Gemini를 먼저 써보는 편이 더 만족스러울 수 있습니다.

긴 문서, 보고서, 회의록, 제안서 초안 정리가 많다면 Claude를 함께 비교해보는 것이 좋습니다.

짧게 정리하면 이렇게 추천할 수 있습니다.

가장 무난한 첫 선택: ChatGPT
Google 서비스 중심 업무: Gemini
긴 문서와 자연스러운 문장 정리: Claude

정리

Gemini, ChatGPT, Claude는 모두 좋은 AI입니다. 다만 잘하는 일이 조금씩 다릅니다.

ChatGPT는 범용성이 좋고, Gemini는 Google 생태계와 멀티모달 작업에서 장점이 크고, Claude는 긴 문서와 장문 정리에 잘 맞습니다.

중요한 것은 “가장 강한 AI”를 찾는 것이 아니라, 내가 자주 하는 작업에 가장 잘 맞는 AI를 고르는 것입니다.

처음에는 무료 버전으로 직접 써보고, 이후에 자주 쓰는 작업이 분명해졌을 때 유료 플랜을 검토하는 편이 가장 안전합니다.

FAQ

셋 중 하나만 먼저 시작한다면 무엇이 좋을까

특정 생태계 제약이 없다면 ChatGPT가 가장 무난합니다. 다만 Google 중심 업무라면 Gemini, 긴 문서 정리가 핵심이라면 Claude가 더 잘 맞을 수 있습니다.

Gemini는 검색에 강하고 ChatGPT는 글쓰기에 강하다고 단정해도 될까

그렇게 단정하기는 어렵습니다. 두 서비스 모두 계속 바뀌고 있고, 실제 체감은 사용하는 플랜과 작업 방식에 따라 달라집니다. 다만 Google 서비스 연동은 Gemini 쪽이, 범용 대화형 초안 작업은 ChatGPT 쪽이 상대적으로 이해하기 쉽습니다.

Claude는 왜 긴 문서에 강하다고 느끼는 사람이 많을까

장문 맥락을 유지하면서 구조를 정리하고 문장을 다듬는 용도로 많이 쓰이기 때문입니다. 특히 긴 PDF, 회의록, 기획서처럼 한 번에 읽고 정리해야 하는 자료에서 장점이 잘 드러납니다.

무료 버전만으로도 충분할까

가벼운 질문, 요약, 초안 작성 정도라면 충분할 수 있습니다. 다만 매일 업무에 쓰거나 긴 파일과 고급 기능이 필요하면 유료 플랜 쪽이 더 잘 맞을 가능성이 큽니다.

AI 에이전트란? 초보자가 이해하기 쉽게 정리

notebase — Fri, 22 May 2026 10:45:46 +0900

AI 에이전트란 무엇인지 초보자도 이해할 수 있게 정리했습니다. ChatGPT와의 차이, 작동 방식, 활용 예시, 주의할 점까지 쉽게 설명합니다.

AI 에이전트는 사용자의 목표를 이해하고, 필요한 단계를 계획한 뒤, 도구를 사용해 작업을 수행하는 AI 시스템을 말합니다. 단순히 질문에 답하는 AI보다 한 단계 더 “행동하는 AI”에 가깝습니다.

쉽게 말하면 ChatGPT가 “질문에 답하는 AI”에 가깝다면, AI 에이전트는 “목표를 받고 작업을 진행하는 AI”에 가깝습니다.

2026년 5월 기준으로 AI 에이전트는 생성형 AI 분야에서 자주 언급되는 개념입니다. 하지만 막상 설명을 들으면 어렵게 느껴질 수 있습니다.

ChatGPT랑 뭐가 다른 걸까?
기존 자동화 프로그램과 같은 걸까?
정말 사람이 시키지 않아도 알아서 일하는 걸까?

이 글에서는 AI 에이전트의 뜻, 작동 방식, ChatGPT와의 차이, 실제 활용 예시, 주의할 점을 초보자도 이해하기 쉽게 정리합니다.

AI 에이전트란?

AI 에이전트는 쉽게 말해 목표를 받고, 스스로 다음 행동을 정해, 작업을 수행하는 AI 시스템입니다.

예를 들어 사용자가 이렇게 요청했다고 가정해보겠습니다.

> “다음 주 제주도 2박 3일 여행 일정을 짜줘.”

일반적인 챗봇은 여행 일정을 텍스트로 추천해줄 수 있습니다.

반면 AI 에이전트는 더 넓은 작업을 처리하도록 설계될 수 있습니다. 예를 들면 항공권 가격을 확인하고, 숙소 후보를 비교하고, 지도 정보를 참고해 동선을 짜고, 사용자의 조건에 맞게 일정을 다시 조정하는 식입니다.

물론 실제로 어디까지 가능한지는 사용하는 서비스, 연결된 도구, 권한 설정에 따라 달라집니다.

핵심은 하나입니다.

AI 에이전트는 단순히 답변만 하는 것이 아니라, 목표를 이루기 위해 여러 단계를 진행할 수 있는 AI입니다.

ChatGPT와 AI 에이전트는 무엇이 다를까?

초보자가 가장 많이 헷갈리는 부분이 이 지점입니다.

ChatGPT 같은 AI 챗봇은 사용자의 질문에 답을 생성합니다. 예를 들어 “블로그 글 목차를 짜줘”라고 하면 목차를 만들어줍니다.

AI 에이전트는 여기서 한 단계 더 나아갑니다.

목차를 만드는 데 그치지 않고, 필요한 자료를 찾고, 초안을 작성하고, 오류를 점검하고, 수정 방향을 판단하는 식으로 작업 흐름을 이어갈 수 있습니다.

간단히 비교하면 다음과 같습니다.

구분	일반 AI 챗봇	AI 에이전트
중심 기능	질문에 답변	목표 달성을 위한 작업 수행
작동 방식	입력 → 답변	목표 → 계획 → 실행 → 점검
도구 사용	제한적이거나 없음	검색, 파일, API, 앱 등 도구 사용 가능
예시	글 요약하기	자료 조사 후 글 작성하고 검토하기
사람의 역할	질문 입력	목표 설정과 결과 검토

다만 모든 AI 서비스가 명확하게 둘로 나뉘는 것은 아닙니다.

최근에는 챗봇 안에 에이전트 기능이 들어가기도 하고, 에이전트라고 부르지만 실제로는 단순 자동화에 가까운 경우도 있습니다. 그래서 이름보다 중요한 것은 그 AI가 실제로 무엇을 할 수 있는지입니다.

AI 에이전트는 어떻게 작동할까?

AI 에이전트의 작동 방식은 보통 다음 흐름으로 이해하면 쉽습니다.

1. 목표를 이해한다

먼저 사용자의 요청을 해석합니다.

예를 들어 “블로그 글을 작성해줘”라는 요청이 들어오면, AI 에이전트는 단순히 글만 쓰는 것이 아니라 주제, 독자, 검색 의도, 필요한 자료를 함께 판단할 수 있습니다.

2. 작업을 나눈다

큰 목표를 작은 단계로 나눕니다.

예를 들어 “AI 에이전트 블로그 글 작성”이라는 목표가 있다면 다음과 같이 나눌 수 있습니다.

주제 파악
독자 분석
키워드 정리
목차 구성
본문 작성
오류 점검
문장 수정

이렇게 큰 일을 작은 단계로 쪼개면 AI가 더 체계적으로 작업할 수 있습니다.

3. 필요한 도구를 사용한다

AI 에이전트의 중요한 특징 중 하나는 도구 사용입니다.

AI 모델 자체가 모든 일을 직접 처리하는 것은 아닙니다. 대신 필요한 도구와 연결되면 실제 작업 범위가 넓어집니다.

연결 도구	AI 에이전트가 할 수 있는 일
웹 검색	최신 자료 조사, 뉴스 확인, 가격 비교
캘린더	빈 시간 확인, 일정 후보 정리
이메일	메일 초안 작성, 발송 전 검토 요청
파일 도구	문서 읽기, 요약, 정리
코드 실행 도구	데이터 계산, 간단한 분석 자동화
외부 API	서비스 간 데이터 조회와 작업 연결

예를 들어 “회의 일정을 잡아줘”라는 요청에서 캘린더 도구와 이메일 도구가 연결되어 있다면, 빈 시간을 확인하고 참석자에게 안내 메일 초안을 작성하는 식으로 이어질 수 있습니다.

다만 이메일 발송, 파일 수정, 결제처럼 되돌리기 어려운 작업은 자동 실행보다 사용자 확인 후 실행 방식이 안전합니다.

4. 결과를 확인하고 수정한다

AI 에이전트는 한 번에 끝내는 것이 아니라 결과를 확인하고 다시 수정하는 방식으로 작동할 수 있습니다.

예를 들어 글을 작성한 뒤 문장이 너무 어렵다고 판단하면 더 쉽게 고칠 수 있습니다. 자료가 부족하다고 판단하면 추가 조사를 할 수도 있습니다.

이런 점 때문에 AI 에이전트는 단순 응답형 AI보다 “작업 흐름”에 더 가깝습니다.

초보자가 이해하기 쉬운 AI 에이전트 예시

AI 에이전트는 아직 추상적으로 느껴질 수 있습니다. 그래서 일상적인 예시로 보는 것이 좋습니다.

예시 1. 여행 일정을 짜주는 AI 에이전트

사용자가 “부산 1박 2일 여행 계획을 세워줘”라고 요청합니다.

AI 에이전트는 다음 작업을 할 수 있습니다.

여행 날짜 확인
이동 수단 비교
숙소 위치 추천
관광지 동선 구성
음식점 후보 정리
예산에 맞게 일정 조정

단순히 “부산 여행지는 해운대, 광안리, 감천문화마을이 있습니다”라고 답하는 것보다 더 구체적입니다.

예시 2. 블로그 글 작성을 돕는 AI 에이전트

블로그 운영자가 “AI 에이전트란 주제로 초보자용 글을 써줘”라고 요청합니다.

AI 에이전트는 다음 단계를 수행할 수 있습니다.

검색 의도 분석
핵심 키워드 정리
제목 후보 작성
목차 설계
본문 작성
문장 검토
SEO 요소 점검

이 경우 AI 에이전트는 단순 글쓰기 도구가 아니라 콘텐츠 제작 흐름을 도와주는 시스템에 가깝습니다.

예시 3. 회의록과 업무 정리를 돕는 AI 에이전트

직장인이 “이번 주 회의 내용을 정리하고 할 일을 뽑아줘”라고 요청합니다.

AI 에이전트는 다음과 같은 작업을 할 수 있습니다.

회의록 읽기
주요 결정사항 정리
담당자별 할 일 분류
마감일 추출
일정 등록 또는 알림 생성

이런 방식으로 반복적인 사무 작업을 줄이는 데 활용될 수 있습니다.

AI 에이전트가 주목받는 이유

AI 에이전트가 주목받는 이유는 단순합니다.

기존 AI가 “답변”에 강했다면, AI 에이전트는 “업무 흐름”에 더 가까워졌기 때문입니다.

사용자는 매번 세세하게 지시하지 않아도 됩니다. 목표를 주면 AI가 필요한 단계를 나누고, 중간 작업을 처리하고, 결과물을 만들어낼 수 있습니다.

특히 다음 분야에서 관심이 큽니다.

고객 응대
일정 관리
자료 조사
보고서 작성
코드 작성
데이터 분석
마케팅 콘텐츠 제작
반복 업무 자동화

기업 입장에서는 시간을 줄이고 업무 효율을 높일 수 있다는 기대가 있습니다. 개인 사용자 입장에서는 복잡한 작업을 더 쉽게 처리할 수 있다는 장점이 있습니다.

다만 이 기대가 항상 현실과 일치하는 것은 아닙니다. AI 에이전트가 제대로 작동하려면 좋은 도구 연결, 명확한 권한 설정, 검증 절차가 필요합니다.

AI 에이전트와 자동화 프로그램은 같은 걸까?

비슷하지만 완전히 같지는 않습니다.

일반적인 자동화 프로그램은 정해진 규칙대로 움직입니다.

예를 들어 “매일 오전 9시에 보고서를 이메일로 보내기” 같은 작업은 전통적인 자동화에 가깝습니다. 조건과 동작이 미리 정해져 있기 때문입니다.

AI 에이전트는 상황을 해석하고 다음 행동을 선택할 수 있다는 점이 다릅니다.

예를 들어 보고서 내용이 부족하면 추가 자료를 찾고, 일정이 충돌하면 다른 시간을 제안하고, 사용자의 목적에 맞게 결과물을 조정할 수 있습니다.

정리하면 다음과 같습니다.

자동화 프로그램: 정해진 규칙대로 반복 실행
AI 챗봇: 질문에 답변 생성
AI 에이전트: 목표를 이해하고 계획을 세워 작업 수행

물론 실제 서비스에서는 이 경계가 섞여 있는 경우가 많습니다.

AI 에이전트의 한계와 주의할 점

AI 에이전트는 유용할 수 있지만, 모든 일을 믿고 맡겨도 되는 도구는 아닙니다.

특히 초보자는 다음 한계를 알고 있어야 합니다.

1. 잘못된 판단을 할 수 있다

AI는 그럴듯한 답을 만들 수 있지만, 항상 정확한 것은 아닙니다. 자료 해석을 잘못하거나, 오래된 정보를 기준으로 판단하거나, 맥락을 놓칠 수 있습니다.

중요한 업무에서는 사람이 반드시 결과를 확인해야 합니다.

2. 권한 설정이 중요하다

AI 에이전트가 이메일, 캘린더, 결제, 파일 시스템과 연결된다면 편리해집니다. 하지만 그만큼 권한 관리가 중요합니다.

예를 들어 AI가 마음대로 메일을 보내거나, 파일을 수정하거나, 외부 서비스에 접근할 수 있다면 문제가 생길 수 있습니다.

처음 사용할 때는 자동 실행보다 검토 후 실행 방식이 안전합니다.

3. 개인정보와 보안에 주의해야 한다

AI 에이전트에게 민감한 정보를 입력할 때는 주의가 필요합니다.

회사 내부 자료, 고객 정보, 계약서, 계정 정보, 결제 정보 등은 서비스의 보안 정책과 데이터 처리 방식을 확인한 뒤 사용하는 것이 좋습니다.

4. 모든 작업에 적합한 것은 아니다

AI 에이전트는 반복적이고 구조화된 작업에는 유용할 수 있습니다.

하지만 높은 책임이 필요한 의사결정, 법률·의료·재무 판단, 보안상 민감한 작업에서는 보조 도구로 보는 것이 안전합니다.

결과를 그대로 믿기보다 참고 자료로 활용하는 태도가 필요합니다.

AI 에이전트를 처음 써볼 때의 기준

AI 에이전트를 처음 접한다면 “무엇까지 자동으로 맡길 수 있을까?”보다 “어디까지 사람이 확인해야 할까?”를 먼저 생각하는 것이 좋습니다.

처음에는 다음 기준으로 접근하면 안전합니다.

정보 조사, 요약, 초안 작성처럼 되돌리기 쉬운 작업부터 맡긴다.
이메일 발송, 파일 수정, 결제처럼 영향이 큰 작업은 승인 후 실행으로 둔다.
결과가 맞는지 사람이 최종 확인한다.
민감한 정보는 입력 전에 서비스의 데이터 처리 방식을 확인한다.
처음부터 완전 자동화하려 하지 말고, 반복 작업 일부를 줄이는 방식으로 시작한다.

AI 에이전트는 사람의 판단을 완전히 대체하는 도구라기보다, 반복적인 중간 작업을 줄여주는 보조 시스템에 가깝습니다.

AI 에이전트를 이해할 때 기억할 핵심

AI 에이전트를 어렵게 생각할 필요는 없습니다.

핵심은 다음 한 문장으로 정리할 수 있습니다.

AI 에이전트는 목표를 받고, 계획을 세우고, 도구를 사용해 작업을 수행하는 AI 시스템입니다.

단순 챗봇은 질문에 답합니다. AI 에이전트는 목표를 달성하기 위한 과정을 진행합니다.

예를 들어 “요약해줘”는 챗봇도 잘할 수 있습니다. 하지만 “자료를 찾고, 비교하고, 정리해서 보고서 형태로 만들어줘”는 에이전트에 가까운 작업입니다.

앞으로 AI 서비스는 단순히 대화하는 형태에서 벗어나, 사용자의 일을 대신 처리하는 방향으로 더 발전할 가능성이 큽니다.

다만 AI 에이전트가 사람의 판단을 완전히 대체한다고 보기는 어렵습니다. 현실적인 활용 방식은 사람이 목표를 정하고, AI가 중간 작업을 돕고, 사람이 최종 결과를 검토하는 구조에 가깝습니다.

AI 에이전트를 제대로 이해하려면 “AI가 다 알아서 한다”가 아니라, 사람이 지시하고 AI가 실행을 보조하는 작업 파트너로 보는 것이 좋습니다.

FAQ

AI 에이전트는 ChatGPT와 같은 건가요?

완전히 같지는 않습니다. ChatGPT는 대화형 AI 서비스이고, AI 에이전트는 목표를 수행하기 위해 계획을 세우고 도구를 사용할 수 있는 시스템을 뜻합니다. 다만 ChatGPT 같은 서비스 안에 에이전트 기능이 포함될 수는 있습니다.

AI 에이전트를 처음 써볼 때 어떤 작업부터 맡기면 좋나요?

정보 조사, 문서 요약, 글 초안 작성, 회의록 정리처럼 사람이 쉽게 검토할 수 있는 작업부터 시작하는 것이 좋습니다. 반대로 결제, 메일 자동 발송, 파일 삭제처럼 되돌리기 어려운 작업은 처음부터 자동화하지 않는 편이 안전합니다.

AI 에이전트가 만든 결과는 그대로 써도 되나요?

중요한 결과물이라면 그대로 쓰기보다 확인 과정을 거치는 것이 좋습니다. 특히 최신 정보, 숫자, 법률·의료·재무 관련 내용, 회사 내부 자료와 연결된 작업은 사람이 검토해야 합니다.

AI 에이전트는 어디에 활용할 수 있나요?

자료 조사, 일정 관리, 고객 응대, 블로그 글 작성, 코드 작성, 데이터 분석, 반복 업무 자동화 등에 활용될 수 있습니다. 다만 서비스마다 가능한 기능과 권한 범위가 다르므로 실제 사용 전 확인이 필요합니다.

AI 에이전트를 이해할 때 가장 중요한 점은 무엇인가요?

AI 에이전트는 “질문에 답하는 도구”를 넘어 “목표를 처리하도록 설계된 시스템”에 가깝다는 점입니다. 다만 최종 판단과 책임은 여전히 사람이 가져야 합니다.

파이썬 모듈과 패키지: import로 코드를 나누고 재사용하는 방법

notebase — Fri, 22 May 2026 10:17:44 +0900

파이썬 모듈과 패키지의 차이, import 사용법, 표준 라이브러리와 외부 패키지 설치 개념을 초보자 기준으로 정리합니다.

파이썬 모듈과 패키지는 코드를 여러 파일로 나누고 다시 가져와 쓰기 위한 구조입니다. 코드가 길어질수록 한 파일에 모든 내용을 넣기 어렵기 때문에, 기능별로 나누는 방법을 알아야 합니다.

처음에는 import가 낯설 수 있습니다. 하지만 핵심은 단순합니다. 이미 만들어둔 코드를 현재 파일에서 불러와 사용하는 것입니다.

모듈이란 무엇일까

파이썬에서 모듈은 보통 하나의 .py 파일을 의미합니다.

예를 들어 calculator.py라는 파일을 만들었다고 하겠습니다.

# calculator.py

def add(a, b):
    return a + b

def subtract(a, b):
    return a - b

이 파일은 계산 기능을 담은 모듈로 볼 수 있습니다.

다른 파이썬 파일에서 이 모듈을 불러올 수 있습니다.

import calculator

print(calculator.add(3, 5))
print(calculator.subtract(10, 4))

실행 결과는 다음과 같습니다.

8
6

import calculator는 calculator.py 파일을 가져온다는 뜻입니다.

모듈 안의 함수를 사용할 때는 calculator.add()처럼 모듈 이름을 함께 붙입니다.

import 기본 사용법

가장 기본적인 import 방식은 다음과 같습니다.

import 모듈이름

예를 들어 파이썬에서 제공하는 math 모듈을 사용할 수 있습니다.

import math

print(math.sqrt(16))
print(math.pi)

실행 결과는 다음과 비슷합니다.

4.0
3.141592653589793

math.sqrt()는 제곱근을 구하는 함수입니다.

math.pi는 원주율 값을 나타냅니다.

from import 사용하기

모듈 전체가 아니라 특정 함수만 가져올 수도 있습니다.

from math import sqrt

print(sqrt(16))

이 경우에는 math.sqrt()가 아니라 바로 sqrt()라고 사용할 수 있습니다.

여러 개를 가져올 수도 있습니다.

from math import sqrt, pi

print(sqrt(25))
print(pi)

다만 가져오는 이름이 많아지면 어디에서 온 함수인지 헷갈릴 수 있습니다.

초보 단계에서는 import math처럼 모듈 이름을 붙여 사용하는 방식이 더 명확할 때가 많습니다.

as로 이름 줄이기

모듈 이름이 길거나 자주 사용할 때는 as로 별명을 붙일 수 있습니다.

import random as rd

print(rd.randint(1, 10))

random 모듈을 rd라는 이름으로 사용한 예입니다.

실무에서는 자주 쓰이는 별명이 있습니다.

import pandas as pd
import numpy as np

다만 처음 배울 때는 별명을 무리하게 쓰기보다 원래 이름으로 이해하는 것이 좋습니다.

표준 라이브러리란 무엇일까

파이썬은 설치할 때 기본으로 제공되는 모듈이 많습니다. 이를 표준 라이브러리라고 합니다.

대표적인 예는 다음과 같습니다.

모듈	용도
`math`	수학 계산
`random`	무작위 값 생성
`datetime`	날짜와 시간 처리
`os`	운영체제 관련 기능
`sys`	파이썬 실행 환경 관련 기능

예를 들어 무작위 숫자를 만들고 싶다면 random 모듈을 사용할 수 있습니다.

import random

number = random.randint(1, 6)
print(number)

1부터 6 사이의 정수가 무작위로 출력됩니다.

주사위 기능을 만들 때 사용할 수 있습니다.

직접 만든 모듈 사용하기

같은 폴더에 두 파일이 있다고 가정하겠습니다.

project/
├── main.py
└── greeting.py

greeting.py 파일에는 함수를 작성합니다.

# greeting.py

def hello(name):
    return name + "님, 안녕하세요"

main.py에서는 이 함수를 가져와 사용할 수 있습니다.

# main.py

import greeting

message = greeting.hello("민수")
print(message)

실행 결과는 다음과 같습니다.

민수님, 안녕하세요

이렇게 기능별로 파일을 나누면 코드 관리가 쉬워집니다.

패키지란 무엇일까

패키지는 여러 모듈을 묶어놓은 폴더 구조입니다.

예를 들어 다음과 같은 구조가 있을 수 있습니다.

my_package/
├── __init__.py
├── calculator.py
└── greeting.py

여기서 my_package는 패키지입니다.

그 안의 calculator.py, greeting.py는 모듈입니다.

패키지 안의 모듈을 사용할 때는 다음처럼 가져올 수 있습니다.

from my_package import calculator

print(calculator.add(3, 5))

패키지는 코드가 많아졌을 때 기능별로 정리하는 데 유용합니다.

초보 단계에서는 “모듈은 파이썬 파일, 패키지는 모듈을 담는 폴더”라고 이해하면 됩니다.

init.py는 무엇일까

패키지 예제에서 __init__.py 파일이 보였을 것입니다.

이 파일은 해당 폴더를 파이썬 패키지로 인식하게 하는 역할을 해왔습니다.

최근 파이썬에서는 일부 경우 __init__.py가 없어도 패키지처럼 동작할 수 있습니다. 하지만 초보 단계에서는 패키지 폴더에 __init__.py를 두는 방식으로 익히는 것이 이해하기 쉽습니다.

처음에는 파일 내용이 비어 있어도 괜찮습니다.

# __init__.py

외부 패키지란 무엇일까

파이썬에는 기본 제공 모듈 외에도 다른 개발자들이 만든 패키지를 설치해서 사용할 수 있습니다.

예를 들어 웹 요청을 쉽게 처리하는 requests, 데이터 분석에 자주 쓰이는 pandas 같은 패키지가 있습니다.

외부 패키지는 보통 pip 명령어로 설치합니다.

pip install requests

설치한 뒤에는 파이썬 코드에서 import해서 사용할 수 있습니다.

import requests

다만 외부 패키지를 설치하는 명령은 터미널이나 명령 프롬프트에서 실행합니다. 파이썬 코드 파일 안에 직접 쓰는 코드가 아닙니다.

import할 때 자주 하는 실수

1. 파일 이름을 표준 모듈과 같게 짓기

예를 들어 파일 이름을 random.py로 만들면 파이썬의 표준 random 모듈과 충돌할 수 있습니다.

random.py

이런 이름은 피하는 것이 좋습니다.

my_random_test.py처럼 더 구체적인 이름을 사용하면 충돌을 줄일 수 있습니다.

2. 모듈 이름에 하이픈 사용하기

파이썬 파일 이름에 하이픈을 사용하면 import하기 어렵습니다.

my-module.py

이보다는 밑줄을 사용하는 것이 좋습니다.

my_module.py

3. 설치하지 않은 외부 패키지를 import하기

import requests

이 코드는 requests가 설치되어 있어야 동작합니다.

설치되어 있지 않다면 ModuleNotFoundError가 발생합니다.

이럴 때는 터미널에서 패키지를 설치해야 합니다.

pip install requests

모듈을 나누는 기준

처음부터 파일을 너무 많이 나눌 필요는 없습니다.

코드가 짧을 때는 하나의 파일로도 충분합니다.

하지만 아래와 같은 상황이라면 모듈 분리를 생각해볼 수 있습니다.

같은 함수가 여러 파일에서 필요할 때
한 파일이 너무 길어져서 읽기 어려울 때
계산, 입력, 출력, 설정 같은 역할을 나누고 싶을 때
프로젝트 구조를 정리하고 싶을 때

모듈은 코드를 더 복잡하게 만드는 도구가 아니라, 복잡해진 코드를 정리하기 위한 도구입니다.

정리

파이썬 모듈은 하나의 .py 파일입니다. 패키지는 여러 모듈을 담은 폴더 구조입니다.

import를 사용하면 다른 파일이나 파이썬이 제공하는 기능을 현재 코드에서 사용할 수 있습니다.

초보 단계에서는 먼저 import math, import random 같은 표준 라이브러리 사용법부터 익히는 것이 좋습니다. 이후 직접 만든 파일을 모듈로 불러오고, 코드가 많아지면 패키지 구조로 나누면 됩니다.

파이썬 파일 입출력: 텍스트 파일 읽고 쓰는 기본 방법

notebase — Fri, 22 May 2026 10:05:51 +0900

파이썬에서 텍스트 파일을 읽고 쓰는 방법을 open, with, read, readline, write 예제로 초보자 기준에서 정리합니다.

파이썬 파일 입출력은 프로그램 밖에 있는 파일을 읽거나, 프로그램에서 만든 내용을 파일로 저장하는 방법입니다. 메모장에 적힌 내용을 읽거나, 계산 결과를 텍스트 파일로 저장할 때 사용할 수 있습니다.

프로그램 안의 변수는 실행이 끝나면 사라집니다. 하지만 파일로 저장하면 나중에 다시 열어 사용할 수 있습니다.

파일 입출력이 필요한 상황

예를 들어 다음과 같은 경우 파일 입출력이 필요합니다.

사용자가 입력한 내용을 저장할 때
프로그램 실행 결과를 기록할 때
텍스트 파일에 있는 데이터를 읽어올 때
로그 파일을 만들 때
설정 파일을 불러올 때

초보 단계에서는 먼저 텍스트 파일을 읽고 쓰는 방법부터 익히면 충분합니다.

open 함수 기본 구조

파이썬에서 파일을 다룰 때는 open() 함수를 사용합니다.

file = open("sample.txt", "r", encoding="utf-8")
content = file.read()
print(content)
file.close()

이 코드는 sample.txt 파일을 읽어서 화면에 출력합니다.

여기서 중요한 부분은 세 가지입니다.

코드	의미
`sample.txt`	열 파일 이름
`r`	읽기 모드
`encoding="utf-8"`	한글 처리를 위한 인코딩 설정

파일을 열었으면 마지막에 close()로 닫아야 합니다.

하지만 매번 직접 닫는 방식은 실수하기 쉽습니다. 그래서 보통은 with 문을 사용합니다.

with 문으로 파일 열기

파일 입출력에서는 with 문을 사용하는 방식이 일반적입니다.

with open("sample.txt", "r", encoding="utf-8") as file:
    content = file.read()
    print(content)

with 문을 사용하면 파일을 직접 닫지 않아도 됩니다.

코드 블록이 끝나면 파이썬이 자동으로 파일을 닫아줍니다.

따라서 초보자라면 파일을 다룰 때 with open(...) as file: 형태를 기본으로 사용하는 것이 좋습니다.

파일 읽기 모드

파일을 읽을 때는 r 모드를 사용합니다.

with open("memo.txt", "r", encoding="utf-8") as file:
    text = file.read()
    print(text)

read()는 파일 전체 내용을 하나의 문자열로 읽습니다.

예를 들어 memo.txt 파일 내용이 다음과 같다고 가정하겠습니다.

파이썬 공부
파일 입출력 연습

실행 결과는 다음과 같습니다.

파이썬 공부
파일 입출력 연습

파일 전체를 한 번에 읽고 싶을 때 read()를 사용합니다.

한 줄씩 읽기

파일을 한 줄씩 읽고 싶을 때는 readline()을 사용할 수 있습니다.

with open("memo.txt", "r", encoding="utf-8") as file:
    line1 = file.readline()
    line2 = file.readline()

print(line1)
print(line2)

readline()은 호출할 때마다 한 줄씩 읽습니다.

하지만 실제로는 반복문과 함께 파일을 읽는 방식이 더 자주 사용됩니다.

with open("memo.txt", "r", encoding="utf-8") as file:
    for line in file:
        print(line.strip())

strip()은 줄 끝의 줄바꿈 문자나 앞뒤 공백을 제거할 때 사용합니다.

파일을 줄 단위로 처리해야 한다면 이 방식이 읽기 좋습니다.

여러 줄을 리스트로 읽기

readlines()를 사용하면 파일의 각 줄을 리스트로 가져올 수 있습니다.

with open("memo.txt", "r", encoding="utf-8") as file:
    lines = file.readlines()

print(lines)

실행 결과는 다음과 비슷합니다.

['파이썬 공부\n', '파일 입출력 연습\n']

각 줄이 리스트의 요소로 들어갑니다.

줄 끝에 \n이 포함될 수 있다는 점을 기억해야 합니다.

파일 쓰기 모드

파일에 내용을 저장할 때는 w 모드를 사용합니다.

with open("result.txt", "w", encoding="utf-8") as file:
    file.write("파이썬 파일 쓰기 연습")

이 코드를 실행하면 result.txt 파일이 만들어지고 내용이 저장됩니다.

중요한 점이 있습니다.

w 모드는 기존 파일 내용이 있으면 모두 지우고 새로 씁니다.

예를 들어 이미 result.txt에 내용이 있었더라도 위 코드를 실행하면 기존 내용은 사라집니다.

줄바꿈 넣어서 쓰기

write()는 자동으로 줄바꿈을 넣어주지 않습니다.

줄을 나누고 싶다면 \n을 직접 넣어야 합니다.

with open("result.txt", "w", encoding="utf-8") as file:
    file.write("첫 번째 줄\n")
    file.write("두 번째 줄\n")

저장된 파일 내용은 다음과 같습니다.

첫 번째 줄
두 번째 줄

파일에 내용 추가하기

기존 내용을 지우지 않고 뒤에 추가하고 싶다면 a 모드를 사용합니다.

with open("result.txt", "a", encoding="utf-8") as file:
    file.write("추가된 줄\n")

a는 append의 의미입니다.

파일 끝에 새로운 내용이 추가됩니다.

파일 모드 정리

모드	의미	특징
`r`	읽기	파일이 없으면 오류 발생
`w`	쓰기	기존 내용을 지우고 새로 작성
`a`	추가	기존 내용 뒤에 이어서 작성
`x`	새 파일 생성	파일이 이미 있으면 오류 발생

초보 단계에서는 r, w, a 세 가지만 먼저 익히면 충분합니다.

파일이 없을 때 발생하는 오류

읽기 모드에서 파일이 없으면 오류가 발생합니다.

with open("없는파일.txt", "r", encoding="utf-8") as file:
    content = file.read()

이 코드는 FileNotFoundError가 발생할 수 있습니다.

파일이 없을 가능성이 있다면 예외 처리를 함께 사용할 수 있습니다.

try:
    with open("memo.txt", "r", encoding="utf-8") as file:
        content = file.read()
        print(content)
except FileNotFoundError:
    print("파일을 찾을 수 없습니다.")

파일 입출력은 예외 처리와 함께 쓰이는 경우가 많습니다.

간단한 메모 저장 예제

사용자가 입력한 내용을 파일에 저장하는 예제를 보겠습니다.

memo = input("메모를 입력하세요: ")

with open("memo.txt", "w", encoding="utf-8") as file:
    file.write(memo)

입력한 메모가 memo.txt 파일에 저장됩니다.

이번에는 저장된 파일을 다시 읽어보겠습니다.

with open("memo.txt", "r", encoding="utf-8") as file:
    memo = file.read()

print("저장된 메모:", memo)

이렇게 파일에 저장하면 프로그램을 종료한 뒤에도 데이터를 다시 사용할 수 있습니다.

인코딩을 지정해야 하는 이유

한글이 들어간 파일을 다룰 때는 encoding="utf-8"을 지정하는 것이 좋습니다.

with open("memo.txt", "r", encoding="utf-8") as file:
    content = file.read()

인코딩 설정이 맞지 않으면 한글이 깨지거나 오류가 발생할 수 있습니다.

특히 윈도우 환경에서는 인코딩 문제를 만나는 경우가 있으므로 초보 단계부터 encoding="utf-8"을 쓰는 습관을 들이는 것이 좋습니다.

정리

파이썬 파일 입출력은 파일을 읽고 쓰기 위한 기본 문법입니다.

파일을 열 때는 open()을 사용하고, 가능하면 with 문과 함께 사용하는 것이 좋습니다.

읽을 때는 r, 새로 쓸 때는 w, 기존 내용 뒤에 추가할 때는 a 모드를 사용합니다.

텍스트 파일을 다룰 때는 한글 깨짐을 줄이기 위해 encoding="utf-8"을 함께 지정하는 편이 안전합니다.

파이썬 예외 처리: 오류가 나도 프로그램이 멈추지 않게 하는 방법

notebase — Fri, 22 May 2026 08:32:29 +0900

파이썬 예외 처리의 기본 구조와 try, except, else, finally 사용법을 초보자 기준 예제로 정리합니다.

파이썬 예외 처리는 프로그램 실행 중 발생할 수 있는 오류를 안전하게 처리하는 방법입니다. 파일이 없거나, 숫자로 바꿀 수 없는 값이 들어오거나, 0으로 나누는 상황에서 프로그램이 바로 종료되지 않도록 도와줍니다.

코드를 작성하다 보면 오류는 피할 수 없습니다. 중요한 것은 오류가 났을 때 프로그램이 어떻게 반응하게 할지 정하는 것입니다.

오류와 예외는 무엇이 다를까

파이썬에서 오류는 크게 두 가지로 나눠볼 수 있습니다.

첫 번째는 문법 오류입니다.

print("안녕하세요"

괄호를 닫지 않았기 때문에 코드 자체가 실행되지 않습니다. 이런 오류는 실행 전에 고쳐야 합니다.

두 번째는 실행 중 발생하는 예외입니다.

number = int("abc")

문법은 맞지만 "abc"는 숫자로 바꿀 수 없습니다. 이 코드는 실행 중 ValueError가 발생합니다.

예외 처리는 주로 이런 실행 중 오류를 다룹니다.

예외 처리가 필요한 이유

사용자에게 숫자를 입력받는 코드를 생각해보겠습니다.

age = int(input("나이를 입력하세요: "))
print(age + 1)

사용자가 20을 입력하면 문제없이 동작합니다. 하지만 스무살이라고 입력하면 오류가 발생하고 프로그램이 종료됩니다.

이런 상황에서 예외 처리를 사용합니다.

try:
    age = int(input("나이를 입력하세요: "))
    print(age + 1)
except ValueError:
    print("숫자로 입력해야 합니다.")

사용자가 숫자가 아닌 값을 입력해도 프로그램이 바로 종료되지 않고 안내 문구를 출력합니다.

try except 기본 구조

예외 처리의 기본 구조는 다음과 같습니다.

try:
    예외가 발생할 수 있는 코드
except 예외종류:
    예외가 발생했을 때 실행할 코드

예제를 보겠습니다.

try:
    result = 10 / 0
except ZeroDivisionError:
    print("0으로 나눌 수 없습니다.")

실행 결과는 다음과 같습니다.

0으로 나눌 수 없습니다.

10 / 0은 실행할 수 없는 계산입니다. 그래서 ZeroDivisionError가 발생합니다.

이때 except ZeroDivisionError 아래 코드가 실행됩니다.

여러 예외 처리하기

하나의 코드에서 여러 종류의 예외가 발생할 수 있습니다.

try:
    number = int(input("숫자를 입력하세요: "))
    result = 10 / number
    print(result)
except ValueError:
    print("숫자만 입력할 수 있습니다.")
except ZeroDivisionError:
    print("0으로 나눌 수 없습니다.")

이 코드는 두 가지 예외를 처리합니다.

숫자로 바꿀 수 없는 값이 들어오면 ValueError
0을 입력하면 ZeroDivisionError

예외 종류를 나눠 쓰면 사용자에게 더 정확한 안내를 할 수 있습니다.

모든 예외를 한 번에 처리할 수도 있다

아래처럼 예외 종류를 쓰지 않고 처리할 수도 있습니다.

try:
    number = int(input("숫자를 입력하세요: "))
    print(10 / number)
except:
    print("오류가 발생했습니다.")

하지만 이 방식은 주의해야 합니다. 어떤 오류가 발생했는지 알기 어렵기 때문입니다.

초보 단계에서도 가능한 한 구체적인 예외 이름을 쓰는 습관이 좋습니다.

권장되는 방식은 다음과 같습니다.

try:
    number = int(input("숫자를 입력하세요: "))
    print(10 / number)
except ValueError:
    print("숫자만 입력해주세요.")
except ZeroDivisionError:
    print("0은 입력할 수 없습니다.")

예외 메시지 확인하기

예외가 발생했을 때 파이썬이 제공하는 메시지를 확인할 수도 있습니다.

try:
    number = int("abc")
except ValueError as e:
    print("오류 내용:", e)

이 방식은 오류 원인을 확인할 때 유용합니다.

else 사용하기

else는 예외가 발생하지 않았을 때 실행됩니다.

try:
    number = int(input("숫자를 입력하세요: "))
except ValueError:
    print("숫자로 입력해야 합니다.")
else:
    print("입력한 숫자:", number)

예외가 발생하면 except가 실행됩니다. 예외가 발생하지 않으면 else가 실행됩니다.

성공했을 때 실행할 코드를 분리하고 싶다면 사용할 수 있습니다.

finally 사용하기

finally는 예외 발생 여부와 상관없이 항상 실행됩니다.

try:
    file = open("sample.txt", "r", encoding="utf-8")
    content = file.read()
except FileNotFoundError:
    print("파일을 찾을 수 없습니다.")
finally:
    print("작업을 종료합니다.")

파일을 찾든 찾지 못하든 finally 아래 코드는 실행됩니다.

실무에서는 파일 닫기, 연결 종료, 임시 작업 정리처럼 반드시 실행해야 하는 코드를 넣을 때 사용합니다.

다만 파일을 다룰 때는 보통 with 문을 더 자주 사용합니다. 파일 입출력 글에서 따로 다루는 것이 좋습니다.

raise로 예외 직접 발생시키기

필요한 경우 개발자가 직접 예외를 발생시킬 수도 있습니다.

def check_age(age):
    if age < 0:
        raise ValueError("나이는 음수가 될 수 없습니다.")
    return age

print(check_age(20))
print(check_age(-1))

age가 음수라면 ValueError를 직접 발생시킵니다.

이 방식은 잘못된 값이 들어왔을 때 코드 흐름을 강제로 중단하고 싶을 때 사용합니다.

초보 단계에서는 “조건에 맞지 않는 값이 들어오면 예외를 직접 만들 수도 있다” 정도로 이해하면 충분합니다.

자주 발생하는 예외 종류

예외 이름	발생 상황
`ValueError`	값의 형태가 맞지 않을 때
`TypeError`	자료형이 맞지 않을 때
`ZeroDivisionError`	0으로 나누려고 할 때
`IndexError`	리스트 인덱스 범위를 벗어날 때
`KeyError`	딕셔너리에 없는 키를 사용할 때
`FileNotFoundError`	파일을 찾을 수 없을 때

예외 이름을 모두 외울 필요는 없습니다. 자주 만나는 오류부터 하나씩 익히면 됩니다.

예외 처리를 너무 넓게 쓰지 않기

예외 처리는 편리하지만, 모든 코드를 감싸는 방식으로 쓰면 좋지 않습니다.

try:
    # 아주 많은 코드
    pass
except Exception:
    print("오류 발생")

이런 코드는 어디에서 문제가 생겼는지 찾기 어렵습니다.

예외 처리는 “오류가 발생할 가능성이 있는 부분”에만 좁게 적용하는 편이 좋습니다.

정리

파이썬 예외 처리는 실행 중 발생하는 오류를 안전하게 다루는 방법입니다.

기본 구조는 try와 except입니다. 예외가 발생할 수 있는 코드는 try에 넣고, 오류가 발생했을 때 실행할 코드는 except에 넣습니다.

가능하면 구체적인 예외 이름을 사용하고, 예외 처리 범위는 너무 넓게 잡지 않는 것이 좋습니다.

처음에는 ValueError, ZeroDivisionError, FileNotFoundError처럼 자주 만나는 예외부터 익히면 충분합니다.

파이썬 함수: 반복되는 코드를 줄이고 재사용하는 방법

notebase — Fri, 22 May 2026 08:18:20 +0900

파이썬 함수의 기본 구조부터 매개변수, return, 기본값, 가변 인자까지 초보자 기준으로 예제와 함께 정리합니다.

파이썬 함수는 반복되는 코드를 하나로 묶어 다시 사용할 수 있게 해주는 문법입니다. 같은 코드를 여러 번 쓰는 대신 함수로 만들면 코드가 짧아지고, 수정하기도 쉬워집니다.

처음에는 함수가 조금 낯설 수 있습니다. 하지만 실제로는 “자주 쓰는 작업에 이름을 붙이는 것”에 가깝습니다.

함수가 필요한 이유

같은 인사 문장을 여러 번 출력한다고 생각해보겠습니다.

print("안녕하세요")
print("안녕하세요")
print("안녕하세요")

이 정도는 괜찮아 보일 수 있습니다. 하지만 같은 작업이 10번, 100번 반복된다면 코드가 금방 지저분해집니다.

이럴 때 함수를 사용합니다.

def say_hello():
    print("안녕하세요")

say_hello()
say_hello()
say_hello()

def say_hello():는 say_hello라는 함수를 만든다는 뜻입니다.

그 아래 들여쓰기 된 코드는 함수가 실행될 때 동작하는 내용입니다.

마지막의 say_hello()는 만든 함수를 호출하는 코드입니다.

함수는 만들어두기만 해서는 실행되지 않습니다. 반드시 함수 이름 뒤에 괄호를 붙여 호출해야 실행됩니다.

함수의 기본 구조

파이썬 함수의 기본 구조는 다음과 같습니다.

def 함수이름():
    실행할 코드

예제를 하나 더 보겠습니다.

def print_line():
    print("----------------")

print_line()
print("회원 정보")
print_line()

실행 결과는 다음과 같습니다.

----------------
회원 정보
----------------

print_line() 함수는 구분선을 출력하는 역할만 합니다. 이렇게 간단한 함수라도 코드의 의미가 명확해집니다.

매개변수가 있는 함수

함수는 외부에서 값을 받아 사용할 수 있습니다.

이때 함수가 받는 값을 매개변수라고 합니다.

def say_hello(name):
    print(name + "님, 안녕하세요")

say_hello("민수")
say_hello("지영")

실행 결과는 다음과 같습니다.

민수님, 안녕하세요
지영님, 안녕하세요

여기서 name이 매개변수입니다.

함수를 호출할 때 전달한 "민수", "지영" 값이 함수 안의 name에 들어갑니다.

매개변수를 여러 개 받는 함수

매개변수는 하나만 받을 수 있는 것이 아닙니다.

여러 개의 값을 받을 수도 있습니다.

def add(a, b):
    print(a + b)

add(3, 5)
add(10, 20)

실행 결과는 다음과 같습니다.

8
30

a와 b는 함수 안에서만 사용하는 이름입니다.

함수를 호출할 때 add(3, 5)라고 쓰면 a에는 3, b에는 5가 들어갑니다.

return으로 결과 돌려주기

지금까지는 함수 안에서 바로 print()를 사용했습니다.

하지만 실제 코드에서는 함수가 계산한 결과를 다시 돌려줘야 할 때가 많습니다. 이때 return을 사용합니다.

def add(a, b):
    return a + b

result = add(3, 5)
print(result)

실행 결과는 다음과 같습니다.

return a + b는 a + b의 결과를 함수 밖으로 돌려준다는 뜻입니다.

함수 호출 결과를 result 변수에 저장한 뒤 출력할 수 있습니다.

print와 return의 차이

초보자가 자주 헷갈리는 부분이 print와 return입니다.

print()는 화면에 보여주는 역할입니다.

return은 함수의 결과를 밖으로 보내는 역할입니다.

def add_print(a, b):
    print(a + b)

x = add_print(2, 3)
print(x)

실행 결과는 다음과 같습니다.

5
None

함수 안에서 print(a + b)로 5는 출력됐습니다.

하지만 return을 하지 않았기 때문에 함수의 결과값은 None입니다.

반대로 return을 사용하면 결과를 변수에 저장해서 다시 사용할 수 있습니다.

def add_return(a, b):
    return a + b

x = add_return(2, 3)
print(x * 10)

실행 결과는 다음과 같습니다.

계산 결과를 다시 사용해야 한다면 return을 쓰는 편이 좋습니다.

기본값 매개변수

함수의 매개변수에는 기본값을 지정할 수 있습니다.

def greet(name="사용자"):
    print(name + "님, 안녕하세요")

greet("민수")
greet()

실행 결과는 다음과 같습니다.

민수님, 안녕하세요
사용자님, 안녕하세요

greet()처럼 값을 전달하지 않으면 기본값인 "사용자"가 사용됩니다.

단, 기본값이 있는 매개변수는 보통 기본값이 없는 매개변수 뒤에 둡니다.

def introduce(name, age=20):
    print(name, age)

이런 형태는 자연스럽습니다.

키워드 인자

함수를 호출할 때 매개변수 이름을 직접 지정할 수도 있습니다.

def introduce(name, age):
    print("이름:", name)
    print("나이:", age)

introduce(name="민수", age=25)
introduce(age=30, name="지영")

이렇게 매개변수 이름을 지정해서 전달하는 값을 키워드 인자라고 합니다.

키워드 인자를 사용하면 순서가 바뀌어도 어떤 값이 어디에 들어가는지 명확합니다.

가변 인자 args

몇 개의 값이 들어올지 모를 때는 *args를 사용할 수 있습니다.

def add_all(*args):
    total = 0
    for number in args:
        total += number
    return total

print(add_all(1, 2, 3))
print(add_all(10, 20, 30, 40))

실행 결과는 다음과 같습니다.

6
100

*args는 여러 값을 튜플 형태로 받습니다.

함수에 전달할 값의 개수가 정해져 있지 않을 때 유용합니다.

함수 안의 변수와 밖의 변수

함수 안에서 만든 변수는 기본적으로 함수 안에서만 사용할 수 있습니다.

def test():
    message = "안녕하세요"
    print(message)

test()
print(message)

이 코드는 오류가 납니다.

message는 함수 안에서 만든 변수이기 때문에 함수 밖에서는 사용할 수 없습니다.

이런 범위를 스코프라고 합니다.

초보 단계에서는 “함수 안에서 만든 변수는 함수 안에서만 쓴다”고 이해하면 충분합니다.

함수 이름을 지을 때 주의할 점

함수 이름은 코드의 의미를 설명할 수 있어야 합니다.

def a():
    pass

이런 이름은 좋지 않습니다. 무엇을 하는 함수인지 알기 어렵기 때문입니다.

아래처럼 동작이 드러나는 이름이 좋습니다.

def calculate_total_price():
    pass

def print_user_info():
    pass

def get_average_score():
    pass

파이썬에서는 보통 소문자와 밑줄을 사용해 함수 이름을 짓습니다.

자주 하는 실수

1. 함수를 만들고 호출하지 않음

def hello():
    print("안녕하세요")

이 코드는 함수를 만들기만 한 상태입니다.

실행하려면 아래 코드가 필요합니다.

hello()

2. 들여쓰기를 잘못함

def hello():
print("안녕하세요")

파이썬은 들여쓰기가 문법의 일부입니다. 함수 안의 코드는 반드시 들여쓰기해야 합니다.

def hello():
    print("안녕하세요")

3. return과 print를 혼동함

함수 결과를 다시 사용해야 한다면 return을 사용해야 합니다.

단순히 화면에 보여주기만 한다면 print()를 사용할 수 있습니다.

정리

파이썬 함수는 코드를 재사용하기 위한 기본 문법입니다.

def로 함수를 만들고, 함수 이름 뒤에 괄호를 붙여 호출합니다. 외부에서 값을 받을 때는 매개변수를 사용하고, 결과를 돌려줄 때는 return을 사용합니다.

처음에는 작은 함수부터 만들어보는 것이 좋습니다.

예를 들어 “두 수를 더하는 함수”, “이름을 받아 인사하는 함수”, “점수 평균을 구하는 함수”처럼 단순한 함수부터 연습하면 함수의 구조가 자연스럽게 익숙해집니다.

파이썬 반복문 for while 사용법 쉽게 이해하기

notebase — Thu, 21 May 2026 19:03:38 +0900

if 조건문으로 흐름을 나눴다면, 이제 파이썬 반복문으로 같은 작업을 여러 번 실행하는 방법을 익힐 차례입니다.

반복할 대상이 정해져 있으면 for문, 조건이 참인 동안 계속 실행해야 하면 while문이 더 잘 맞습니다.

처음에는 두 문법이 비슷해 보여도, 언제 어떤 문법을 써야 하는지 구분해두면 코드가 훨씬 읽기 쉬워집니다.

반복문이 필요한 이유

같은 코드를 여러 번 써야 할 때 반복문이 필요합니다.

예를 들어 같은 문장을 세 번 출력한다고 해서 아래처럼 직접 세 줄을 쓰는 방식은 금방 불편해집니다.

print("안녕하세요")
print("안녕하세요")
print("안녕하세요")

이런 작업은 반복문으로 더 간단하게 표현할 수 있습니다.

for i in range(3):
    print("안녕하세요")

실행 결과:

안녕하세요
안녕하세요
안녕하세요

반복문을 사용하면 코드 길이가 줄고, 같은 작업을 여러 번 처리할 때 실수도 줄일 수 있습니다.

for문 기본 구조

for문은 반복할 대상에서 값을 하나씩 꺼내며 실행합니다.

기본 형태는 아래와 같습니다.

for 변수 in 반복할대상:
    실행할 코드

간단한 예제를 보면 더 이해하기 쉽습니다.

for number in [1, 2, 3]:
    print(number)

실행 결과:

1
2
3

위 코드는 리스트 안의 값을 하나씩 꺼내서 number에 넣고 출력합니다.

리스트와 함께 사용하는 for문

리스트는 for문과 가장 자주 함께 쓰는 자료형입니다.

fruits = ["사과", "바나나", "딸기"]

for fruit in fruits:
    print(fruit)

실행 결과:

사과
바나나
딸기

리스트 안의 값을 처음부터 끝까지 한 번씩 확인하고 싶을 때 for문이 자연스럽습니다.

문자열과 함께 사용하는 for문

문자열도 글자들이 순서대로 들어 있기 때문에 for문으로 한 글자씩 꺼낼 수 있습니다.

for letter in "Python":
    print(letter)

실행 결과:

P
y
t
h
o
n

문자열을 한 글자씩 검사하거나, 특정 글자가 있는지 확인하는 기초 연습에 자주 사용합니다.

range() 사용법

반복 횟수가 정해져 있을 때는 range()를 많이 사용합니다.

for number in range(5):
    print(number)

실행 결과:

range(5)는 0부터 시작해서 5 바로 전까지 숫자를 만듭니다.

즉, 5번 반복하고 싶을 때 자주 사용하는 형태입니다.

range(start, stop)

시작 숫자를 직접 정하고 싶다면 range(start, stop) 형태로 쓸 수 있습니다.

for number in range(1, 5):
    print(number)

실행 결과:

여기서 중요한 점은 stop 값인 5는 포함되지 않는다는 것입니다.

처음에는 1부터 5까지라고 생각하기 쉬운데, 실제로는 1부터 4까지입니다.

range(start, stop, step)

한 번에 얼마나 증가할지도 정할 수 있습니다.

for number in range(1, 10, 2):
    print(number)

실행 결과:

step은 숫자가 얼마나씩 건너뛸지를 뜻합니다.

위 예제는 1부터 시작해서 2씩 증가하며 10 전까지 반복합니다.

while문 기본 구조

while문은 조건식이 참인 동안 계속 실행됩니다.

기본 형태는 아래와 같습니다.

while 조건식:
    실행할 코드

예제를 보면 for문과 차이가 더 분명해집니다.

count = 1

while count <= 3:
    print(count)
    count += 1

실행 결과:

1
2
3

이 코드는 count <= 3이 참일 동안 반복하고, 반복할 때마다 count 값을 1씩 늘립니다.

while문에서 조건식이 중요한 이유

while문은 반복 횟수보다 조건이 언제 거짓이 되는지가 더 중요합니다.

위 예제에서 count += 1이 없다면 count는 계속 1인 상태로 남습니다.

그러면 count <= 3은 계속 참이 되고, 반복문은 끝나지 않습니다.

즉, while문에서는 조건식뿐 아니라 조건에 영향을 주는 값이 반복 안에서 바뀌는지도 함께 봐야 합니다.

무한 반복 주의

while문을 처음 배울 때 가장 자주 하는 실수 중 하나가 무한 반복입니다.

아래 코드는 반복이 끝나지 않습니다.

count = 1

while count <= 3:
    print(count)

이유는 count 값이 변하지 않기 때문입니다.

while문을 쓸 때는 "이 반복이 언제 끝나는가?"를 먼저 확인하는 습관이 필요합니다.

break 사용법

break는 반복문을 즉시 끝낼 때 사용합니다.

for number in [1, 2, 3, 4, 5]:
    if number == 4:
        break
    print(number)

실행 결과:

1
2
3

number가 4가 되는 순간 반복문이 바로 종료됩니다.

for문과 while문 모두에서 사용할 수 있습니다.

continue 사용법

continue는 반복문을 끝내는 것이 아니라, 이번 차례만 건너뛰고 다음 반복으로 넘어갈 때 사용합니다.

fruits = ["사과", "바나나", "딸기"]

for fruit in fruits:
    if fruit == "바나나":
        continue
    print(fruit)

실행 결과:

사과
딸기

바나나일 때는 print()를 실행하지 않고 다음 값으로 넘어간 것입니다.

for문과 while문의 차이

두 반복문은 모두 같은 작업을 여러 번 실행할 때 쓰지만 기준이 다릅니다.

for문은 반복할 대상이나 횟수가 비교적 분명할 때 사용합니다.
while문은 조건이 참인 동안 계속 실행해야 할 때 사용합니다.

짧게 정리하면 아래처럼 볼 수 있습니다.

for문: 리스트, 문자열, range()처럼 반복할 대상이 보일 때
while문: 조건이 언제 거짓이 되는지가 더 중요할 때

for문을 쓰기 좋은 경우

아래처럼 반복할 대상이 이미 정해져 있으면 for문이 더 간단합니다.

리스트 값을 하나씩 확인할 때
문자열을 한 글자씩 볼 때
range()로 정해진 횟수만큼 반복할 때

예를 들어 학생 점수를 순서대로 출력하는 작업은 for문이 잘 맞습니다.

while문을 쓰기 좋은 경우

반복 횟수를 미리 딱 잘라 말하기보다, 어떤 조건이 바뀔 때까지 계속 돌아야 하면 while문이 편합니다.

숫자가 특정 값이 될 때까지 줄이거나 늘릴 때
어떤 상태가 바뀔 때까지 반복할 때
반복 종료 시점이 조건에 따라 달라질 때

예를 들어 카운트다운처럼 값이 계속 바뀌면서 조건이 달라지는 작업은 while문으로 자주 표현합니다.

자주 발생하는 오류

숫자를 바로 for문에 넣는 경우

아래 코드는 초보자가 자주 헷갈리는 형태입니다.

for i in 3:
    print(i)

숫자 3 자체는 반복할 대상이 아니기 때문에 오류가 납니다.

반복 횟수를 정하고 싶다면 range(3)처럼 써야 합니다.

for i in range(3):
    print(i)

실행 결과:

0
1
2

range()의 끝값도 포함된다고 생각하는 경우

for number in range(1, 5):
    print(number)

실행 결과:

5가 출력되지 않는다는 점을 꼭 기억해야 합니다.

while문 안에서 값을 바꾸지 않는 경우

count = 1

while count <= 3:
    print(count)

이 코드는 count가 계속 1이라서 반복이 끝나지 않습니다.

while문에서는 조건을 바꿀 코드가 있는지 항상 같이 확인해야 합니다.

초보자용 예제

먼저 for문 예제입니다. 리스트 안에서 60점 이상인 점수만 출력합니다.

scores = [75, 52, 88, 60]

for score in scores:
    if score >= 60:
        print(score, "점 통과")

실행 결과:

75 점 통과
88 점 통과
60 점 통과

이번에는 while문 예제입니다. 숫자를 하나씩 줄이며 카운트다운합니다.

count = 3

while count > 0:
    print(count)
    count -= 1

실행 결과:

3
2
1

이 두 예제만 비교해봐도 for문은 정해진 값들을 순서대로 볼 때, while문은 조건이 바뀌는 흐름을 만들 때 더 어울린다는 점이 보입니다.

정리

파이썬 반복문은 같은 작업을 여러 번 실행할 때 사용하는 기본 문법입니다.

처음 배우는 단계에서는 아래 흐름만 분명히 이해해도 충분합니다.

for문: 반복할 대상이 정해져 있을 때
while문: 조건이 참인 동안 반복할 때
break: 반복을 바로 끝낼 때
continue: 이번 차례만 건너뛸 때

여기에 range()와 조건식의 동작까지 익히면, 리스트와 문자열을 다루는 반복문부터 간단한 조건 반복까지 자연스럽게 연결할 수 있습니다.

파이썬 조건문 if 사용법 쉽게 이해하기

notebase — Thu, 21 May 2026 18:43:56 +0900

딕셔너리와 집합으로 값을 정리했다면, 이제 파이썬 조건문 if로 상황에 따라 다른 코드를 실행하는 방법을 배울 차례입니다.

값이 같을 때만 실행하거나, 특정 조건에서만 다른 결과를 보여주고 싶을 때 if를 사용합니다.

조건문이 필요한 이유

프로그램은 항상 같은 일만 반복하지 않습니다.

나이에 따라 다른 안내를 보여주거나, 점수에 따라 다른 결과를 출력해야 할 때가 있습니다.

예를 들어 아래처럼 점수가 60점 이상일 때만 합격이라고 표시할 수 있습니다.

score = 75

if score >= 60:
    print("합격")

실행 결과:

합격

조건문이 없다면 상황에 따라 다른 동작을 만들기 어렵습니다.

if 기본 구조

if 조건문은 아래 형태로 작성합니다.

if 조건식:
    실행할 코드

여기서 중요한 점은 두 가지입니다.

if 뒤에는 조건식이 옵니다.
조건식 뒤에는 반드시 :가 붙습니다.

간단한 예제를 보면 더 이해하기 쉽습니다.

age = 20

if age >= 19:
    print("성인입니다")

실행 결과:

성인입니다

조건식이 참이면 들여쓰기된 코드가 실행됩니다.

들여쓰기의 중요성

파이썬은 들여쓰기로 코드의 범위를 구분합니다.

즉, if 아래에서 어디까지 실행할지를 들여쓰기로 판단합니다.

age = 20

if age >= 19:
    print("성인입니다")
    print("입장 가능합니다")

실행 결과:

성인입니다
입장 가능합니다

들여쓰기가 맞지 않으면 오류가 나거나, 생각과 다른 위치에서 코드가 실행될 수 있습니다.

age = 20

if age >= 19:
print("성인입니다")

위 코드는 들여쓰기가 없어서 오류가 납니다.

초보 단계에서는 공백 4칸 들여쓰기를 습관처럼 쓰는 것이 가장 편합니다.

비교 연산자

if 조건문에서는 비교 연산자를 자주 사용합니다.

연산자	의미	예시
`==`	같다	`age == 20`
`!=`	같지 않다	`age != 20`
`>`	크다	`score > 80`
`<`	작다	`score < 80`
`>=`	크거나 같다	`score >= 60`
`<=`	작거나 같다	`score <= 100`

예를 들어 아래처럼 사용할 수 있습니다.

number = 10

if number == 10:
    print("10입니다")

실행 결과:

10입니다

=는 값을 저장할 때 사용하고, ==는 같은지 비교할 때 사용한다는 점을 구분해야 합니다.

if else

조건이 참일 때와 거짓일 때를 나누고 싶다면 else를 함께 사용합니다.

score = 52

if score >= 60:
    print("합격")
else:
    print("불합격")

실행 결과:

불합격

if는 조건이 맞을 때 실행하고, else는 그 외의 경우를 처리합니다.

if elif else

조건이 두 개보다 많다면 elif를 사용합니다.

score = 85

if score >= 90:
    print("A")
elif score >= 80:
    print("B")
elif score >= 70:
    print("C")
else:
    print("D")

실행 결과:

위 코드는 위에서부터 순서대로 검사합니다.

한 조건이 참이 되면 그 아래 조건은 더 보지 않습니다.

여러 조건을 연결하는 and, or, not

조건을 하나만 쓰는 경우도 많지만, 두 개 이상을 함께 확인할 때도 있습니다.

and

and는 두 조건이 모두 참일 때만 참입니다.

age = 20
has_ticket = True

if age >= 19 and has_ticket:
    print("입장 가능합니다")

실행 결과:

입장 가능합니다

or

or는 둘 중 하나만 참이어도 참입니다.

day = "토요일"

if day == "토요일" or day == "일요일":
    print("주말입니다")

실행 결과:

주말입니다

not

not은 참과 거짓을 뒤집습니다.

is_closed = False

if not is_closed:
    print("영업 중입니다")

실행 결과:

영업 중입니다

in을 활용한 조건문

이전 글에서 배운 리스트, 딕셔너리, 집합에서도 조건문을 자주 사용합니다.

in은 어떤 값이 들어 있는지 확인할 때 편리합니다.

tags = {"python", "basic", "if"}

if "python" in tags:
    print("파이썬 태그가 있습니다")

실행 결과:

파이썬 태그가 있습니다

딕셔너리에서는 key가 있는지 확인할 때도 쓸 수 있습니다.

user = {"name": "철수", "age": 20}

if "name" in user:
    print(user["name"])

실행 결과:

철수

bool 값과 조건문

True, False 같은 bool 값은 조건문과 아주 잘 맞습니다.

is_logged_in = True

if is_logged_in:
    print("로그인 상태입니다")

실행 결과:

로그인 상태입니다

굳이 if is_logged_in == True:처럼 길게 쓰지 않아도 됩니다.

보통은 아래처럼 짧게 씁니다.

if is_logged_in:
    print("로그인 상태입니다")

반대로 False인지 보고 싶다면 not을 함께 사용할 수 있습니다.

is_logged_in = False

if not is_logged_in:
    print("로그인이 필요합니다")

실행 결과:

로그인이 필요합니다

자주 발생하는 오류

1. `=`와 `==`를 헷갈리는 경우

age = 20

if age = 20:
    print("같습니다")

이 코드는 오류가 납니다.

조건 비교는 ==를 써야 합니다.

if age == 20:
    print("같습니다")

2. 콜론 `:`을 빼먹는 경우

score = 90

if score >= 80
    print("통과")

if 조건식 뒤에는 반드시 :가 필요합니다.

3. 들여쓰기를 하지 않는 경우

score = 90

if score >= 80:
print("통과")

이 코드도 오류가 납니다.

if 아래의 실행문은 들여써야 합니다.

4. 순서를 잘못 써서 결과가 달라지는 경우

score = 95

if score >= 60:
    print("합격")
elif score >= 90:
    print("우수")

실행 결과:

합격

95는 90 이상이기도 하지만, 위에서 먼저 score >= 60이 참이 되었기 때문에 아래 elif까지 가지 않습니다.

조건이 더 엄격한 쪽을 위에 두는 습관이 필요합니다.

초보자용 예제

아래 예제는 in, and, bool 값을 함께 사용하는 간단한 예제입니다.

cart = ["우유", "빵", "사과"]
is_member = True
total = 12000

if "우유" in cart:
    print("우유가 장바구니에 있습니다")

if is_member and total >= 10000:
    print("할인 대상입니다")
else:
    print("할인 대상이 아닙니다")

실행 결과:

우유가 장바구니에 있습니다
할인 대상입니다

이 정도 예제를 직접 여러 번 바꿔보면 조건문이 훨씬 빨리 익숙해집니다.

예를 들어 total 값을 바꾸거나, is_member를 False로 바꿔서 결과가 어떻게 달라지는지 확인해보면 좋습니다.

정리

파이썬 조건문 if는 조건에 따라 코드를 다르게 실행할 때 사용하는 기본 문법입니다.

초보 단계에서는 아래 흐름만 먼저 확실히 익히면 충분합니다.

if: 조건이 참일 때 실행
if else: 참/거짓 두 경우 나누기
if elif else: 여러 경우 나누기
and, or, not: 조건 연결하기
in: 포함 여부 확인하기

특히 들여쓰기와 :는 문법의 일부이기 때문에 꼭 함께 익혀야 합니다.

파이썬 딕셔너리와 집합 set 쉽게 이해하기

notebase — Thu, 21 May 2026 18:34:53 +0900

파이썬 딕셔너리와 집합 set은 여러 값을 다룰 때 사용하는 자료형입니다. 딕셔너리는 이름과 값을 짝으로 저장하고, 집합은 중복 없는 값을 모아둘 때 사용합니다.

이전 글에서 리스트와 튜플을 다뤘습니다. 리스트와 튜플은 여러 값을 순서대로 저장하는 자료형입니다.

fruits = ["사과", "바나나", "딸기"]
print(fruits[0])

실행 결과는 다음과 같습니다.

사과

그런데 모든 데이터를 위치로만 다루면 불편한 경우가 있습니다.

user = ["철수", 20, "서울"]

이렇게 저장하면 user[0]이 이름이고, user[1]이 나이이며, user[2]가 지역이라는 사실을 따로 기억해야 합니다.

데이터가 많아질수록 헷갈리기 쉽습니다. 이럴 때 사용하는 자료형이 딕셔너리(dictionary) 입니다.

user = {
    "name": "철수",
    "age": 20,
    "city": "서울"
}

딕셔너리를 사용하면 값에 이름표를 붙여서 관리할 수 있습니다.

딕셔너리는 key와 value를 저장하는 자료형이다

딕셔너리는 key와 value를 한 쌍으로 저장합니다.

user = {
    "name": "철수",
    "age": 20,
    "city": "서울"
}

위 코드에서 "name", "age", "city"는 key입니다.
"철수", 20, "서울"은 value입니다.

key	value
name	철수
age	20
city	서울

딕셔너리는 리스트처럼 위치 번호로 값을 꺼내기보다, key를 사용해서 값을 꺼냅니다.

print(user["name"])
print(user["age"])

실행 결과는 다음과 같습니다.

철수
20

즉, 딕셔너리는 이렇게 이해하면 됩니다.

key를 넣으면 value가 나온다

파이썬 딕셔너리 만들기

딕셔너리는 중괄호 {}를 사용해서 만듭니다.

student = {
    "name": "영희",
    "score": 95
}

딕셔너리 안의 key와 value는 콜론 :으로 연결합니다.

"name": "영희"

여러 쌍을 넣을 때는 쉼표 ,로 구분합니다.

student = {
    "name": "영희",
    "score": 95,
    "grade": "A"
}

빈 딕셔너리도 만들 수 있습니다.

user = {}

빈 딕셔너리는 나중에 값을 하나씩 추가할 때 사용합니다.

user = {}

user["name"] = "철수"
user["age"] = 20

print(user)

실행 결과는 다음과 같습니다.

{'name': '철수', 'age': 20}

딕셔너리에서 값 꺼내기

딕셔너리에서 값을 꺼낼 때는 key를 사용합니다.

user = {
    "name": "철수",
    "age": 20,
    "city": "서울"
}

print(user["name"])
print(user["city"])

실행 결과는 다음과 같습니다.

철수
서울

리스트는 인덱스로 값을 꺼냅니다.

fruits = ["사과", "바나나", "딸기"]
print(fruits[0])

딕셔너리는 key로 값을 꺼냅니다.

user = {
    "name": "철수"
}

print(user["name"])

get()으로 값 꺼내기

딕셔너리에서 값을 꺼낼 때는 get()을 사용할 수도 있습니다.

user = {
    "name": "철수",
    "age": 20
}

print(user.get("name"))

실행 결과는 다음과 같습니다.

철수

대괄호와 get()은 없는 key를 사용할 때 차이가 있습니다.

print(user["city"])

이 코드는 오류가 발생합니다.

KeyError: 'city'

반면 get()은 없는 key를 사용해도 오류가 나지 않고 None을 반환합니다.

print(user.get("city"))

기본값을 직접 지정할 수도 있습니다.

print(user.get("city", "지역 정보 없음"))

실행 결과는 다음과 같습니다.

지역 정보 없음

초보 단계에서는 이렇게 기억하면 됩니다.

확실히 있는 key라면 []
없는 key일 수도 있다면 get()

딕셔너리에 값 추가하기

딕셔너리에 값을 추가하는 방법은 간단합니다.

user = {
    "name": "철수",
    "age": 20
}

user["city"] = "서울"

print(user)

실행 결과는 다음과 같습니다.

{'name': '철수', 'age': 20, 'city': '서울'}

새로운 key를 사용해서 값을 넣으면 딕셔너리에 항목이 추가됩니다.

딕셔너리 값 수정하기

이미 있는 key에 새로운 값을 넣으면 기존 값이 수정됩니다.

user = {
    "name": "철수",
    "age": 20
}

user["age"] = 21

print(user)

실행 결과는 다음과 같습니다.

{'name': '철수', 'age': 21}

정리하면 다음과 같습니다.

user["city"] = "서울"  # city가 없으면 추가
user["age"] = 21      # age가 있으면 수정

딕셔너리 값 삭제하기

딕셔너리에서 값을 삭제할 때는 del을 사용할 수 있습니다.

user = {
    "name": "철수",
    "age": 20,
    "city": "서울"
}

del user["city"]

print(user)

실행 결과는 다음과 같습니다.

{'name': '철수', 'age': 20}

pop()을 사용할 수도 있습니다.

user = {
    "name": "철수",
    "age": 20,
    "city": "서울"
}

city = user.pop("city")

print(city)
print(user)

실행 결과는 다음과 같습니다.

서울
{'name': '철수', 'age': 20}

pop()은 값을 삭제하면서 삭제한 값을 반환합니다.

딕셔너리 key, value 확인하기

딕셔너리의 key만 확인하고 싶을 때는 keys()를 사용합니다.

user = {
    "name": "철수",
    "age": 20,
    "city": "서울"
}

print(user.keys())

value만 확인하고 싶을 때는 values()를 사용합니다.

print(user.values())

key와 value를 함께 확인하고 싶을 때는 items()를 사용합니다.

print(user.items())

items()는 이후 반복문을 배울 때 자주 사용합니다.

for key, value in user.items():
    print(key, value)

실행 결과는 다음과 같습니다.

name 철수
age 20
city 서울

반복문은 뒤에서 따로 다루므로, 지금은 items()가 key와 value를 함께 가져올 때 쓰인다는 정도만 이해하면 됩니다.

딕셔너리에 key가 있는지 확인하기

딕셔너리에 특정 key가 있는지 확인할 때는 in을 사용합니다.

user = {
    "name": "철수",
    "age": 20
}

print("name" in user)
print("city" in user)

실행 결과는 다음과 같습니다.

True
False

딕셔너리에서 in은 기본적으로 key를 기준으로 확인합니다.

value에 특정 값이 있는지 확인하고 싶다면 values()를 사용합니다.

print("철수" in user.values())

실행 결과는 다음과 같습니다.

True

딕셔너리를 사용할 때 좋은 경우

딕셔너리는 값에 이름을 붙여서 관리해야 할 때 유용합니다.

member = {
    "id": "user01",
    "name": "철수",
    "email": "user01@example.com"
}

상품 정보도 딕셔너리로 표현하기 좋습니다.

product = {
    "name": "노트북",
    "price": 1200000,
    "stock": 5
}

설정값을 저장할 때도 사용할 수 있습니다.

settings = {
    "theme": "dark",
    "language": "ko",
    "notification": True
}

리스트와 비교하면 차이가 더 분명해집니다.

product = ["노트북", 1200000, 5]

이렇게 쓰면 각 값이 무엇을 의미하는지 바로 알기 어렵습니다.

반면 딕셔너리는 key가 의미를 설명해줍니다.

product = {
    "name": "노트북",
    "price": 1200000,
    "stock": 5
}

그래서 여러 속성을 가진 하나의 대상을 표현할 때는 딕셔너리가 적합합니다.

집합 set은 무엇인가?

집합 set은 여러 값을 저장하는 자료형입니다.

numbers = {1, 2, 3}

집합은 중괄호 {}를 사용합니다. 다만 딕셔너리와 다르게 key와 value 쌍이 없습니다.

# 딕셔너리
user = {"name": "철수", "age": 20}

# 집합
numbers = {1, 2, 3}

딕셔너리는 콜론 :이 있습니다.

"name": "철수"

집합은 값만 나열합니다.

{1, 2, 3}

집합은 중복을 허용하지 않는다

집합 set의 가장 중요한 특징은 중복을 허용하지 않는다는 것입니다.

numbers = {1, 2, 2, 3, 3, 3}

print(numbers)

실행 결과는 다음과 비슷합니다.

{1, 2, 3}

중복된 값은 하나만 남습니다.

이 특징 때문에 집합은 중복 제거에 자주 사용됩니다.

names = ["철수", "영희", "철수", "민수", "영희"]

unique_names = set(names)

print(unique_names)

실행 결과는 다음과 비슷합니다.

{'철수', '영희', '민수'}

주의할 점은 집합은 리스트처럼 순서를 기준으로 사용하는 자료형이 아니라는 점입니다.
출력 순서는 실행 환경에 따라 다르게 보일 수 있습니다.

빈 집합 만들기

빈 집합을 만들 때는 주의해야 합니다.

empty = {}

print(type(empty))

실행 결과는 다음과 같습니다.

<class 'dict'>

{}는 빈 집합이 아니라 빈 딕셔너리입니다.

빈 집합을 만들려면 set()을 사용해야 합니다.

empty_set = set()

print(type(empty_set))

실행 결과는 다음과 같습니다.

<class 'set'>

따라서 이렇게 기억하면 됩니다.

{}      → 빈 딕셔너리
set()   → 빈 집합

집합에 값 추가하기

집합에 값을 추가할 때는 add()를 사용합니다.

numbers = {1, 2, 3}

numbers.add(4)

print(numbers)

실행 결과는 다음과 비슷합니다.

{1, 2, 3, 4}

이미 있는 값을 추가하면 중복으로 들어가지 않습니다.

numbers = {1, 2, 3}

numbers.add(2)

print(numbers)

실행 결과는 다음과 같습니다.

{1, 2, 3}

집합에서 값 삭제하기

집합에서 값을 삭제할 때는 remove()를 사용할 수 있습니다.

numbers = {1, 2, 3}

numbers.remove(2)

print(numbers)

실행 결과는 다음과 같습니다.

{1, 3}

다만 remove()는 없는 값을 삭제하려고 하면 오류가 발생합니다.

numbers.remove(4)

오류는 다음과 같습니다.

KeyError: 4

오류 없이 삭제하고 싶다면 discard()를 사용할 수 있습니다.

numbers = {1, 2, 3}

numbers.discard(4)

print(numbers)

실행 결과는 다음과 같습니다.

{1, 2, 3}

초보 단계에서는 이렇게 구분하면 됩니다.

값이 확실히 있으면 remove()
없을 수도 있으면 discard()

집합 연산 이해하기

집합은 수학의 집합처럼 사용할 수 있습니다.

python_students = {"철수", "영희", "민수"}
java_students = {"영희", "지연", "민수"}

합집합

합집합은 두 집합의 모든 값을 합친 것입니다.

result = python_students | java_students
print(result)

실행 결과는 다음과 비슷합니다.

{'철수', '영희', '민수', '지연'}

union()을 사용할 수도 있습니다.

result = python_students.union(java_students)

교집합

교집합은 두 집합에 공통으로 들어 있는 값입니다.

result = python_students & java_students
print(result)

실행 결과는 다음과 비슷합니다.

{'영희', '민수'}

intersection()을 사용할 수도 있습니다.

result = python_students.intersection(java_students)

차집합

차집합은 한쪽 집합에는 있지만 다른 집합에는 없는 값입니다.

result = python_students - java_students
print(result)

실행 결과는 다음과 같습니다.

{'철수'}

반대로 쓰면 결과가 달라집니다.

result = java_students - python_students
print(result)

실행 결과는 다음과 같습니다.

{'지연'}

차집합은 순서에 따라 결과가 달라진다는 점을 기억해야 합니다.

딕셔너리와 집합의 차이

딕셔너리와 집합은 모두 중괄호 {}를 사용하기 때문에 처음에는 헷갈릴 수 있습니다. 하지만 구조가 다릅니다.

구분	딕셔너리	집합
형태	`{key: value}`	`{value1, value2}`
목적	key로 value 관리	중복 없는 값 관리
값 접근	key 사용	특정 위치 접근 불가
중복	key 중복 불가	값 중복 불가
예시	`{"name": "철수"}`	`{"철수", "영희"}`

딕셔너리는 key와 value가 있습니다.

user = {
    "name": "철수",
    "age": 20
}

집합은 값만 있습니다.

names = {"철수", "영희", "민수"}

딕셔너리는 특정 key의 값을 꺼낼 수 있습니다.

print(user["name"])

집합은 리스트처럼 names[0]으로 값을 꺼낼 수 없습니다.

names = {"철수", "영희", "민수"}
print(names[0])

이 코드는 오류가 발생합니다.

TypeError: 'set' object is not subscriptable

집합은 순서를 기준으로 값을 다루는 자료형이 아니기 때문입니다.

딕셔너리와 리스트를 함께 사용하기

실제 코드에서는 딕셔너리와 리스트를 함께 사용하는 경우도 많습니다.

students = [
    {"name": "철수", "score": 90},
    {"name": "영희", "score": 85},
    {"name": "민수", "score": 92}
]

이 구조는 리스트 안에 딕셔너리가 들어 있는 형태입니다.

리스트는 여러 학생을 순서대로 담고 있습니다.
각 학생의 정보는 딕셔너리로 표현됩니다.

첫 번째 학생의 이름을 가져오려면 이렇게 쓸 수 있습니다.

print(students[0]["name"])

실행 결과는 다음과 같습니다.

철수

자주 발생하는 오류

없는 key를 사용할 때

딕셔너리에 없는 key를 대괄호로 가져오면 오류가 발생합니다.

user = {
    "name": "철수",
    "age": 20
}

print(user["city"])

오류는 다음과 같습니다.

KeyError: 'city'

없는 key일 수도 있다면 get()을 사용하면 됩니다.

print(user.get("city", "지역 정보 없음"))

딕셔너리와 집합을 헷갈리는 경우

다음 코드는 딕셔너리입니다.

data = {"name": "철수"}

다음 코드는 집합입니다.

data = {"철수"}

콜론 :이 있으면 딕셔너리입니다.
값만 있으면 집합입니다.

빈 집합을 {}로 만드는 경우

빈 집합을 만들고 싶어서 다음처럼 쓰면 안 됩니다.

data = {}

이 코드는 빈 딕셔너리입니다.

빈 집합은 이렇게 만듭니다.

data = set()

딕셔너리와 집합 예제 정리

딕셔너리 예제를 다시 정리해보겠습니다.

book = {
    "title": "파이썬 기초",
    "price": 15000,
    "author": "홍길동"
}

book["price"] = 18000
book["publisher"] = "테크출판"

print(book["title"])
print(book.get("publisher"))
print(book)

실행 결과는 다음과 같습니다.

파이썬 기초
테크출판
{'title': '파이썬 기초', 'price': 18000, 'author': '홍길동', 'publisher': '테크출판'}

이번에는 집합 예제입니다.

tags = ["python", "basic", "python", "list", "basic"]

unique_tags = set(tags)

print(unique_tags)

실행 결과는 다음과 비슷합니다.

{'python', 'basic', 'list'}

집합을 사용하면 중복된 값을 제거할 수 있습니다.

정리

딕셔너리와 집합은 모두 여러 값을 다룰 때 사용하는 자료형입니다.
하지만 목적이 다릅니다.

딕셔너리는 key와 value를 한 쌍으로 저장합니다.

user = {
    "name": "철수",
    "age": 20
}

key를 사용해서 값을 꺼낼 수 있습니다.

print(user["name"])

집합 set은 중복 없는 값을 저장할 때 사용합니다.

numbers = {1, 2, 2, 3}

결과적으로 중복된 값은 하나만 남습니다.

{1, 2, 3}

초보 단계에서는 이렇게 기억하면 됩니다.

딕셔너리: 이름표가 붙은 값 관리
집합 set: 중복 없는 값 관리

리스트, 튜플, 딕셔너리, 집합까지 이해하면 파이썬의 기본 자료형 흐름을 어느 정도 잡은 것입니다.

다음 글에서는 조건에 따라 코드를 실행하는 if 조건문을 알아보겠습니다.

파이썬 리스트와 튜플 차이 쉽게 이해하기

notebase — Thu, 21 May 2026 15:17:59 +0900

파이썬 리스트와 튜플은 여러 값을 하나로 묶어서 다룰 때 사용하는 자료형입니다. 둘 다 순서가 있지만, 값을 바꿀 수 있는지에 따라 쓰임이 달라집니다.

변수는 값 하나를 저장할 때 많이 사용합니다.

name = "철수"
age = 20

그런데 이름 5개를 저장해야 한다면 어떻게 해야 할까요?

name1 = "철수"
name2 = "영희"
name3 = "민수"
name4 = "지연"
name5 = "수진"

이렇게 변수 이름을 계속 늘리는 방식은 관리하기 어렵습니다.

이럴 때 사용하는 것이 리스트(list) 입니다.

names = ["철수", "영희", "민수", "지연", "수진"]

리스트를 사용하면 여러 값을 하나의 변수에 담아 관리할 수 있습니다.

리스트는 여러 값을 담는 자료형이다

리스트는 여러 값을 순서대로 저장하는 자료형입니다.

fruits = ["사과", "바나나", "딸기"]

위 코드에서 fruits라는 변수 안에는 세 개의 문자열이 들어 있습니다.

리스트 안에는 문자열뿐 아니라 숫자도 넣을 수 있습니다.

numbers = [10, 20, 30, 40]

서로 다른 자료형을 함께 넣는 것도 가능합니다.

user = ["철수", 20, True]

다만 초보 단계에서는 한 리스트 안에 같은 성격의 값을 넣는 방식이 이해하기 쉽습니다.

scores = [80, 90, 75]
names = ["철수", "영희", "민수"]

파이썬 리스트 만들기

리스트는 대괄호 []를 사용해서 만듭니다.

리스트이름 = [값1, 값2, 값3]

예시는 다음과 같습니다.

colors = ["red", "green", "blue"]

빈 리스트도 만들 수 있습니다.

items = []

빈 리스트는 나중에 값을 추가할 때 자주 사용합니다.

items = []

items.append("노트북")
items.append("마우스")

print(items)

실행 결과는 다음과 같습니다.

["노트북", "마우스"]

리스트에서 값 꺼내기: 인덱싱

리스트 안의 값은 순서가 있습니다.

fruits = ["사과", "바나나", "딸기"]

여기서 각각의 위치는 다음과 같습니다.

값	위치
사과	0
바나나	1
딸기	2

파이썬은 순서를 셀 때 0부터 시작합니다.

fruits = ["사과", "바나나", "딸기"]

print(fruits[0])
print(fruits[1])
print(fruits[2])

실행 결과는 다음과 같습니다.

사과
바나나
딸기

이처럼 리스트에서 특정 위치의 값을 가져오는 것을 인덱싱(indexing) 이라고 합니다.

음수 인덱스 사용하기

파이썬 리스트는 음수 인덱스도 사용할 수 있습니다.

fruits = ["사과", "바나나", "딸기"]

print(fruits[-1])
print(fruits[-2])

실행 결과는 다음과 같습니다.

딸기
바나나

-1은 마지막 값을 의미합니다.
-2는 뒤에서 두 번째 값을 의미합니다.

마지막 값을 가져올 때는 fruits[-1]처럼 쓰는 경우가 많습니다.

리스트 일부만 가져오기: 슬라이싱

리스트에서 일부 값만 잘라서 가져올 수도 있습니다.

이것을 슬라이싱(slicing) 이라고 합니다.

numbers = [10, 20, 30, 40, 50]

print(numbers[1:4])

실행 결과는 다음과 같습니다.

[20, 30, 40]

numbers[1:4]는 인덱스 1부터 인덱스 4 전까지 가져오라는 뜻입니다.

주의할 점은 끝 위치의 값은 포함되지 않는다는 것입니다.

numbers = [10, 20, 30, 40, 50]
# 인덱스:   0   1   2   3   4

print(numbers[1:4])

결과는 인덱스 1, 2, 3에 해당하는 값입니다.

[20, 30, 40]

처음부터 가져오고 싶다면 시작 위치를 생략할 수 있습니다.

numbers = [10, 20, 30, 40, 50]

print(numbers[:3])

실행 결과는 다음과 같습니다.

[10, 20, 30]

특정 위치부터 끝까지 가져오고 싶다면 끝 위치를 생략할 수 있습니다.

numbers = [10, 20, 30, 40, 50]

print(numbers[2:])

실행 결과는 다음과 같습니다.

[30, 40, 50]

리스트에 값 추가하기

리스트에 값을 추가할 때는 append()를 많이 사용합니다.

fruits = ["사과", "바나나"]

fruits.append("딸기")

print(fruits)

실행 결과는 다음과 같습니다.

["사과", "바나나", "딸기"]

append()는 리스트의 맨 뒤에 값을 추가합니다.

원하는 위치에 값을 넣고 싶다면 insert()를 사용할 수 있습니다.

fruits = ["사과", "딸기"]

fruits.insert(1, "바나나")

print(fruits)

실행 결과는 다음과 같습니다.

["사과", "바나나", "딸기"]

insert(1, "바나나")는 인덱스 1 위치에 "바나나"를 넣으라는 뜻입니다.

리스트 값 수정하기

리스트의 값은 나중에 바꿀 수 있습니다.

fruits = ["사과", "바나나", "딸기"]

fruits[1] = "포도"

print(fruits)

실행 결과는 다음과 같습니다.

["사과", "포도", "딸기"]

기존에 인덱스 1 위치에 있던 "바나나"가 "포도"로 바뀌었습니다.

이처럼 리스트는 변경 가능한 자료형입니다.

리스트 값 삭제하기

리스트에서 값을 삭제하는 방법은 여러 가지가 있습니다.

가장 직관적인 방법은 remove()입니다.

fruits = ["사과", "바나나", "딸기"]

fruits.remove("바나나")

print(fruits)

실행 결과는 다음과 같습니다.

["사과", "딸기"]

remove()는 리스트에서 해당 값을 찾아 삭제합니다.

인덱스를 기준으로 삭제하고 싶다면 pop()을 사용할 수 있습니다.

fruits = ["사과", "바나나", "딸기"]

fruits.pop(1)

print(fruits)

실행 결과는 다음과 같습니다.

["사과", "딸기"]

pop(1)은 인덱스 1에 있는 값을 삭제합니다.

pop()에 아무 값도 넣지 않으면 마지막 값을 삭제합니다.

fruits = ["사과", "바나나", "딸기"]

fruits.pop()

print(fruits)

실행 결과는 다음과 같습니다.

["사과", "바나나"]

리스트 길이 확인하기

리스트에 값이 몇 개 들어 있는지 확인할 때는 len()을 사용합니다.

fruits = ["사과", "바나나", "딸기"]

print(len(fruits))

실행 결과는 다음과 같습니다.

len()은 리스트뿐 아니라 문자열, 튜플 등 여러 자료형에서도 사용됩니다.

text = "Python"

print(len(text))

실행 결과는 다음과 같습니다.

리스트 안에 값이 있는지 확인하기

리스트 안에 특정 값이 있는지 확인할 때는 in을 사용합니다.

fruits = ["사과", "바나나", "딸기"]

print("사과" in fruits)
print("포도" in fruits)

실행 결과는 다음과 같습니다.

True
False

in은 조건문과 함께 자주 사용됩니다.

fruits = ["사과", "바나나", "딸기"]

if "사과" in fruits:
    print("사과가 있습니다.")

조건문은 이후 글에서 자세히 다루겠습니다.
지금은 in을 사용하면 리스트 안에 값이 있는지 확인할 수 있다는 정도만 이해하면 됩니다.

튜플은 무엇인가?

튜플(tuple)은 리스트처럼 여러 값을 순서대로 담는 자료형입니다.

다만 튜플은 소괄호 ()를 사용합니다.

point = (10, 20)

튜플도 인덱싱이 가능합니다.

point = (10, 20)

print(point[0])
print(point[1])

실행 결과는 다음과 같습니다.

10
20

튜플도 슬라이싱할 수 있습니다.

numbers = (10, 20, 30, 40, 50)

print(numbers[1:4])

실행 결과는 다음과 같습니다.

(20, 30, 40)

여기까지 보면 리스트와 거의 비슷해 보입니다.

차이는 값을 바꿀 수 있는지에서 나옵니다.

튜플은 값을 바꿀 수 없다

리스트는 값을 수정할 수 있습니다.

fruits = ["사과", "바나나", "딸기"]

fruits[0] = "포도"

print(fruits)

실행 결과는 다음과 같습니다.

["포도", "바나나", "딸기"]

하지만 튜플은 한 번 만들면 내부 값을 바꿀 수 없습니다.

fruits = ("사과", "바나나", "딸기")

fruits[0] = "포도"

이 코드는 오류가 발생합니다.

TypeError: 'tuple' object does not support item assignment

튜플은 수정하기 어려운 리스트가 아니라, 변경할 수 없는 순서형 자료형입니다.

이 차이를 정확히 이해하는 것이 중요합니다.

리스트와 튜플의 차이

리스트와 튜플의 핵심 차이는 다음과 같습니다.

구분	리스트	튜플
기호	`[]`	`()`
값 변경	가능	불가능
값 추가	가능	불가능
값 삭제	가능	불가능
순서	있음	있음
인덱싱	가능	가능
슬라이싱	가능	가능

리스트는 값을 추가, 수정, 삭제할 수 있습니다.

numbers = [1, 2, 3]

numbers.append(4)
numbers[0] = 10

print(numbers)

실행 결과는 다음과 같습니다.

[10, 2, 3, 4]

튜플은 값을 바꿀 수 없습니다.

numbers = (1, 2, 3)

이 상태에서 numbers[0] = 10처럼 수정하려고 하면 오류가 발생합니다.

리스트를 써야 하는 경우

리스트는 값이 나중에 바뀔 가능성이 있을 때 사용합니다.

예를 들어 장바구니를 생각해볼 수 있습니다.

cart = []

cart.append("노트북")
cart.append("마우스")
cart.append("키보드")

print(cart)

실행 결과는 다음과 같습니다.

["노트북", "마우스", "키보드"]

장바구니는 상품을 추가할 수도 있고, 삭제할 수도 있습니다.
이런 데이터는 리스트가 적합합니다.

학생 점수 목록도 리스트로 다루기 좋습니다.

scores = [80, 90, 75]

scores.append(100)

print(scores)

실행 결과는 다음과 같습니다.

[80, 90, 75, 100]

값이 계속 변할 수 있다면 리스트를 사용하면 됩니다.

튜플을 써야 하는 경우

튜플은 한 번 정한 값을 바꾸지 않을 때 사용합니다.

예를 들어 좌표를 생각해볼 수 있습니다.

point = (10, 20)

요일처럼 고정된 값에도 사용할 수 있습니다.

weekdays = ("월", "화", "수", "목", "금", "토", "일")

설정값처럼 바뀌면 안 되는 데이터에도 튜플을 사용할 수 있습니다.

rgb = (255, 255, 255)

튜플을 사용하면 이 데이터는 쉽게 수정되지 않는 값이라는 의도를 코드에서 드러낼 수 있습니다.

초보 단계에서는 이렇게 판단하면 됩니다.

나중에 값을 바꿀 수 있어야 한다면 리스트
한 번 정한 값을 유지하고 싶다면 튜플

값 하나짜리 튜플을 만들 때 주의할 점

튜플에서 헷갈리기 쉬운 부분이 하나 있습니다.

값이 하나만 있는 튜플을 만들 때는 쉼표가 필요합니다.

a = ("사과")
b = ("사과",)

print(type(a))
print(type(b))

실행 결과는 다음과 같습니다.

<class 'str'>
<class 'tuple'>

("사과")는 튜플이 아니라 문자열입니다.
값 하나짜리 튜플은 ("사과",)처럼 쉼표를 붙여야 합니다.

숫자도 마찬가지입니다.

a = (10)
b = (10,)

print(type(a))
print(type(b))

실행 결과는 다음과 같습니다.

<class 'int'>
<class 'tuple'>

초보자에게는 자주 필요한 문법은 아니지만, 튜플을 공부할 때 한 번은 알아두는 것이 좋습니다.

리스트와 문자열은 닮은 점이 있다

이전 글에서 문자열을 다뤘다면 리스트가 조금 더 쉽게 느껴질 수 있습니다.

문자열도 인덱싱할 수 있습니다.

text = "Python"

print(text[0])
print(text[1])

실행 결과는 다음과 같습니다.

P
y

문자열도 슬라이싱할 수 있습니다.

text = "Python"

print(text[0:3])

실행 결과는 다음과 같습니다.

Pyt

리스트도 마찬가지입니다.

items = ["P", "y", "t", "h", "o", "n"]

print(items[0])
print(items[0:3])

실행 결과는 다음과 같습니다.

P
['P', 'y', 't']

문자열과 리스트는 둘 다 순서가 있는 자료형입니다.
그래서 인덱싱과 슬라이싱 방식이 비슷합니다.

다만 문자열은 문자들이 이어진 자료형이고, 리스트는 여러 값을 담을 수 있는 자료형입니다.

자주 발생하는 오류

인덱스 범위를 벗어나는 경우

리스트에 없는 위치를 가져오려고 하면 오류가 발생합니다.

fruits = ["사과", "바나나", "딸기"]

print(fruits[3])

이 코드는 오류가 발생합니다.

IndexError: list index out of range

리스트의 마지막 인덱스는 값의 개수보다 1 작습니다.

fruits = ["사과", "바나나", "딸기"]

위 리스트에는 값이 3개 있습니다.

하지만 인덱스는 다음과 같습니다.

0, 1, 2

따라서 fruits[3]은 존재하지 않습니다.

remove()로 없는 값을 삭제하려는 경우

remove()는 리스트 안에 있는 값을 삭제합니다.
그런데 없는 값을 삭제하려고 하면 오류가 발생합니다.

fruits = ["사과", "바나나", "딸기"]

fruits.remove("포도")

오류는 다음과 같습니다.

ValueError: list.remove(x): x not in list

삭제하기 전에 값이 있는지 확인하면 오류를 줄일 수 있습니다.

fruits = ["사과", "바나나", "딸기"]

if "포도" in fruits:
    fruits.remove("포도")

아직 조건문을 자세히 배우지 않았다면 이런 방식이 있다는 정도만 봐도 충분합니다.

리스트와 튜플 예제 정리

간단한 예제로 다시 정리해보겠습니다.

fruits = ["사과", "바나나", "딸기"]

fruits.append("포도")
fruits[1] = "수박"
fruits.remove("딸기")

print(fruits)

실행 결과는 다음과 같습니다.

["사과", "수박", "포도"]

리스트는 값을 추가하고, 수정하고, 삭제할 수 있습니다.

이번에는 튜플입니다.

colors = ("red", "green", "blue")

print(colors[0])
print(colors[1:3])

실행 결과는 다음과 같습니다.

red
('green', 'blue')

튜플은 인덱싱과 슬라이싱은 가능하지만, 값을 직접 수정할 수는 없습니다.

정리

리스트와 튜플은 여러 값을 하나로 묶어서 다룰 때 사용하는 자료형입니다.

리스트는 대괄호 []를 사용합니다.

fruits = ["사과", "바나나", "딸기"]

튜플은 소괄호 ()를 사용합니다.

fruits = ("사과", "바나나", "딸기")

두 자료형 모두 순서가 있습니다.
그래서 인덱싱과 슬라이싱을 사용할 수 있습니다.

차이는 값을 바꿀 수 있는지입니다.

리스트는 값을 추가, 수정, 삭제할 수 있습니다.
튜플은 한 번 만들면 내부 값을 바꿀 수 없습니다.

초보 단계에서는 이렇게 기억하면 됩니다.

리스트: 나중에 바뀔 수 있는 값들의 묶음
튜플: 바뀌지 않아야 하는 값들의 묶음

다음 글에서는 이름과 값이 짝을 이루는 자료형인 딕셔너리(dictionary) 와, 중복을 제거할 때 자주 사용하는 집합(set) 을 알아보겠습니다.

파이썬 문자열 사용법: 초보자가 자주 헷갈리는 예제 중심 정리

notebase — Thu, 21 May 2026 10:13:56 +0900

파이썬 문자열은 글자, 단어, 문장을 다룰 때 사용하는 기본 자료형입니다. 이름, 이메일, 주소, 메시지, 파일명처럼 문자로 된 데이터는 대부분 문자열로 처리합니다.

처음에는 단순히 따옴표 안에 글자를 넣으면 된다고 생각하기 쉽습니다.

하지만 실제로 코드를 작성하다 보면 문자열을 합치거나, 일부만 자르거나, 변수와 함께 출력해야 하는 일이 많습니다.

이 글에서는 파이썬 문자열을 처음 배우는 사람도 이해할 수 있도록 기본 사용법을 예제 중심으로 정리합니다.

파이썬 문자열이란?

문자열은 문자들이 순서대로 이어진 데이터입니다.

파이썬에서는 문자열을 str 타입이라고 부릅니다.

name = "Python"
message = "Hello"

위 코드에서 "Python"과 "Hello"는 문자열입니다.

문자열은 반드시 따옴표로 감싸야 합니다.
따옴표 없이 쓰면 파이썬은 그것을 문자열이 아니라 변수 이름으로 해석합니다.

text = Hello

이 코드는 오류가 납니다.

Hello라는 문자열을 저장하려면 아래처럼 작성해야 합니다.

text = "Hello"

문자열을 만드는 방법

파이썬에서는 문자열을 만들 때 작은따옴표 또는 큰따옴표를 사용할 수 있습니다.

text1 = 'Hello'
text2 = "Hello"

둘 다 문자열입니다.

일반적으로 둘 중 하나만 골라 일관되게 쓰면 됩니다.
다만 문자열 안에 따옴표가 들어갈 때는 상황에 따라 선택하면 편합니다.

sentence = "I'm learning Python"

위 예제에서는 문자열 안에 작은따옴표가 들어가므로 바깥쪽을 큰따옴표로 감쌌습니다.

반대로 문자열 안에 큰따옴표가 들어가면 바깥쪽을 작은따옴표로 감쌀 수 있습니다.

sentence = 'He said "Hello"'

이렇게 하면 따옴표 때문에 생기는 오류를 줄일 수 있습니다.

여러 줄 문자열 만들기

문장이 길거나 여러 줄로 된 문자열을 만들 때는 따옴표 3개를 사용할 수 있습니다.

text = """안녕하세요.
파이썬 문자열을 배우고 있습니다.
여러 줄 문장도 저장할 수 있습니다."""

작은따옴표 3개도 사용할 수 있습니다.

text = '''첫 번째 줄
두 번째 줄
세 번째 줄'''

여러 줄 안내문, 설명문, 긴 메시지를 변수에 저장할 때 사용할 수 있습니다.

문자열 출력하기

문자열은 print() 함수로 출력할 수 있습니다.

print("Hello Python")

결과는 다음과 같습니다.

Hello Python

변수에 저장한 문자열도 출력할 수 있습니다.

name = "Python"
print(name)

결과:

Python

문자열과 변수를 함께 출력할 수도 있습니다.

name = "민수"
print("안녕하세요", name)

결과:

안녕하세요 민수

,를 사용하면 값 사이에 공백이 자동으로 들어갑니다.

문자열 합치기

문자열끼리는 + 연산자로 합칠 수 있습니다.

first = "Hello"
second = "Python"

result = first + second
print(result)

결과:

HelloPython

두 문자열이 그대로 붙어서 출력됩니다.
중간에 공백을 넣고 싶다면 공백 문자열을 함께 더해야 합니다.

result = first + " " + second
print(result)

결과:

Hello Python

문자열 합치기는 이름, 문장, 파일명 등을 만들 때 자주 사용합니다.

first_name = "Kim"
last_name = "Gwanghee"

full_name = first_name + " " + last_name
print(full_name)

결과:

Kim Gwanghee

문자열과 숫자는 바로 더할 수 없다

초보자가 자주 만나는 오류 중 하나입니다.

age = 20
print("나이: " + age)

이 코드는 오류가 납니다.

문자열과 숫자는 자료형이 다르기 때문입니다.
문자열과 숫자를 +로 합치려면 숫자를 문자열로 바꿔야 합니다.

age = 20
print("나이: " + str(age))

결과:

나이: 20

str()은 값을 문자열로 바꿔주는 함수입니다.

하지만 실제로는 뒤에서 설명할 f-string을 쓰는 편이 더 깔끔합니다.

문자열 반복하기

문자열은 * 연산자로 반복할 수 있습니다.

text = "Hi"
print(text * 3)

결과:

HiHiHi

구분선을 만들 때도 사용할 수 있습니다.

print("-" * 20)

결과:

--------------------

간단한 출력 형식을 만들 때 유용합니다.

문자열 인덱싱

문자열은 글자들이 순서대로 들어 있는 자료형입니다.
그래서 각 글자에는 위치 번호가 있습니다.

이 위치 번호를 인덱스라고 합니다.

파이썬의 인덱스는 0부터 시작합니다.

word = "Python"

각 글자의 위치는 다음과 같습니다.

문자	P	y	t	h	o	n
인덱스	0	1	2	3	4	5

첫 번째 글자를 가져오려면 이렇게 씁니다.

word = "Python"
print(word[0])

결과:

세 번째 글자는 인덱스 2입니다.

print(word[2])

결과:

처음 배울 때 가장 헷갈리는 부분은 “첫 번째 글자 = 0번”이라는 점입니다.

음수 인덱스

파이썬은 뒤에서부터 글자를 가져올 수도 있습니다.

word = "Python"
print(word[-1])

결과:

-1은 마지막 글자를 의미합니다.

print(word[-2])

결과:

뒤에서부터 접근할 때는 -1, -2, -3처럼 사용합니다.

문자	P	y	t	h	o	n
음수 인덱스	-6	-5	-4	-3	-2	-1

마지막 글자를 가져올 때는 음수 인덱스가 편합니다.

문자열 슬라이싱

슬라이싱은 문자열의 일부를 잘라내는 방법입니다.

기본 형태는 다음과 같습니다.

문자열[시작:끝]

주의할 점은 끝 위치의 글자는 포함되지 않는다는 것입니다.

word = "Python"
print(word[0:2])

결과:

Py

0번부터 시작해서 2번 앞까지 가져옵니다.
즉, 인덱스 0과 1에 해당하는 "Py"만 가져옵니다.

시작 위치 생략하기

처음부터 자르고 싶다면 시작 위치를 생략할 수 있습니다.

word = "Python"
print(word[:3])

결과:

Pyt

처음부터 인덱스 3 앞까지 가져옵니다.

끝 위치 생략하기

특정 위치부터 끝까지 가져오고 싶다면 끝 위치를 생략합니다.

word = "Python"
print(word[3:])

결과:

hon

인덱스 3부터 마지막까지 가져옵니다.

전체 문자열 복사하기

시작과 끝을 모두 생략하면 전체 문자열을 가져옵니다.

word = "Python"
print(word[:])

결과:

Python

실무에서 자주 쓰는 패턴은 아니지만, 슬라이싱 구조를 이해하는 데 도움이 됩니다.

문자열 안에 변수 넣기

문자열 안에 변수 값을 넣는 방법은 여러 가지가 있습니다.
초보자에게는 f-string 방식이 가장 이해하기 쉽습니다.

name = "민수"
age = 20

print(f"이름은 {name}이고, 나이는 {age}살입니다.")

결과:

이름은 민수이고, 나이는 20살입니다.

문자열 앞에 f를 붙이고, 변수는 {} 안에 넣습니다.

이 방식은 문자열과 숫자를 함께 출력할 때도 편합니다.

price = 15000
count = 2

print(f"가격은 {price}원이고, 수량은 {count}개입니다.")

결과:

가격은 15000원이고, 수량은 2개입니다.

+로 문자열을 계속 합치는 것보다 읽기 쉽습니다.

f-string 안에서 계산하기

f-string 안에서는 간단한 계산도 할 수 있습니다.

price = 15000
count = 2

print(f"총 금액은 {price * count}원입니다.")

결과:

총 금액은 30000원입니다.

변수 값을 문장에 자연스럽게 넣어야 할 때 많이 사용합니다.

자주 쓰는 문자열 메서드

문자열에는 자주 사용하는 기능들이 미리 준비되어 있습니다.
이런 기능을 메서드라고 합니다.

형태는 보통 다음과 같습니다.

문자열.메서드()

입문 단계에서 자주 쓰는 문자열 메서드를 몇 가지 살펴보겠습니다.

대문자와 소문자 바꾸기

text = "Python"

print(text.upper())
print(text.lower())

결과:

PYTHON
python

upper()는 대문자로 바꿉니다.
lower()는 소문자로 바꿉니다.

영문 검색, 비교, 정리 작업에서 자주 사용합니다.

공백 제거하기

사용자가 입력한 값에는 앞뒤 공백이 들어갈 수 있습니다.

text = "  Python  "
print(text.strip())

결과:

Python

strip()은 문자열 양쪽의 불필요한 공백을 제거합니다.

회원가입, 검색어 입력, 파일 처리처럼 사용자 입력을 다룰 때 자주 사용됩니다.

문자열 바꾸기

문자열 안의 특정 부분을 다른 문자열로 바꿀 수 있습니다.

text = "I like Java"
print(text.replace("Java", "Python"))

결과:

I like Python

replace()는 첫 번째 값으로 찾을 문자열을 받고, 두 번째 값으로 바꿀 문자열을 받습니다.

문자열 나누기

문자열을 특정 기준으로 나눌 때는 split()을 사용합니다.

text = "apple,banana,orange"
fruits = text.split(",")

print(fruits)

결과:

['apple', 'banana', 'orange']

,를 기준으로 문자열이 나뉘고, 결과는 리스트로 만들어집니다.

아직 리스트를 배우지 않았다면 “여러 값을 담는 자료형으로 바뀐다” 정도로 이해하면 됩니다.

문자열 길이 구하기

문자열의 길이는 len() 함수로 구합니다.

text = "Python"
print(len(text))

결과:

문자열에 글자가 몇 개 들어 있는지 확인할 때 사용합니다.

한글도 글자 수 기준으로 계산할 수 있습니다.

text = "파이썬"
print(len(text))

결과:

특정 문자열이 포함되어 있는지 확인하기

문자열 안에 특정 글자나 단어가 들어 있는지 확인할 때는 in을 사용합니다.

text = "I am learning Python"

print("Python" in text)

결과:

True

포함되어 있지 않으면 False가 나옵니다.

print("Java" in text)

결과:

False

검색 기능, 필터링, 조건문에서 자주 사용됩니다.

초보자가 자주 하는 실수

1. 따옴표를 빼먹는 경우

text = Hello

이 코드는 오류가 납니다.

문자열은 반드시 따옴표로 감싸야 합니다.

text = "Hello"

2. 문자열과 숫자를 바로 더하는 경우

age = 20
print("나이: " + age)

문자열과 숫자는 바로 더할 수 없습니다.

아래처럼 바꿔야 합니다.

age = 20
print("나이: " + str(age))

또는 f-string을 사용하는 것이 더 좋습니다.

age = 20
print(f"나이: {age}")

3. 인덱스가 1부터 시작한다고 생각하는 경우

word = "Python"
print(word[1])

이 코드는 첫 번째 글자인 P가 아니라 두 번째 글자인 y를 출력합니다.

파이썬 인덱스는 0부터 시작합니다.

첫 번째 글자는 아래처럼 가져옵니다.

print(word[0])

4. 슬라이싱의 끝 위치가 포함된다고 생각하는 경우

word = "Python"
print(word[0:3])

결과는 다음과 같습니다.

Pyt

인덱스 0, 1, 2까지만 포함됩니다.
끝 위치인 3은 포함되지 않습니다.

슬라이싱은 처음에는 헷갈리지만, 아래처럼 기억하면 편합니다.

[시작 위치 : 끝나기 직전 위치]

문자열은 직접 수정할 수 없다

파이썬 문자열은 한 번 만들어지면 내부 글자를 직접 바꿀 수 없습니다.

예를 들어 아래 코드는 오류가 납니다.

word = "Python"
word[0] = "J"

문자열의 일부를 바꾸고 싶다면 새 문자열을 만들어야 합니다.

word = "Python"
new_word = "J" + word[1:]

print(new_word)

결과:

Jython

또는 replace()를 사용할 수도 있습니다.

word = "Python"
new_word = word.replace("P", "J")

print(new_word)

결과:

Jython

문자열은 수정하는 것이 아니라, 바뀐 결과를 새로 만든다고 이해하면 됩니다.

간단한 예제로 정리하기

아래 코드는 문자열에서 자주 쓰는 기능을 한 번에 보여줍니다.

name = "kim"
language = "Python"

print(f"{name.upper()}님은 {language}을 배우고 있습니다.")
print(language[0])
print(language[:3])
print(len(language))
print("Py" in language)

결과:

KIM님은 Python을 배우고 있습니다.
P
Pyt
6
True

이 예제 안에는 다음 개념이 들어 있습니다.

upper()로 대문자 변환
f-string으로 변수 넣기
인덱싱으로 첫 글자 가져오기
슬라이싱으로 일부 문자열 가져오기
len()으로 길이 구하기
in으로 포함 여부 확인하기

문자열 기초를 익힐 때는 이런 짧은 예제를 직접 실행해보는 것이 좋습니다.

마무리

파이썬 문자열은 단순히 글자를 저장하는 기능만 있는 것이 아닙니다.

문자열을 합치고, 자르고, 바꾸고, 검색하고, 변수와 함께 출력하는 작업은 거의 모든 파이썬 코드에서 사용됩니다.

처음에는 특히 아래 개념을 확실히 익히는 것이 좋습니다.

문자열 만들기
문자열 합치기
인덱싱
슬라이싱
f-string
자주 쓰는 문자열 메서드

문자열이 익숙해지면 리스트, 조건문, 반복문을 배울 때도 훨씬 수월해집니다.

파이썬 변수와 자료형 쉽게 이해하기: 초보자를 위한 Python 기초

notebase — Wed, 20 May 2026 09:31:02 +0900

파이썬 변수와 자료형이 헷갈리나요? Python 3.14.5 공식 문서 흐름에 맞춰 변수, int, float, str, bool, None, list, dict, type() 사용법까지 초보자 기준으로 정리했습니다.

파이썬 변수와 자료형은 Python을 처음 배울 때 가장 먼저 만나는 개념입니다.
그런데 생각보다 많은 초보자가 여기서 헷갈립니다.

name = "Python" 같은 코드는 짧아 보입니다.
하지만 이 한 줄 안에는 변수, 값, 자료형, 대입이라는 중요한 개념이 모두 들어 있습니다.

이번 글에서는 2026년 5월 기준 Python 3.14.5 공식 문서 흐름에 맞춰, 파이썬 변수와 자료형을 초보자 기준으로 정리해보겠습니다.
전공자식 설명보다 “실제로 코드를 읽을 때 어떻게 이해하면 되는지”에 초점을 맞췄습니다.

이 글에서 다루는 내용

파이썬 변수란 무엇인지
변수는 왜 “상자”보다 “이름표”에 가까운지
자료형이 필요한 이유
int, float, str, bool, None 이해하기
list, tuple, dict, set 차이
type() 함수로 자료형 확인하는 방법
초보자가 자주 하는 실수
직접 풀어볼 수 있는 연습문제

변수는 값을 담는 상자일까?

처음 코딩을 배울 때 변수는 보통 “값을 담는 상자”라고 설명합니다.

예를 들어 아래 코드를 보겠습니다.

name = "Python"
age = 35

이 코드를 처음 보면 이렇게 이해하기 쉽습니다.

name이라는 상자에 "Python"을 넣었다.
age라는 상자에 35를 넣었다.

입문 단계에서는 이 설명도 도움이 됩니다.
하지만 파이썬을 조금 더 정확하게 이해하려면 이렇게 보는 편이 낫습니다.

name이라는 이름이 "Python"이라는 값을 가리킨다.
age라는 이름이 35라는 값을 가리킨다.

파이썬에서 변수는 값에 붙이는 이름표에 가깝습니다.

공식 문서에서도 파이썬의 모든 데이터는 객체로 표현된다고 설명합니다. 객체는 각각 정체성(identity), 자료형(type), 값(value)을 가집니다. 초보자 입장에서는 이 말을 전부 외울 필요는 없습니다. 우선은 “변수 이름이 값 객체를 가리킨다” 정도로 이해하면 충분합니다.

변수 만들기: 대입 연산자 `=`

파이썬에서 변수는 보통 = 기호로 만듭니다.

score = 90

여기서 =는 수학의 “같다”와 완전히 같은 의미가 아닙니다.
코딩에서는 보통 오른쪽 값을 왼쪽 이름에 연결한다는 뜻입니다.

score = 90

이 코드는 이렇게 읽으면 됩니다.

90이라는 값을 score라는 이름으로 부르겠다.

그래서 아래 코드도 가능합니다.

score = 90
score = 95

print(score)

실행 결과는 다음과 같습니다.

처음에는 score가 90을 가리켰지만, 다음 줄에서 95를 가리키도록 다시 연결했기 때문입니다.
이것을 재대입이라고 볼 수 있습니다.

변수 이름을 지을 때 기본 규칙

변수 이름은 아무렇게나 지으면 안 됩니다.
초보자는 아래 정도만 기억해도 충분합니다.

규칙	예시
숫자로 시작할 수 없음	`1name`은 안 됨
공백을 넣을 수 없음	`user name`은 안 됨
대소문자를 구분함	`age`와 `Age`는 다름
예약어는 피해야 함	`if`, `for`, `class` 같은 단어는 안 됨
의미 있는 이름이 좋음	`a`보다 `user_age`가 읽기 쉬움

예를 들어 이런 변수 이름은 좋습니다.

user_name = "민수"
user_age = 25
is_student = True

반대로 이런 이름은 피하는 것이 좋습니다.

a = "민수"
b = 25
c = True

코드가 짧을 때는 괜찮아 보이지만, 줄이 길어지면 a, b, c가 무엇을 뜻하는지 금방 헷갈립니다.

파이썬에서는 한글 변수명도 동작할 수 있습니다.

이름 = "민수"
나이 = 25

다만 처음 공부할 때는 영어 변수명에 익숙해지는 편이 좋습니다.
예제, 문서, 오류 메시지, 협업 코드가 대부분 영어 기준으로 작성되기 때문입니다.

자료형이란 무엇일까?

자료형은 쉽게 말해 값의 종류입니다.

아래 값을 비교해보겠습니다.

age = 25
name = "민수"
is_student = True

겉보기에는 모두 변수입니다.
하지만 값 객체의 종류는 다릅니다.

이름	값	값의 자료형
`age`	`25`	정수
`name`	`"민수"`	문자열
`is_student`	`True`	불리언

자료형이 중요한 이유는 간단합니다.
값의 자료형에 따라 할 수 있는 일이 달라지기 때문입니다.

예를 들어 숫자는 계산할 수 있습니다.

price = 10000
discount = 2000

print(price - discount)

실행 결과는 다음과 같습니다.

문자열은 글자를 이어붙일 수 있습니다.

first_name = "김"
last_name = "민수"

print(first_name + last_name)

실행 결과는 다음과 같습니다.

김민수

하지만 숫자와 문자열을 그대로 더하려고 하면 오류가 납니다.

age = 25

print("나이: " + age)

이 코드는 오류가 납니다.
"나이: "는 문자열이고, age가 가리키는 25는 정수 객체이기 때문입니다.

해결하려면 숫자를 문자열로 바꿔야 합니다.

age = 25

print("나이: " + str(age))

실행 결과는 다음과 같습니다.

나이: 25

`type()` 함수로 자료형 확인하기

자료형이 헷갈릴 때는 type() 함수를 쓰면 됩니다.

name = "Python"
age = 35
height = 175.5
is_easy = True

print(type(name))
print(type(age))
print(type(height))
print(type(is_easy))

실행 결과는 다음과 비슷합니다.

<class 'str'>
<class 'int'>
<class 'float'>
<class 'bool'>

처음에는 <class 'str'> 같은 표현이 낯설 수 있습니다.
간단히 이렇게 이해하면 됩니다.

출력	뜻
`<class 'str'>`	문자열
`<class 'int'>`	정수
`<class 'float'>`	실수
`<class 'bool'>`	참/거짓

type()은 초보자가 오류를 찾을 때도 매우 유용합니다.

예를 들어 아래 코드를 보겠습니다.

price = "10000"
delivery_fee = 3000

print(price + delivery_fee)

이 코드는 오류가 납니다.
겉으로 보기에는 10000이 숫자처럼 보이지만, 따옴표 안에 있기 때문에 문자열입니다.

확인해보면 바로 알 수 있습니다.

price = "10000"

print(type(price))

실행 결과는 다음과 같습니다.

<class 'str'>

파이썬 기본 값·자료형 한눈에 보기

처음부터 모든 자료형을 외울 필요는 없습니다.
입문 단계에서는 아래 자료형과 값을 먼저 이해하면 됩니다.

값/자료형	뜻	예시
`int`	정수	`10`, `-3`, `0`
`float`	실수	`3.14`, `0.5`
`str`	문자열	`"Python"`, `"안녕"`
`bool`	참/거짓	`True`, `False`
`None`	값의 부재를 나타내는 특별한 값	`None`
`list`	수정 가능한 순서형 자료	`[1, 2, 3]`
`tuple`	수정 불가능한 순서형 자료	`(1, 2, 3)`
`dict`	키와 값의 매핑	`{"name": "민수"}`
`set`	중복 없는 집합	`{1, 2, 3}`

공식 문서에서는 숫자형, 시퀀스형, 매핑형 같은 큰 분류로 자료형을 설명합니다. 초보자라면 처음부터 분류명을 외우기보다, 위 표의 예시를 직접 실행해보는 것이 더 좋습니다.

숫자 자료형: `int`와 `float`

파이썬에서 숫자는 크게 정수와 실수로 나눠서 이해하면 됩니다.

`int`: 정수

int는 소수점이 없는 숫자입니다.

age = 25
count = 3
temperature = -5

print(type(age))

실행 결과는 다음과 같습니다.

<class 'int'>

int는 더하기, 빼기, 곱하기, 나누기 같은 계산에 사용할 수 있습니다.

a = 10
b = 3

print(a + b)
print(a - b)
print(a * b)
print(a / b)

실행 결과는 다음과 같습니다.

13
7
30
3.3333333333333335

나누기 결과는 소수점이 포함될 수 있기 때문에 float로 나옵니다.

`float`: 실수

float는 소수점이 있는 숫자입니다.

height = 175.5
weight = 68.2

print(type(height))

실행 결과는 다음과 같습니다.

<class 'float'>

float를 쓸 때 초보자가 자주 놀라는 예시가 있습니다.

print(0.1 + 0.2)

실행 결과는 보통 다음처럼 나옵니다.

0.30000000000000004

왜 0.3이 아니냐고 느낄 수 있습니다.
이건 파이썬만의 문제가 아니라 컴퓨터가 소수를 이진수로 표현하는 방식 때문에 생기는 현상입니다.

입문 단계에서는 이렇게 기억하면 됩니다.

돈 계산처럼 정확한 소수 계산이 필요한 경우에는 float만 믿으면 안 된다.

처음에는 이 정도만 알아도 충분합니다.
나중에 돈 계산이나 정밀 계산을 다룰 때 Decimal 같은 도구를 따로 배우면 됩니다.

문자열 자료형: `str`

str은 문자열입니다.
문자열은 글자, 단어, 문장을 다룰 때 사용합니다.

name = "민수"
language = "Python"
message = "안녕하세요"

문자열은 작은따옴표와 큰따옴표를 모두 사용할 수 있습니다.

text1 = 'Python'
text2 = "Python"

둘 다 문자열입니다.
중요한 것은 따옴표 안에 들어가면 숫자처럼 보여도 문자열이 된다는 점입니다.

number1 = 100
number2 = "100"

print(type(number1))
print(type(number2))

실행 결과는 다음과 같습니다.

<class 'int'>
<class 'str'>

number1은 숫자입니다.
number2는 문자열입니다.

문자열은 더하기로 이어붙일 수 있습니다.

greeting = "안녕하세요"
name = "민수"

print(greeting + ", " + name + "님")

실행 결과는 다음과 같습니다.

안녕하세요, 민수님

다만 실무에서는 문자열을 이어붙일 때 f-string을 자주 씁니다.

name = "민수"
age = 25

print(f"{name}님의 나이는 {age}살입니다.")

실행 결과는 다음과 같습니다.

민수님의 나이는 25살입니다.

초보자라면 문자열 더하기보다 f-string 방식에 빨리 익숙해지는 것이 좋습니다.
숫자와 문자열을 섞어 출력할 때 훨씬 편합니다.

참과 거짓: `bool`

bool은 참과 거짓을 나타내는 자료형입니다.

is_student = True
is_adult = False

print(type(is_student))

실행 결과는 다음과 같습니다.

<class 'bool'>

주의할 점은 True와 False의 첫 글자가 대문자라는 것입니다.

is_done = True

아래처럼 쓰면 안 됩니다.

is_done = true

true는 파이썬에서 참값으로 인식되지 않습니다.

bool은 조건문에서 자주 사용합니다.

is_logged_in = True

if is_logged_in:
    print("환영합니다.")
else:
    print("로그인이 필요합니다.")

실행 결과는 다음과 같습니다.

환영합니다.

파이썬에서는 0, 빈 문자열, 빈 리스트 같은 값이 조건문에서 거짓처럼 취급될 수 있습니다.

name = ""

if name:
    print("이름이 있습니다.")
else:
    print("이름이 비어 있습니다.")

실행 결과는 다음과 같습니다.

이름이 비어 있습니다.

이 개념은 나중에 조건문을 배울 때 자주 나옵니다.
지금은 “비어 있으면 거짓처럼 볼 수 있다” 정도만 기억하면 됩니다.

값이 없음을 나타내는 `None`

None은 “값이 없다” 또는 “아직 값이 정해지지 않았다”는 뜻으로 자주 쓰이는 특별한 값입니다.

result = None

print(type(result))

실행 결과는 다음과 같습니다.

<class 'NoneType'>

여기서 중요한 점이 있습니다.

None은 값입니다.
NoneType은 None의 타입입니다.

즉, None은 값의 부재를 나타내는 특별한 객체이고, type(None)을 실행하면 <class 'NoneType'>이 출력됩니다.

None은 0이나 빈 문자열과 다릅니다.

값	의미
`0`	숫자 0
`""`	비어 있는 문자열
`None`	값이 아직 없음을 나타내는 특별한 값

예를 들어 아직 사용자의 이메일을 입력받지 않았다면 이렇게 둘 수 있습니다.

email = None

나중에 이메일이 생기면 다시 값을 넣을 수 있습니다.

email = "user@example.com"

초보자는 None을 “아직 정해지지 않은 값” 정도로 이해하면 됩니다.

여러 값을 담는 `list`

list는 여러 값을 순서대로 담을 때 사용합니다.

fruits = ["apple", "banana", "orange"]

print(fruits)

실행 결과는 다음과 같습니다.

['apple', 'banana', 'orange']

리스트는 순서가 있기 때문에 위치 번호로 값을 꺼낼 수 있습니다.
파이썬의 위치 번호는 0부터 시작합니다.

fruits = ["apple", "banana", "orange"]

print(fruits[0])
print(fruits[1])

실행 결과는 다음과 같습니다.

apple
banana

리스트는 값을 추가하거나 바꿀 수 있습니다.

fruits = ["apple", "banana"]

fruits.append("orange")
fruits[0] = "grape"

print(fruits)

실행 결과는 다음과 같습니다.

['grape', 'banana', 'orange']

이처럼 값을 바꿀 수 있는 성질을 mutable, 즉 수정 가능하다고 표현합니다.

수정 불가능한 순서형 자료: `tuple`

tuple은 리스트처럼 여러 값을 순서대로 담을 수 있지만, 한 번 만든 뒤에는 안의 항목을 바꿀 수 없는 자료형입니다.

point = (10, 20)

print(point[0])
print(point[1])

실행 결과는 다음과 같습니다.

10
20

튜플은 보통 바뀌면 안 되는 묶음을 표현할 때 사용합니다.

예를 들어 좌표처럼 두 값이 함께 움직이는 경우입니다.

location = (37.5665, 126.9780)

리스트와 튜플 차이는 이렇게 정리할 수 있습니다.

자료형	특징
`list`	순서가 있고, 값을 추가하거나 바꿀 수 있음
`tuple`	순서가 있지만, 한 번 만든 뒤 항목을 바꿀 수 없음

초보 단계에서는 list를 더 자주 쓰게 됩니다.
튜플은 “수정 불가능한 순서형 자료”라고 기억하면 됩니다.

키와 값으로 저장하는 `dict`

dict는 키와 값을 묶어서 저장하는 자료형입니다.
딕셔너리라고 읽습니다.

user = {
    "name": "민수",
    "age": 25,
    "is_student": True
}

이 구조는 실제 데이터와 비슷합니다.

이름: 민수
나이: 25
학생 여부: True

딕셔너리에서 값을 꺼낼 때는 키를 사용합니다.

user = {
    "name": "민수",
    "age": 25
}

print(user["name"])
print(user["age"])

실행 결과는 다음과 같습니다.

민수
25

딕셔너리는 API 응답, 설정값, 사용자 정보, 상품 정보 같은 데이터를 다룰 때 자주 사용합니다.

예를 들어 블로그 글 정보를 표현하면 이렇게 쓸 수 있습니다.

post = {
    "title": "파이썬 변수와 자료형",
    "category": "Python",
    "views": 120
}

초보자가 dict를 어렵게 느끼는 이유는 대괄호와 중괄호가 섞여 나오기 때문입니다.

list: []
dict: {}

이 차이만 먼저 기억해도 충분합니다.

중복을 제거하는 `set`

set은 중복 없는 값을 모을 때 사용합니다.

numbers = {1, 2, 2, 3, 3, 3}

print(numbers)

실행 결과는 다음과 비슷합니다.

{1, 2, 3}

중복된 값이 하나로 정리됩니다.

예를 들어 방문자가 검색한 키워드 목록에서 중복을 제거하고 싶다면 이런 식으로 생각할 수 있습니다.

keywords = ["Python", "ChatGPT", "Python", "Docker"]

unique_keywords = set(keywords)

print(unique_keywords)

결과는 순서가 다르게 보일 수 있습니다.

{'Docker', 'Python', 'ChatGPT'}

set은 중복 제거에는 편하지만, 순서를 중요하게 다루는 자료형은 아닙니다.
처음에는 “중복 없는 집합” 정도로 이해하면 됩니다.

list와 dict는 특히 중요하다

입문 단계에서 가장 중요한 자료형을 고르라면 list와 dict입니다.

Python으로 자동화, 데이터 정리, API 사용을 하다 보면 이 둘을 자주 만나게 됩니다.

예를 들어 여러 명의 사용자 정보를 저장한다고 해보겠습니다.

users = [
    {"name": "민수", "age": 25},
    {"name": "지은", "age": 30},
    {"name": "현우", "age": 28}
]

겉보기에는 복잡해 보이지만 구조를 나눠보면 어렵지 않습니다.

users는 리스트다.
리스트 안에는 딕셔너리가 들어 있다.
각 딕셔너리는 한 사람의 정보를 나타낸다.

값을 하나 꺼내보겠습니다.

print(users[0]["name"])

실행 결과는 다음과 같습니다.

민수

해석 순서는 이렇습니다.

users[0]          → 첫 번째 사람 정보
users[0]["name"]  → 첫 번째 사람의 name 값

이 구조는 나중에 웹 데이터, JSON, API 응답을 다룰 때 자주 나옵니다.
따라서 Python을 계속 공부할 생각이라면 list와 dict는 꼭 익숙해져야 합니다.

수정 가능한 자료형과 수정 불가능한 자료형

파이썬 자료형을 배울 때 중요한 기준이 하나 더 있습니다.

객체의 내용을 바꿀 수 있는가?

이 기준으로 자료형을 나누면 다음과 같습니다.

구분	자료형 예시	설명
수정 불가능	`int`, `float`, `str`, `tuple`	객체 자체를 바꾸기보다 새 객체에 이름을 다시 연결
수정 가능	`list`, `dict`, `set`	객체 안에 들어 있는 항목을 바꿀 수 있음

예를 들어 문자열은 수정 불가능한 자료형입니다.

text = "Python"
text = "Python Study"

이 코드는 문자열 자체를 고친다기보다, text라는 이름을 새 문자열 객체에 다시 연결하는 방식으로 이해하는 편이 좋습니다.

반면 리스트는 내부 값을 바꿀 수 있습니다.

numbers = [1, 2, 3]
numbers[0] = 100

print(numbers)

실행 결과는 다음과 같습니다.

[100, 2, 3]

이 차이는 나중에 매우 중요해집니다.

초보자가 자주 틀리는 부분: 리스트 복사

파이썬을 처음 배울 때 많이 헷갈리는 예제가 있습니다.

a = [1, 2, 3]
b = a

b.append(4)

print(a)
print(b)

초보자는 이렇게 예상할 수 있습니다.

a는 [1, 2, 3]
b는 [1, 2, 3, 4]

하지만 실제 결과는 다음과 같습니다.

[1, 2, 3, 4]
[1, 2, 3, 4]

왜 그럴까요?

b = a는 리스트를 새로 복사한 것이 아닙니다.
b라는 이름도 a가 가리키던 같은 리스트 객체를 가리키게 만든 것입니다.

공식 튜토리얼에서도 단순 대입은 데이터를 복사하지 않는다고 설명합니다.
리스트를 복사하려면 아래처럼 할 수 있습니다.

a = [1, 2, 3]
b = a.copy()

b.append(4)

print(a)
print(b)

실행 결과는 다음과 같습니다.

[1, 2, 3]
[1, 2, 3, 4]

초보자는 이 부분을 꼭 기억해야 합니다.

리스트를 복사하고 싶다면 b = a만 쓰면 안 된다.

자료형 변환: `int()`, `str()`, `float()`

코딩을 하다 보면 자료형을 바꿔야 할 때가 많습니다.

예를 들어 사용자에게 입력받은 값은 보통 문자열로 들어옵니다.

age = "25"

이 값을 숫자로 계산하려면 int()를 사용할 수 있습니다.

age = "25"
next_year_age = int(age) + 1

print(next_year_age)

실행 결과는 다음과 같습니다.

자주 쓰는 변환은 다음과 같습니다.

함수	뜻	예시
`int()`	정수로 변환	`int("10")`
`float()`	실수로 변환	`float("3.14")`
`str()`	문자열로 변환	`str(100)`
`list()`	리스트로 변환	`list("abc")`

예를 들어 문자열을 리스트로 바꾸면 글자 단위로 나뉩니다.

letters = list("Python")

print(letters)

실행 결과는 다음과 같습니다.

['P', 'y', 't', 'h', 'o', 'n']

주의할 점도 있습니다.

number = int("abc")

이 코드는 오류가 납니다.
"abc"는 숫자로 바꿀 수 없는 문자열이기 때문입니다.

초보자는 자료형 변환을 할 때 이렇게 생각하면 됩니다.

겉보기만 숫자인가?
정말 숫자로 바꿀 수 있는 형태인가?

`=`와 `==`를 구분해야 한다

변수를 배울 때 =와 ==도 자주 헷갈립니다.

기호	의미	예시
`=`	이름을 값에 연결	`age = 25`
`==`	두 값이 같은지 비교	`age == 25`

예를 들어 아래 코드는 이름을 값에 연결하는 코드입니다.

age = 25

아래 코드는 값이 같은지 확인하는 코드입니다.

age = 25

print(age == 25)

실행 결과는 다음과 같습니다.

True

조건문에서는 ==를 자주 씁니다.

password = "1234"

if password == "1234":
    print("로그인 성공")
else:
    print("로그인 실패")

실행 결과는 다음과 같습니다.

로그인 성공

초보자는 이렇게 기억하면 됩니다.

=  : 이름을 값에 연결한다
== : 같은지 물어본다

실제 예제로 변수와 자료형 이해하기

이제 간단한 예제를 하나 만들어보겠습니다.

product_name = "무선 마우스"
price = 25000
delivery_fee = 3000
is_member = True

total_price = price + delivery_fee

print(f"상품명: {product_name}")
print(f"상품 가격: {price}원")
print(f"배송비: {delivery_fee}원")
print(f"총 결제 금액: {total_price}원")
print(f"회원 여부: {is_member}")

실행 결과는 다음과 같습니다.

상품명: 무선 마우스
상품 가격: 25000원
배송비: 3000원
총 결제 금액: 28000원
회원 여부: True

이 예제에는 여러 자료형이 들어 있습니다.

이름	값의 자료형	설명
`product_name`	`str`	상품명
`price`	`int`	상품 가격
`delivery_fee`	`int`	배송비
`is_member`	`bool`	회원 여부
`total_price`	`int`	계산 결과

이렇게 실제 상황과 연결하면 변수와 자료형이 훨씬 쉽게 이해됩니다.

ChatGPT로 변수와 자료형을 공부할 때 좋은 질문

ChatGPT를 활용한다면 단순히 “자료형 알려줘”라고 묻기보다, 조건을 구체적으로 주는 편이 좋습니다.

아래처럼 질문해보세요.

나는 Python을 처음 배우는 비전공자야.
변수와 자료형을 쇼핑몰 예제로 설명해줘.
int, str, bool, list, dict가 각각 하나씩 들어간 예제 코드를 만들어줘.
각 줄마다 주석을 달아줘.

오류가 났을 때는 이렇게 질문하면 됩니다.

아래 Python 코드에서 TypeError가 났어.
초보자 기준으로 원인을 설명하고, 수정된 코드를 보여줘.

[코드]
...
[오류 메시지]
...

복습할 때는 문제를 만들어달라고 요청하는 것도 좋습니다.

Python 변수와 자료형을 연습할 수 있는 초보자용 문제 5개를 내줘.
정답은 바로 보여주지 말고, 내가 답을 쓰면 채점해줘.

이런 방식으로 공부하면 답을 그냥 읽는 것보다 기억에 오래 남습니다.

연습문제

아래 문제는 직접 풀어보는 것을 추천합니다.
정답을 보기 전에 코드를 먼저 실행해보세요.

문제 1. 자료형 확인하기

아래 값들의 자료형을 type()으로 출력해보세요.

title = "Python 기초"
views = 150
rating = 4.8
is_published = True
tags = ["Python", "입문", "자료형"]
empty_value = None

문제 2. 문자열과 숫자 함께 출력하기

아래 이름과 값을 사용해 다음 문장을 출력해보세요.

name = "민수"
age = 25

출력 결과:

민수님의 나이는 25살입니다.

힌트: f-string을 사용해보세요.

문제 3. 리스트에 값 추가하기

아래 리스트에 "Docker"를 추가한 뒤 출력해보세요.

skills = ["Python", "Git"]

문제 4. 딕셔너리에서 값 꺼내기

아래 딕셔너리에서 title과 views를 출력해보세요.

post = {
    "title": "파이썬 변수와 자료형",
    "views": 100
}

문제 5. 리스트 복사 확인하기

아래 코드를 실행하면 어떤 결과가 나올지 먼저 예상해보세요.

a = [1, 2, 3]
b = a
b.append(4)

print(a)
print(b)

그다음 b = a.copy()로 바꿔서 다시 실행해보세요.

정리: 변수와 자료형은 Python의 출발점이다

파이썬 변수와 자료형은 단순한 기초 문법처럼 보이지만, 이후 모든 코드의 출발점입니다.

이번 글의 핵심은 세 가지입니다.

1. 변수는 값에 붙이는 이름표에 가깝다.
2. 자료형은 값 객체가 어떤 종류인지 알려준다.
3. 자료형에 따라 할 수 있는 일이 달라진다.

처음에는 int, float, str, bool, None, list, dict 정도만 확실히 익혀도 충분합니다.
그다음 조건문, 반복문, 함수로 넘어가면 Python 코드가 훨씬 자연스럽게 읽히기 시작합니다.

다음 단계로는 for 반복문과 while 반복문을 배우는 것이 좋습니다.
리스트와 딕셔너리를 반복문과 함께 쓰면 실제 자동화 예제를 만들 수 있기 때문입니다.

FAQ

Q1. 파이썬 변수는 꼭 자료형을 미리 정해야 하나요?

아니요. 파이썬은 변수를 만들 때 int age = 25처럼 자료형을 미리 쓰지 않습니다. age = 25라고 쓰면 age라는 이름이 정수 객체 25에 연결됩니다. 이후 age = "25"처럼 다시 대입하면 같은 이름이 문자열 객체 "25"에 새로 연결될 수 있습니다.

Q2. 숫자처럼 생긴 `"100"`은 숫자인가요?

아닙니다. 따옴표 안에 있으면 문자열입니다. "100"은 str이고, 100은 int입니다. 계산하려면 int("100")처럼 변환해야 합니다.

Q3. `list`와 `tuple`의 가장 큰 차이는 무엇인가요?

list는 값을 추가하거나 바꿀 수 있고, tuple은 한 번 만든 뒤 항목을 바꿀 수 없습니다. 초보자는 값이 바뀔 가능성이 있으면 list, 고정된 순서형 묶음이면 tuple로 생각하면 됩니다.

Q4. `dict`는 언제 쓰나요?

이름, 나이, 조회수처럼 항목 이름과 값이 함께 있는 데이터를 표현할 때 씁니다. 사용자 정보, 상품 정보, 블로그 글 정보, API 응답에서 자주 사용합니다.

Q5. `type()`은 실무에서도 쓰나요?

디버깅할 때 사용할 수 있습니다. 다만 실제 코드에서 자료형을 검사할 때는 상황에 따라 isinstance()를 쓰는 경우도 많습니다. 입문 단계에서는 type()으로 값의 자료형을 확인하는 연습부터 하면 됩니다.

Q6. 변수 이름은 한글로 써도 되나요?

파이썬에서는 한글 변수명도 동작할 수 있습니다. 다만 예제, 문서, 협업 환경은 대부분 영어 기준이므로 처음에는 영어 변수명에 익숙해지는 편이 좋습니다.

Q7. `None`과 `NoneType`은 같은 말인가요?

같은 말은 아닙니다. None은 값의 부재를 나타내는 특별한 값이고, NoneType은 그 None 값의 타입입니다. type(None)을 실행하면 <class 'NoneType'>이 출력됩니다.

ChatGPT로 Python 공부하는 방법: 비전공자도 따라 하는 파이썬 입문 로드맵

notebase — Wed, 20 May 2026 08:55:01 +0900

ChatGPT로 Python을 공부해도 괜찮을까요? 2026년 5월 기준으로 파이썬 최신 버전, 초보자 학습 순서, 질문 예시, 주의할 점까지 비전공자 기준으로 정리했습니다.

ChatGPT로 Python 공부를 시작하려는 사람이 많아졌습니다.
예전에는 책이나 강의로 문법을 따라가는 방식이 일반적이었지만, 이제는 모르는 개념을 바로 질문하고, 예제 코드를 만들고, 오류 메시지까지 해석해주는 AI 도구를 함께 쓸 수 있습니다.

그렇다면 ChatGPT만 있으면 Python을 제대로 배울 수 있을까요?

결론부터 말하면, ChatGPT는 좋은 학습 도구가 될 수 있습니다.
다만 선생님을 완전히 대체한다기보다는, 옆에서 설명을 바꿔주고 예제를 만들어주는 보조 코치에 가깝습니다.

이 글에서는 2026년 5월 기준으로 ChatGPT를 활용해 Python을 공부하는 방법을 초보자 기준으로 정리해보겠습니다.

2026년 5월 기준 Python 최신 버전은?

2026년 5월 기준 Python 공식 다운로드 페이지에서 확인되는 최신 안정 버전은 Python 3.14.5입니다.

다만 초보자 입장에서는 버전 숫자보다 중요한 것이 있습니다.

너무 오래된 Python 2.x 자료를 따라 하지 않는 것입니다.

요즘 Python 입문 자료는 대부분 Python 3 기준입니다.
따라서 처음 설치할 때는 공식 사이트에서 제공하는 최신 Python 3 버전을 설치하면 됩니다.

처음 설치하는 사람이라면 운영체제에 맞게 Python 공식 다운로드 페이지에서 제공하는 설치 파일을 사용하는 것이 가장 무난합니다.

처음에는 복잡한 개발 환경보다 “설치 후 터미널에서 실행 확인”까지 하는 것이 중요합니다.

python --version

또는 환경에 따라 아래 명령어를 사용할 수도 있습니다.

python3 --version

정상적으로 설치되었다면 다음과 비슷한 결과가 나옵니다.

Python 3.14.5

버전 숫자가 조금 달라도 괜찮습니다.
Python 3.12, 3.13, 3.14처럼 비교적 최근 버전이라면 입문 학습에는 큰 문제가 없습니다.

ChatGPT로 Python을 공부해도 괜찮을까?

괜찮습니다.
특히 처음 배우는 사람에게는 오히려 도움이 되는 부분이 많습니다.

Python 공식 사이트에서도 Python은 초보자가 배우고 사용하기 쉬운 언어라고 설명합니다. 그래서 프로그래밍을 처음 배우는 사람이 시작하기 좋은 언어로 자주 추천됩니다.

ChatGPT를 함께 쓰면 다음과 같은 부분에서 도움을 받을 수 있습니다.

상황	ChatGPT 활용법
개념이 이해되지 않을 때	쉬운 비유로 다시 설명해달라고 요청
예제가 부족할 때	비슷한 예제를 3개 더 만들어달라고 요청
오류가 났을 때	에러 메시지를 붙여넣고 원인 분석 요청
코드가 길어졌을 때	한 줄씩 주석을 달아달라고 요청
공부 순서를 모를 때	4주 학습 계획을 만들어달라고 요청

다만 중요한 점이 있습니다.

ChatGPT가 항상 정확한 답을 주는 것은 아닙니다.
특히 라이브러리 버전, 설치 명령어, 최신 기능, 운영체제별 차이에서는 틀릴 수 있습니다.

그래서 초보자는 ChatGPT 답변을 그대로 외우기보다, 직접 실행해보고 결과를 확인하는 방식으로 공부해야 합니다.

ChatGPT로 Python 공부하는 5단계

1단계: Python이 어디에 쓰이는지 먼저 이해하기

처음부터 문법을 외우려고 하면 금방 지칩니다.
먼저 Python으로 무엇을 할 수 있는지 이해하는 것이 좋습니다.

예를 들면 다음과 같습니다.

엑셀 파일 정리
반복 업무 자동화
웹 데이터 수집
간단한 프로그램 만들기
데이터 분석
AI, 머신러닝 기초 학습
블로그 운영 자동화

처음 배우는 사람이라면 “웹사이트 만들기”보다 파일 정리, 엑셀 자동화, 텍스트 정리 같은 작은 작업부터 시작하는 것이 좋습니다.

ChatGPT에는 이렇게 물어볼 수 있습니다.

나는 코딩을 처음 배우는 비전공자야.
Python으로 실제 생활에서 할 수 있는 쉬운 예제 10가지를 알려줘.
난이도도 함께 표시해줘.

이런 질문은 단순히 문법을 배우는 것보다 훨씬 동기부여가 됩니다.

2단계: 설치와 실행 환경부터 확인하기

Python 공부를 시작할 때 가장 많이 막히는 부분은 의외로 문법이 아닙니다.
설치와 실행 환경입니다.

초보자는 다음 세 가지만 확인하면 됩니다.

1. Python이 설치되어 있는가?
2. 터미널에서 python 명령어가 실행되는가?
3. VS Code 같은 편집기에서 코드를 실행할 수 있는가?

이때 ChatGPT에는 이렇게 질문하면 됩니다.

Mac에서 Python을 처음 설치하려고 해.
공식 사이트 기준으로 설치하는 방법을 초보자도 따라 할 수 있게 단계별로 알려줘.
설치 후 확인 명령어도 알려줘.

Windows라면 이렇게 바꾸면 됩니다.

Windows 11에서 Python을 처음 설치하려고 해.
PATH 설정이 뭔지도 모르는 초보자 기준으로 설명해줘.
설치 후 python --version을 확인하는 방법까지 알려줘.

주의할 점은 운영체제를 꼭 말해야 한다는 것입니다.
Windows, Mac, Linux는 설치 과정이 다릅니다.

3단계: 변수, 조건문, 반복문만 먼저 익히기

Python을 처음 배울 때 모든 문법을 한 번에 외우려고 하면 어렵습니다.
처음에는 아래 세 가지만 집중해도 됩니다.

변수: 값을 담는 이름
조건문: 상황에 따라 다른 코드를 실행하는 방법
반복문: 같은 작업을 여러 번 실행하는 방법

예를 들어 변수는 이렇게 이해할 수 있습니다.

name = "민수"
age = 25

print(name)
print(age)

이 코드는 name이라는 이름에 “민수”를 담고, age라는 이름에 25를 담은 뒤 출력합니다.

조건문은 이렇게 사용합니다.

age = 20

if age >= 20:
    print("성인입니다.")
else:
    print("미성년자입니다.")

반복문은 같은 일을 여러 번 할 때 사용합니다.

for i in range(5):
    print("Python 공부 중입니다.")

초보자는 이 코드를 외우려고 하기보다, ChatGPT에게 설명을 요청하는 것이 좋습니다.

아래 Python 코드를 한 줄씩 초보자 기준으로 설명해줘.
비유를 들어서 설명해줘.

for i in range(5):
    print("Python 공부 중입니다.")

이렇게 질문하면 단순한 문법 설명보다 훨씬 이해하기 쉽습니다.

4단계: 짧은 자동화 예제를 따라 하기

문법만 계속 공부하면 실력이 잘 늘지 않습니다.
짧은 자동화 예제를 직접 실행해보는 것이 좋습니다.

예를 들어 폴더 안의 파일명을 정리하는 작업, 텍스트에서 특정 단어를 세는 작업, 간단한 계산기를 만드는 작업이 좋습니다.

처음에는 이런 예제로 시작할 수 있습니다.

text = "Python is easy. Python is useful."

count = text.count("Python")

print("Python이라는 단어는", count, "번 나옵니다.")

실행 결과는 다음과 같습니다.

Python이라는 단어는 2 번 나옵니다.

이 정도 예제는 짧지만, 변수와 문자열 처리, 출력 개념이 들어 있습니다.

ChatGPT에는 이렇게 질문하면 좋습니다.

Python 초보자가 따라 할 수 있는 10줄 이하의 자동화 예제를 만들어줘.
변수, 조건문, 반복문 중 하나 이상이 들어가게 해줘.
그리고 코드 아래에 한 줄씩 설명을 붙여줘.

처음부터 큰 프로그램을 만들 필요는 없습니다.
작은 코드를 여러 번 실행해보는 것이 더 중요합니다.

5단계: 오류 메시지를 ChatGPT로 해석하기

코딩 공부에서 오류는 피할 수 없습니다.
오히려 오류를 읽는 능력이 실력입니다.

예를 들어 이런 오류가 나왔다고 해보겠습니다.

NameError: name 'pritn' is not defined

초보자는 이 메시지를 보고 당황할 수 있습니다.
하지만 실제 원인은 단순합니다.

pritn("Hello")

print를 pritn으로 잘못 입력한 것입니다.

이럴 때 ChatGPT에는 이렇게 질문하면 됩니다.

Python에서 아래 오류가 나왔어.
초보자 기준으로 원인과 해결 방법을 설명해줘.

NameError: name 'pritn' is not defined

가능하면 오류 메시지만 보내지 말고, 실행한 코드와 오류 메시지를 함께 보내는 것이 좋습니다.

아래 Python 코드를 실행했더니 오류가 났어.
1. 오류 원인
2. 수정된 코드
3. 앞으로 같은 실수를 피하는 방법
이렇게 나눠서 설명해줘.

[내 코드]
...

[오류 메시지]
...

ChatGPT의 장점은 오류를 무섭지 않게 만들어준다는 점입니다.
초보자는 이 과정에서 “에러 메시지를 읽는 습관”을 만들 수 있습니다.

ChatGPT에게 이렇게 질문하면 공부가 잘 된다

ChatGPT를 코딩 공부에 잘 활용하려면 질문 방식이 중요합니다.

나쁜 질문은 이렇게 너무 짧습니다.

파이썬 알려줘

이렇게 물으면 답변이 넓고 뻔해질 가능성이 큽니다.

좋은 질문은 조건이 구체적입니다.

나는 Python을 처음 배우는 비전공자야.
변수, 조건문, 반복문을 각각 5줄 이하 예제로 설명해줘.
각 코드 아래에는 초보자용 설명을 붙여줘.
마지막에는 내가 직접 풀 수 있는 연습문제 3개를 내줘.

또는 이런 식도 좋습니다.

아래 Python 코드를 초보자 기준으로 설명해줘.
전문 용어는 쉽게 풀어주고, 각 줄마다 주석을 달아줘.

[코드 붙여넣기]

공부용으로는 다음 형식을 기억하면 좋습니다.

내 수준 + 원하는 주제 + 예제 조건 + 설명 방식

예를 들어:

나는 코딩을 처음 배우는 사람이야.
Python의 for 반복문을 배우고 싶어.
엑셀 업무 자동화와 연결되는 쉬운 예제로 설명해줘.
코드는 10줄 이하로 작성해줘.

이렇게 질문하면 ChatGPT 답변의 품질이 훨씬 좋아집니다.

ChatGPT 답변을 그대로 믿으면 안 되는 경우

ChatGPT가 코딩 공부에 도움이 되는 것은 맞지만, 그대로 믿으면 안 되는 경우도 있습니다.

특히 아래 상황에서는 반드시 확인이 필요합니다.

상황	주의할 점
설치 명령어	운영체제마다 다를 수 있음
라이브러리 사용법	버전에 따라 코드가 달라질 수 있음
오래된 블로그 코드	현재 버전에서 작동하지 않을 수 있음
보안 관련 코드	민감한 정보가 노출될 수 있음
자동화 코드	파일 삭제, 덮어쓰기 위험이 있을 수 있음

예를 들어 파일을 삭제하거나 이름을 바꾸는 코드는 반드시 테스트 폴더에서 먼저 실행해야 합니다.

import os

# 실제 중요한 폴더에서 바로 실행하지 말 것

초보자는 ChatGPT에게 코드 작성을 요청할 때 이렇게 덧붙이는 것이 좋습니다.

실제 파일을 삭제하거나 덮어쓰지 않는 안전한 예제로 만들어줘.
테스트용 폴더에서만 실행하는 방식으로 설명해줘.

이 한 문장만 추가해도 위험한 예제를 줄일 수 있습니다.

ChatGPT의 Python 실행 기능도 활용할 수 있다

2026년 기준 ChatGPT에는 코딩 학습에 도움이 되는 기능이 더 늘었습니다.

OpenAI 도움말에 따르면 ChatGPT의 데이터 분석 기능은 일부 작업에서 Python 코드를 실행해 파일, 표, CSV 같은 데이터를 분석할 수 있습니다. 또한 Canvas는 글쓰기와 코딩 프로젝트를 편집하고 수정하는 인터페이스로 제공됩니다.

즉, 단순히 “코드를 물어보는 도구”를 넘어, 일부 환경에서는 코드를 실행하고 결과를 확인하는 방식으로도 활용할 수 있습니다.

다만 초보자는 처음부터 이 기능에만 의존하지 않는 것이 좋습니다.
내 컴퓨터에 Python을 설치하고, 직접 실행해보는 경험도 필요합니다.

Python 공부 후 이어서 배우면 좋은 기술

Python 기초를 어느 정도 익혔다면 다음 단계로 넘어갈 수 있습니다.

다음 주제	배우면 좋은 이유
Git / GitHub	코드 저장과 기록 관리에 필요
VS Code	Python 코드를 편하게 작성하는 편집기
가상환경	프로젝트별 라이브러리 관리를 위해 필요
pandas	엑셀, CSV 데이터 정리에 유용
requests	웹 데이터 요청 기초를 배울 수 있음
Docker	실행 환경을 일정하게 관리할 때 필요

초보자에게 가장 추천하는 순서는 이렇습니다.

Python 기초
→ VS Code 사용법
→ GitHub 기초
→ pandas로 엑셀 자동화
→ Docker 기초

처음부터 Docker나 서버 배포까지 가려고 하면 어렵습니다.
먼저 Python으로 작은 문제를 해결하는 경험을 만드는 것이 좋습니다.

정리: ChatGPT는 Python 공부의 지름길이 아니라 보조 코치다

ChatGPT로 Python을 공부하는 것은 충분히 좋은 방법입니다.
특히 비전공자나 초보자에게는 모르는 개념을 바로 물어볼 수 있다는 점이 큰 장점입니다.

하지만 ChatGPT가 모든 답을 정확하게 주는 것은 아닙니다.

그래서 가장 좋은 공부 방식은 다음과 같습니다.

설명은 ChatGPT에게 듣고,
코드는 직접 실행하고,
오류는 다시 ChatGPT에게 질문하고,
결과는 스스로 확인한다.

Python은 처음 배울 때 어렵게 느껴질 수 있지만, 작은 예제를 반복하면 생각보다 빠르게 익숙해집니다.

처음부터 큰 프로그램을 만들려고 하지 않아도 됩니다.
오늘은 변수 하나, 내일은 조건문 하나, 그다음은 반복문 하나만 익혀도 충분합니다.

ChatGPT를 잘 활용하면 혼자 공부할 때 막히는 시간을 줄일 수 있습니다.
중요한 것은 답을 복사하는 것이 아니라, 왜 그렇게 작동하는지 계속 질문하는 것입니다.

FAQ

Q1. ChatGPT만으로 Python을 배워도 되나요?

기초 학습은 가능합니다. 다만 ChatGPT 답변을 그대로 믿기보다, 직접 코드를 실행하면서 확인해야 합니다. 설치 방법이나 라이브러리 사용법은 최신 공식 문서도 함께 확인하는 것이 좋습니다.

Q2. Python을 처음 배우면 어떤 버전을 설치해야 하나요?

2026년 5월 기준 Python 공식 사이트의 최신 안정 버전은 Python 3.14.5입니다. 초보자는 공식 사이트에서 제공하는 최신 Python 3 버전을 설치하면 됩니다. 다만 강의나 책이 특정 버전을 기준으로 한다면 그 버전에 맞춰도 됩니다.

Q3. 코딩을 전혀 몰라도 ChatGPT로 공부할 수 있나요?

가능합니다. 대신 처음부터 어려운 프로젝트를 만들기보다 변수, 조건문, 반복문, 함수처럼 기본 개념부터 차근차근 공부하는 것이 좋습니다.

Q4. ChatGPT가 만들어준 코드는 항상 맞나요?

항상 맞지는 않습니다. 특히 최신 라이브러리, 운영체제별 설치 방법, 파일 삭제나 자동화 코드에서는 주의가 필요합니다. 반드시 테스트 환경에서 먼저 실행해보는 것이 좋습니다.

Q5. Python 다음에는 무엇을 배우면 좋나요?

목적에 따라 다릅니다. 업무 자동화가 목적이라면 pandas와 엑셀 자동화를 배우는 것이 좋고, 개발자로 확장하고 싶다면 Git, GitHub, Docker를 이어서 배우는 것이 좋습니다.