원문: https://velog.io/@playername_ltt/AI-코딩-툴-제대로-쓰고-계신가요
본 컨텐츠는 길벗출판사에서 보내준 <AI 자율학습 클로드 코드·코덱스 CLI·제미나이 CLI 완전 활용법> 을 읽고 작성한 컨텐츠 입니다.
서평 작성이라서 생각을 많이 했는데 이 활용법을 읽고, 이 학습서의 대략적인 내용을 저의 추가 활용방안에 대한 생각과 작성해 보려고 합니다. 아마 독후감과 서평 사이라고 보시면 될 것 같습니다.
마지막에 제가 책을 읽고 직접 만들어본
Claude Code를 위한 Springboot 프로젝트 템플릿을 공유드립니다.
언제까지 브라우저 창과 IDE를 오가며 '복사-붙여넣기'의 굴레에 갇혀 있을 수는 없습니다. 이제는 터미널 안에서 코드베이스를 직접 이해하는 AI를 만나야 할 때입니다.
현 시점에서 IT 업계 종사자라면 AI를 사용하지 않아본 분들은 없을 겁니다.
아, 그니까 웹 브라우저에서 사용하는 AI 말입니다.
다들 모르는 문제에 대하여 질문을 작성하고, GPT가 내놓은 답변을 읽고(때때로는 귀찮아 코드만 복사하고), 내용을 붙여넣고, 돌려보고, 안된다고 푸념하고, 다시 작성하고…… 반복해본 경험 있으실 겁니다.
여기서 다루는 가장 큰 세 가지인 Claude Code, Codex CLI, Gemini CLI는 여러분의 코드베이스를 읽어 여러분이 물어본 질문에 답변하고 요청한 작업을 수행합니다.
우선 이 책에서는 AI 코딩 도구를 크게 두 가지 분류로 나누어 말합니다.
IDE형과 터미널형으로요.
AI 코딩 도구가 처음 각광받기 시작하던 시점에는 IDE가 시장을 지배했었지만, 현 시점에서는 터미널 기반 툴이 단연코 시장을 압도하고 있습니다.
이 책은 그 “CLI 툴”을 입문부터 실무까지 사용하는 방법을 소개하고 있습니다.
툴 사용을 위한 기초적인 배경지식, 툴 설치부터 프로젝트에 툴 사용하기까지 광범위한 내용을 다루고 있습니다.
책에서 다루는 가장 첫 번째 툴은 “Claude Code”입니다.
많은 사람들이 입을 모아 “가장 개발을 잘한다”라고 얘기하는 도구이죠.
이전 글(한달만에 AI로 코드 3만라인 짜며 깨달은 것)을 작성하던 시점에는 Claude Code를 사용해보지 않았지만, 최근 회사에서 Claude Code를 지원해주기 시작하여 열심히 써먹어보고 있습니다.
우선 빠르게 각 챕터별 핵심 내용 위주로 소개해드리겠습니다.
처음 써보는 사람도 상세하게 따라 할 수 있도록 책에 상세하게 잘 정리되어있으니 궁금하시면 책 참고하시면 좋을 것 같습니다.
“컨텍스트(Context) 관리하기”
쉽게 말해 대화 내용 관리입니다. 최근 RLM(Recursive Language Model)의 발견 등으로 인해 컨텍스트 윈도우의 크기(한 세션에서 AI가 맥락을 이해할 수 있는 길이)가 비약적으로 발전 중이지만, 이는 다 비용으로 이어집니다.
무엇보다 비용이 문제가 아닌, AI가 사용자의 의도를 잘못 이해하기 시작하면 이는 곧 생산성 저하로 이어지기 때문에 이를 제대로 관리하는 것이 핵심이라고 할 수 있습니다.
상황 하나를 가정해봅시다.
AI에게
“이벤트를 날짜별로 조회할 수 있는 기능을 만들어줘”
라고 입력했더니 AI는 이벤트의 조회 조건을 하루하루 끊어서 진짜 순수 날짜별로만 조회할 수 있게 만들어버립니다.
잘못된 기능이기에 다시 요청합니다.
“아니 이게 아니고 이벤트 날짜별 조회인데 특정 기간을 지정하고 그 사이에 진행하는 모든 이벤트를 조회하고 싶었던 거야.”
이 두 컨텍스트는 AI에게 불필요한 컨텍스트가 되어 AI 기능과 기억력에 사소하게 마이너스 요소로 작동합니다.
이를 해결하기 위해 가장 쉬운 방법은 “Claude Code”에서 /compact를 실행해버리면 끝입니다. 핵심만 추출하고 이전 컨텍스트들은 날려버리거든요.
AI의 성능과 속도를 위해선 /compact가 아니더라도, 컨텍스트 관리가 필수적입니다.
이 부분이 다들 놓치고 넘어갈 수 있는 부분인데 언급하고 사유까지 더 상세하게 이해하기 쉽게 설명해준 부분이 상당히 인상적이었습니다.
“md 파일로 프로젝트 구조잡고 운영하기”
사실 이 부분은 제가 거의 써먹지 않은 방법이었습니다.
멀티모듈 프로젝트를 운영하며 모듈별 관리에 고민이 많았는데, 책에서 제안한 '모듈별 .md 관리 방식'이 무척 유용했습니다.
각 모듈의 폴더 내에 직접 설명 문서를 두는 방식을 최근 적용하기 시작했는데, 확실히 최초 페르소나 부여 및 프로젝트 구조 파악이 빨라지는 효과를 체감하고 있습니다.
가장 대표적인 사례는 Anthropic의 Claude Code가 제안하는 CLAUDE.md 기반 구조입니다.
프로젝트 루트에만 가이드를 두는 것이 아니라, 각 모듈이나 디렉토리별로 컨텍스트 파일을 분산 배치하여 AI가 해당 폴더에 진입했을 때 필요한 정보만 읽게 하는 방식입니다.
Root CLAUDE.md: 전체 기술 스택, 빌드 명령어, 전역 코드 스타일.
Module CLAUDE.md (혹은 README.md): 해당 모듈의 도메인 로직, 의존 관계, 특정 설계 패턴(예: "이 모듈은 Querydsl만 사용함").
Claude Code 공식 문서: Best Practices for Claude Code
문서에서는 "코드만으로 추론할 수 없는 의도"를 담기 위해
CLAUDE.md를 적극 권장하며, 대규모 프로젝트에서는 하위 디렉토리에 전용 가이드를 둘 것을 제안합니다.
AGENTS.md 표준화 프로젝트특정 도구(Claude, Cursor)에 종속되지 않고, 모든 AI 에이전트가 읽을 수 있는 공통 규약을 만들려는 시도입니다.
프로젝트 루트에 AGENTS.md를 두고 아래와 같은 섹션을 명확히 구분합니다.
Onboarding: 프로젝트 목적 및 환경 설정.
Architecture: 데이터 흐름 및 모듈 구조.
Rules & Standards: 금지 사항(Anti-patterns) 및 필수 준수 사항.
AGENTS.md 공식 사이트: agents.md
OpenAI Codex, Google, Cursor 등의 개발자들이 협력하여 만든 오픈 형식입니다. 여러 에이전트가 공통으로 참조할 수 있는 "AI 전용 README"의 표준을 제시합니다.
.cursorrules 및 .claude/rules/)최근에는 설정 파일 하나에 모든 규칙을 때려 넣는 대신, 관심사별로 규칙 파일을 쪼개는 방식이 주류입니다.
# 구조 예시
project-root/
├── .claude/
│ └── rules/
│ ├── testing.md # 테스트 코드 작성 원칙
│ ├── api-design.md # API 네이밍 및 DTO 규약
│ └── db-schema.md # JPA 및 DB 마이그레이션 규칙
├── module-websocket/
│ └── README.md # WebSocket 명세 및 로직 설명
└── module-api/
└── README.md # API 명세 및 인증 흐름Cursor 가이드: Cursor Rules Best Practices
"규칙은 짧고(500라인 이하), 구체적이며, 파일 기반으로 참조(Reference files)해야 한다"고 명시합니다. 특히 복잡한 백엔드 프로젝트에서 AI의 환각을 줄이는 가장 효과적인 방법으로 꼽힙니다.
MCP 사용법과, 서브에이전트 사용법, Hook 사용법 등을 설명해 주고 있습니다.
이 부분에서는 고급 기능인 만큼 충분히 익숙해지고 이해도를 높인 다음 사용하는 것을 추천드립니다.
(저도 사실 아직 제대로 못써보고 있습니다)
최근 AI의 지나친 권한 부여, 보안 등 이슈가 많았거든요. 발전속도에 비해 못따라오는 듯한 그런 느낌도 있고요.
혹시나 읽어보시거나 사용하실 때 공유할만한 팁이 있다면 공유해주세요 :)
앞에서 쌓은 지식들을 바탕으로 AI를 만땅으로 사용하는 개발 워크플로우를 순차적으로 상세하게 설명해줍니다.
PRD 작성 → 실행계획과 WBS 작성 → 컨텍스트 파일 작성
PRD는 문서를 완벽하게 만드는 것이 아니라, AI가 참고할 핵심 기준을 만드는 것을 주요 목적으로 합니다.
제품 개요, 핵심 기능, 대상 사용자, 기술 스택 등을 작성합니다.
저같은 경우는 귀찮아서 AI한테 초안 작성하라고 한다음에 수정합니다.
실행 계획은 프로젝트를 어떤 순서대로 진행할지 정리하는 로드맵입니다.
기존에는 타임라인 정의, 작업 간 의존성 파악, 리소스 배분, 주요 마일스톤 설정이 필수적입니다.
WBS는 큰 작업을 작은 작업들로 세분화하고 관리하기 쉽게 만드는 구조입니다.
PRD를 잘 작성해 두었다면, Plan 모드를 켜서 실행계획과 WBS 또한 AI가 상세하게 작성해줍니다.
PRD로 무엇을 만들지, WBS로 어떻게 만들지를 정의했다면 이를 활용하여 컨텍스트 파일을 작성하여 계획을 마무리짓습니다.
AI가 프로젝트를 안정적으로 이해하기 위한 파일문서 입니다.
프로젝트 요약, 기술 스택, 핵심 규칙, 폴더 구조 등을 명시해둡니다.
// 컨텍스트 파일 example
# 프로젝트 컨텍스트: [프로젝트 명]
## 1. 프로젝트 요약
- **목적**: [예: 실시간 컨퍼런스 통번역 및 기록 서비스]
- **대상 사용자**: [예: 다국어 행사를 진행하는 운영진 및 참가자]
- **핵심 가치**: 저지연 번역(500ms 이내), 높은 도메인 용어 정확도
## 2. 기술 스택 (Tech Stack)
- **Backend**: Java 21, Spring Boot 3.4
- **Database**: PostgreSQL (Main), Redis (Cache)
- **AI/ML**: Google Gemini API, LangChain4j
- **Infrastructure**: Docker, Kubernetes
## 3. 핵심 개발 규칙 (Core Rules)
- **Architecture**: 멀티모듈 구조를 따르며, 각 모듈의 책임(Domain/API/Infra)을 엄격히 분리한다.
- **Code Style**: Google Java Style Guide를 준수하고, 모든 비즈니스 로직은 Service 계층이 아닌 Domain 엔티티 내부에서 처리하도록 노력한다.
- **Exception**: `CustomException`을 정의하여 사용하며, 모든 API 응답은 `ApiResponse<T>` 포맷으로 통일한다.
- **Testing**: JUnit 5와 AssertJ를 사용하여 핵심 도메인 로직에 대한 단위 테스트를 반드시 작성한다.
## 4. 폴더 구조 (Project Structure)
- `project-api/`: 외부 클라이언트 요청 처리 (Controller, DTO)
- `project-domain/`: 순수 비즈니스 로직 및 엔티티
- `project-infra/`: DB 설정, 외부 API(Gemini) 연동부
- `docs/`: PRD, WBS 등 기획 문서 보관"AI에게는 지도가 필요": PRD가 '무엇을(What)' 만들지 정의한다면, 컨텍스트 파일은 '어떻게(How)' 유지할지를 정의합니다. 폴더 구조만 명시해줘도 AI가 파일을 찾느라 엉뚱한 곳을 헤매는 시간을 80% 이상 줄일 수 있습니다.
"규칙은 구체적일수록 좋음": 단순히 "Clean Code를 지켜줘"라고 하기보다 "Service 계층에서 인터페이스를 쓰지 마"처럼 도구적으로 명확한 지시를 담는 것이 핵심입니다.
"살아있는 문서화": 프로젝트가 진행되면서 새로운 기술이나 규칙이 추가되면 이 파일을 가장 먼저 업데이트하세요. AI는 항상 최신화된 이 파일을 바탕으로 다음 단계의 코드를 생성합니다
부트스트래핑 → 단계별 개발 → TDD 개발 → 코드 품질 개선 → 배포와 운영
이 파트에서는 각 파트별 AI로 “무지성 바이브 코딩”이 아닌 “똑똑한 바이브 코딩”하는 법을 예시와 함께 상세하게 안내해 줍니다.
각 예시를 직접 해보며 하는 것을 추천드리며, 이 부분은 책을 따라가서 해보면 좋을 것 같습니다.
아래는 제가 자주 사용하는 코드 리팩토링 프롬프트입니다.
<클래스>를 리팩토링하세요.
- SOLID원칙과 클린코드 원칙 준수
- 디자인패턴 적용이 가능한 포인트 점검 후 적용
- 과도한 추상화 및 클래스 분리 지양아래는 책을 읽고 제가 나름대로 만들어본 Claude Code를 위한 Springboot 프로젝트 템플릿입니다.
코드를 보고 편의에 맞게 수정해서 사용하세요.
추후 시간이 될 때 종종 업데이트하고, FastAPI등의 다른 프레임워크의 boilerplate도 추가하겠습니다.
반은 맞고 반은 틀립니다. 개발자가 되고 싶어 갓 공부를 시작한 대학교 저학년이라면 이게 충분히 맞는 말입니다.
하지만 어느정도 개발에 대한 이해를 하고 나면 AI가 오히려 공부에 도움이 됩니다.
AI 툴은 훌륭한 조수입니다. 여러분의 생각을 보조하고, 필요하다면 방향도 제시해줄 수 있죠.
혼자 작성한 코드만을 바라보며 공부한다면 자신의 스타일과 구현 방법 등에 매몰되어 더딘 성장을 할 거라고 생각합니다.
AI 툴은 여러분이 생각하지 못한 문제 해결 방법과 코드를 제공합니다. 남의 코드를 보는 것은 성장의 발판 중 하나이죠.
또한, 한번이라도 써보고 본인 가치관에 맞는 생각을 해보길 추천합니다.
AI 툴도 공부하며 잘 쓸줄 알아야 하는 시대가 다가오고 있습니다. 개발자는 점점 AI들을 사용하는 기술자이자 지휘자가 되어가고 있습니다.
저는 개발자를 ‘기능을 구현하는 사람’이라고 정의하고, 엔지니어를 ‘문제를 정의하고 해결방법을 찾는 사람’이라과 정의합니다. 이제 ‘개발’은 AI에게 맡기고, ‘엔지니어링’은 사람이 맡아 진행해야 한다고 생각합니다.
미뤄오던 AI 툴 공부, 이제 슬슬 함께 시작해봅시다 :)
피드백이나 소개해줄 팁이 있다면 언제든 댓글 달아주세요.