프로젝트 생성 흐름
Claude Code를 활용하여 프로젝트를 생성하고 관리하는 전체 흐름을 이해합니다. 환경 초기화부터 진행 전략, CLAUDE.md 관리, 도구 활용까지 실전에 필요한 핵심 개념을 정리합니다.
~/.claude 리셋의 중요성
Claude Code가 이상하게 동작할 때 가장 확실한 해결책은 ~/.claude 디렉토리를 리셋하는 것입니다.
잘못 쌓인 설정, 오래된 캐시, 꼬인 인증 정보 등을 깔끔하게 리셋
실험적으로 건드린 settings.json이 문제를 일으킬 때
전역 CLAUDE.md에 잘못된 규칙이 누적됐을 때
최초 프로젝트를 어떻게 생성할 것인가?
프레임워크와 인프라 결정
어떤 프레임워크와 인프라 기반으로 만들지를 먼저 고민하고 요청합니다.
Plan Mode로 시작
바로 개발에 들어가지 않고 Plan Mode를 활용하여 구조를 먼저 설계합니다.
Example Prompt
Spring Initializr를 이용해서 Spring Boot 4 최신버전, JPA/H2/Lombok 을 사용하는 프로젝트를 생성해줘 - Gradle Kotlin DSL - package: moz.ai.reminder - project name: mozreminder
진행 순서
어떤 방향으로 진행할지는 프로젝트의 범위에 따라 결정합니다.
prompt → 개발
간단한 작업이나 빠른 프로토타이핑
prompt → plan → 개발
중간 규모의 기능 구현
prompt → prd.md → 개발
요구사항을 문서화한 후 개발
prompt → spec → implementation plan → task → 개발 (SDD)
체계적인 대규모 개발
prompt → slice별 개발, 검증, 가이드 갱신
User layer 등 슬라이스 단위 반복 개발
추천 방식
4번과 5번의 조합이 좋은 방법입니다. spec.md를 기반으로 phase별 개발을 진행하고, 각 phase 마지막에 Acceptance Criteria를 두어 완료 여부를 판단합니다.
PRD → Spec 변환 프롬프트 예시
prd.md 를 spec.md 로 변경해줘 spec.md 의 내용을 단순한 것부터 점점 기능을 추가하는 방식으로 개발하도록 phase 를 구분해서 plan.md 에 개발계획을 넣어줘. 기술에 대한 내용도 같이 넣어줘.
Phase별 개발 진행 프롬프트 예시
@plan.md 를 구현하는 세부 작업을 정리해서 tasks.md 리스트를 만들고, 체크 가능하도록 해줘. 이제 @tasks.md의 phase 1 기능 전체를 개발하고, task 하나가 완료되면 tasks.md 파일에 check 해줘 phase2 ~ phase5 까지 계속 진행하고 phase 하나 마치면 commit 해줘
CLAUDE.md 관리
CLAUDE.md는 프로젝트의 규칙과 컨벤션을 AI에게 전달하는 핵심 파일입니다. 효과적으로 관리하는 것이 프로젝트 품질에 직결됩니다.
주의사항
CLAUDE.md에 AI가 직접 작성한 내용이 너무 길어지면 실행 시 누락되는 경우가 생깁니다. 직접 파일을 확인해서 AI가 알아서 잘 하는 내용은 제거하세요.
저장 위치
코딩 관례는 CLAUDE.md에 명시적으로 남기는 게 중요합니다. ~/.claude/projects의 MEMORY.md에도 남지만 CLAUDE.md에 남기는 것이 더 확실합니다.
커밋 컨벤션
커밋 컨벤션처럼 매번 요청할 수 없는 규칙은 CLAUDE.md에 기술합니다. 반복되는 작업이 있다면 Skill로 만드는 것도 고려하세요.
CLAUDE.md 업데이트 흐름
도구, 에이전트, 스킬
Claude Code가 가진 핵심 구성 요소들입니다. 각각의 역할을 이해하면 더 효과적으로 활용할 수 있습니다.
도구 (Tools)
| 도구 | 설명 |
|---|---|
| Bash | 셸 명령 실행 |
| Read | 파일 읽기 (이미지, PDF, 노트북 포함) |
| Write | 파일 생성/덮어쓰기 |
| Edit | 파일 내 문자열 치환 (부분 수정) |
| Glob | 파일 패턴 검색 (예: **/*.java) |
| Grep | 파일 내용 정규식 검색 |
| Agent | 서브 에이전트 실행 |
| Skill | 등록된 스킬 호출 |
| ToolSearch | 지연 로드된 도구 스키마 조회 |
이 외에 AskUserQuestion, WebFetch, WebSearch, TaskCreate 등의 지연 로드 도구가 필요 시 활성화됩니다.
에이전트 (Agents)
general-purpose
복잡한 멀티스텝 작업, 코드 검색, 리서치 (모든 도구 사용 가능)
Explore
코드베이스 빠른 탐색 — 파일 패턴 검색, 키워드 검색, 구조 파악
Plan
구현 계획 설계 — 아키텍처 분석, 단계별 계획 수립
claude-code-guide
Claude Code/Agent SDK/API 관련 질문 답변
스킬 (Skills)
| 스킬 | 용도 |
|---|---|
| update-config | settings.json 설정 변경 (권한, 환경변수, 훅 등) |
| keybindings-help | 키보드 단축키 커스터마이징 |
| simplify | 변경된 코드의 품질/효율성 리뷰 및 수정 |
| loop | 반복 실행 스케줄링 (예: /loop 5m /foo) |
| claude-api | Claude API / Anthropic SDK 코드 작성 |
| /skill-creator | 커스텀 스킬 생성 |
반복되는 작업이 있을 경우 /skill-creator를 사용하여 커스텀 스킬을 만들 수 있습니다.
Plugin
플러그인은 .claude/ 폴더에 직접 설정하는 것들(skills, hooks, MCP 서버 등)을 하나의 패키지로 묶어서 설치·공유·버전관리 할 수 있게 만든 배포 단위입니다.
아무 플러그인을 막 설치해서 사용하지 말고, 클로드 코드팀이 배포한 공식 플러그인을 위주로 사용하도록 합니다.
공식 플러그인 저장소
anthropics/claude-plugins-official
github.com
Agent & Agent Team
커스텀 에이전트를 만들어 특정 작업을 자동화하고, Agent Team으로 구성하면 TDD 등 복잡한 워크플로우도 자동으로 수행할 수 있습니다.
커스텀 Agent 만들기
/agents 명령으로 새로운 에이전트를 생성할 수 있습니다. 에이전트가 무엇을 하고 언제 사용해야 하는지 상세히 기술하면 됩니다.
Example
코드를 분석해서 품질을 평가하고 리포트를 생성하는 에이전트 — 가독성, 아키텍처, 테스트, 보안 등을 분석하고 점수를 매김
Agent Team
환경변수 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS를 1로 설정하여 활성화합니다. settings.json의 env 필드에서 설정할 수 있습니다.
TDD Team 예시
Red(실패 테스트 작성) → Green(테스트 통과 코드) → Refactor(리팩터링) 사이클을 팀이 자동 수행
생성한 팀을 다른 세션에서도 사용하려면 커스텀 에이전트(스킬)를 구성해야 합니다.