Claude Code Roadmap

https://roadmap.sh/claude-code

SI에서 Nextjs 첫 프로젝트 반성 및 후기 에서 Nextjs 프로젝트 아키텍쳐를 담당하며 ai의 도움을 많이 받았다. 가장 고민했었던 부분은 최대한의 개발속도를 확보하기 위해 어떻게 레거시한 베이들을 건드리지 않고 Nextjs를 최대한 React 스럽게 개발할 수 있을까? 였고 여기서 파생되는 고민들에 대해서 Cursor와 Claude cli가 정말 큰 도움이 되었다.

그렇다면 ai를 더 잘 쓰는 방법은 무엇일까? 사용하면서 가장 유용했던 Claude code에 대해 더 알아보고 정리하려고 한다.

Vibe coding vs Agentic Coding

내가 사용했던 방법(Nextjs의 경우)

• 레거시 CRA 코드베이스(대부분 css 및 기능 구현을 위한 레거시 라이브러리)를 유지하며 나머지는 최신 Nextjs 15~16으로 구현해야 함.
• Nextjs 개념 학습 이후 도식화된 다이어그램을 통해 필요사항 구체화
• 코드 use-case 스니펫으로 정립.

이 과정에서 여러 use-case를 정립하는 과정에서 ai 툴이 큰 도움이 되었다.

1. 유지해야 하는 레거시 베이스와 새롭게 추가해야 하는 Nextjs 유즈케이스를 구분하는 것이 도움이 되었음.
2. 영어로 프롬프트를 쓰는 것이 가장 도움이 되었음.

1. Claude code

소개

https://code.claude.com/docs/en/overview

Claude Code는 에이전틱 코딩 툴로 당신의 코드베이스를 읽고 수정하고 커맨드를 실행시키는 등 당신의 개발 환경과 함께 사용할 수 있습니다. 터미널, IDE, 데스크탑 앱, 브라우저에서 사용 가능합니다. 기능을 개발하거나 버그를 고치거나 개발을 자동화시키는 용도로 사용할 수 있습니다. 태스크를 완료하기 위해 여러 파일과 툴을 함께 사용합니다.

바이브 코딩이란?

[Vibe coding vs Agentic Coding](/docs/needsReview/Vibe coding vs Agentic Coding)

코딩 에이전트란

코딩 에이전트란 어떠한 프로그래밍적 태스크를 위해 독립적으로 수정, 테스트, 디버깅을 수행하는 엔티티를 말합니다. 하나 이상의 AI 테크닉을 사용해 요구사항을 이해하고 스니펫을 만들거나 에러를 판별하거나 iteration을 통해 문제를 해결합니다.

에이전틱 루프란?

에이전틱 루프란 코딩 에이전트가 문제를 해결하기 위해 인식, 플래닝, 액션의 단계를 반복하는 것을 말합니다. 에이전트가 독립적으로 목표를 설정하고 현재 상황을 인식하며 액션을 수행하고 평가하는것 까지를 말합니다.

클로드 CLI 세팅하기

// claude cli 설치
// macos, wsl
curl -fsSL https://claude.ai/install.sh | bash
// powershell
irm https://claude.ai/install.ps1 | iex

사용법

https://automaker.app/

Claude 기본적인 사용 법

Claude code는 여러가지 개발 용도로 사용할 수 있습니다. 레거시 시스템 리팩토링 및 현대화나 빠른 프로토타이핑과 같은 경우입니다. 100만줄 이상의 코드도 이해할 수 있습니다. 일상적으로는 유닛 테스팅 자동화, 복잡한 버그 진단 및 리포의 전체 업데이트와 같은 경우에 활용할 수 있습니다. 인프라스트럭처 자동화에도 사용 가능합니다. Kubernetes 클러스터 관리, 모니터링 시스템 관리, CI/CD 파이프라인 등을 자연어로 요청해서 처리 가능합니다.

어떻게 사용하는지?

베스트 프렉티스

Claude.md

https://code.claude.com/docs/en/best-practices#write-an-effective-claude-md

CLAUDE.md란 클로드가 모든 대화를 시작하기 전 읽는 텍스트입니다. 유저는 프로젝트에 대한 정보, 코드 스타일, 워크 플로우 룰을 여기서 지정해 줄 수 있습니다. /init 커맨드를 통해 코드베이스가 빌드, 테스트 프레임워크, 패턴 등을 파악하도록 할 수 있습니다. CLAUDE.md는 모든 세션이 시작될 때 로딩 됩니다. 어떤 특수한 케이스에 대해서는 skills를 사용해 주세요. 하지만 너무 많은 내용을 적는 것은 좋지 않습니다. 실제 지시를 잊어버릴 수 있습니다. 만약 잘못된 결과가 나온다면 CLAUDE.md 내용을 줄여 주세요. "IMPORTANT"나 "YOU MUST"라는 표현을 써서 반드시 지켜야 할 룰들을 지정할 수 있습니다.

//./CLAUDE.md
# CLAUDE.md



## CRITICAL MANDATORY RULES - READ FIRST



## CRITICAL: NO MOCK DATA/ no fall back POLICY

## CRITICAL RULES - READ FIRST

1. **ALWAYS read CLAUDE.md** at before ANY work
2. **ALWAYS search files in the codebase** EVERY SINGLE TIME before proceeding
3. **ALWAYS follow the workflow**: ANALYZE → REUSE → VALIDATE → INTEGRATE
4. **ALWAYS follow**: Research → Plan → Implement (NEVER jump to coding)

## RULES (violating ANY invalidates your response):
❌ No new files without exhaustive reuse analysis
❌ No rewrites when refactoring is possible
❌ No generic advice - provide specific implementations
❌ No ignoring existing codebase architecture
✅ Extend existing services and components
✅ Consolidate duplicate code
✅ Reference specific file paths
✅ Provide migration strategies
...

@path/to/import을 통해 추가적인 내용을 임포트할 수 있습니다.

See @README.md for project overview and @package.json for available npm commands.

# Additional Instructions
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md

https://www.reddit.com/r/ClaudeAI/comments/1m3pol4/my_best_workflow_for_working_with_claude_code/

Skills

https://code.claude.com/docs/en/skills

Skills를 통해 Claude를 확장해서 사용할 수 있습니다. 어떤 특정한 액션을 수행해야 할 때, SKILL.md 파일에 해당 액션을 기록하고 /skill-name 커맨드를 통해 해당 액션을 수행할 수 있도록 할 수 있습니다.

use-case https://www.reddit.com/r/ClaudeAI/comments/1og1gdx/now_that_were_one_week_into_the_claude_skills/

Context

https://code.claude.com/docs/en/how-claude-code-works#the-context-window

컨텍스트 윈도우는 당신의 대화 내역 및 수정 사항을 기억합니다. CLAUDE.md 파일을 기록하고 /context 커맨드를 통해 해당 룰을 기억하고 있는지 확인할 수 있습니다. 컨텍스트는 저장용량이 남는 동안 계속 대화 내역을 기억합니다. 꽉 차게 되면 오래된 내용부터 삭제되기 때문에 계속해서 유지되어야 하는 기억은 CLAUDE.md를 통해 기록하세요. /compact 커맨드를 통해 특정한 지시에 집중하게 할 수 있습니다. /compact focus on the API changes /mcp 커맨드는 MCP 서버의 상태를 보여줍니다.

Permissions

https://code.claude.com/docs/en/permissions

클로드 코드에게 특정한 권한을 줘서 실행할 수 있습니다. 지정하지 않는다면 작업을 수행하면서 에이전트가 유저에게 어떤 권한을 실행시킬 것인지 물어볼 것입니다.

Tools

https://code.claude.com/docs/en/how-claude-code-works#tools

에이전틱 코딩에 사용됩니다. 툴이 없다면 클로드는 오직 텍스트로만 답변할 수 있으며 툴을 통해 파일을 읽고 수정하고 커맨드를 실행하는 등의 액션을 수행할 수 있습니다. 에이전틱 루프에 필수적인 개념입니다.

MCP

https://code.claude.com/docs/en/mcp

Model Context Protocol 을 통해서 Claude는 외부의 여러 툴과 데이터 소스에 접속할 수 있습니다.툴, 데이터베이스, api등 모두요.

• 이슈 트래커와 연결 지라 4521 이슈를 해결해서 github에 pr 해주세요
• 모니터링 데이터와 연결 - Sentry와 Statsig에 연결해서 4521 기능의 사용량을 확인해주세요
• 데이터베이스 쿼리 - 4521 기능을 사용하는 랜덤한 유저 10명의 이메일을 postgre db에서 뽑아주세요
• 디자인과 연결 - 슬랙에 올라온 새 피그마 디자인을 보고 템플릿으 업데이트 해주세요
• 워크플로우 자동화 - 해당 10명의 유저를 업데이트 테스트 참여 이메일을 보내주세요

Plugin

https://code.claude.com/docs/en/discover-plugins

플러그인은 클로드 코드에서 사용할 수 있는 새로운 커맨드, 에이전트 및 기능을 제공합니다. 마켓플레이스에서 찾거나 직접 만들어서 마켓플레이스에 올릴 수 있습니다. 공식 클로드 플러그인 마켓플레이스는 /plugin 커맨드를 통해 접근해서

/plugin install plugin-name@claude-plugins-official

를 통해 설치할 수 있습니다.

Hooks

https://code.claude.com/docs/en/hooks-guide

hook 이란 유저가 지정하는 쉘 커맨드입니다. 클로드 코드가 어떤 액션을 수행할 때 그 뒤에 추가로 어떤 일을 하는지 지정할 수 있습니다. 코드를 수정한 뒤 포맷을 실행한다거나, 테스트 후 git 에 커밋한다거나 할 수 있습니다. /hooks 커맨드를 통해 접근할 수 있습니다.

Subagents

https://code.claude.com/docs/en/sub-agents

Subagents란 특정한 태스크를 해결하기 위해 존재하는 전문화된 ai 에이전트입니다. 기존 컨텍스트와는 다른 컨텍스트 윈도우를 가지고 있어서 자신의 역할에만 집중하게 됩니다. 클로드 코드가 어떤 특정한 태스크를 해결해야 한다면 자동으로 서브에이전트를 로드해서 해당 작업을 수행하게 됩니다.

여기서부터 Advanced

용어집