메뉴
HN
Hacker News • 4일 전

일상 개발 도구로 쓰는 클로드 코드: 완벽 가이드

IMP
8/10
핵심 요약

Anthropic의 터미널 기반 코딩 에이전트인 클로드 코드(Claude Code)를 단순한 챗봇이 아닌 자율적인 프로그래밍 에이전트로 활용하는 심화 가이드입니다. 핵심은 에이전트 스스로 자신의 작업을 검증할 수 있는 피드백 루프를 구축하고, CLAUDE.md를 통해 규칙을 학습시키며, 폴더 구조를 이해해 프로젝트 단위의 설정을 분리하는 워크플로우 구축에 있습니다.

번역된 본문

목차

  1. 기본기를 넘어선 클로드 코드(Claude Code)
  2. .claude 디렉토리에 대한 정확한 이해
  3. 클로드 코드 팀이 작성하는 CLAUDE.md 방식 3.1 클로드 코드 팀의 실제 CLAUDE.md 3.2 공부해볼 만한 인기 CLAUDE.md 파일들
  4. 일상적인 개발 도구로서의 CLAUDE.local.md
  5. 스킬(Skills) 심화 5.1 스킬의 실체 5.2 실제 스킬 작성하기: Go API 컨벤션 5.3 설치해볼 만한 인기 스킬들
  6. 맞춤형 서브에이전트(Subagents) 구축 6.1 /pr-review 에이전트 둘러보기 6.2 가져다 쓰기 좋은 인기 서브에이전트들
  7. 플러그인(Plugins)과 마켓플레이스
  8. 제대로 활용되지 않는 클로드 코드 명령어들 8.1 내장된 랠프 루프(Ralph Loop), /goal
  9. 강력한 도구, MCPs 9.1 실제 옵시디언(Obsidian) 워크플로우
  10. 일상적인 워크플로우 최적화
  11. Anthropic 팀의 팁
  12. 리소스 맺음말

클로드 코드는 가벼운 마음으로 접하는 사용자와 이 도구를 내재화한 사람 사이의 격차가 엄청나게 큰 도구 중 하나입니다. 가벼운 사용자는 프롬프트를 입력하고 제안을 수락하며, 이를 단지 더 고급스러운 자동완성 정도로 취급합니다. 반면, 일상 개발 도구로 활용하는 사용자는 이를 메모리, 맞춤형 명령어, 병렬 세션, 그리고 시간이 지남에 따라 복리로 쌓이는 프로젝트 설정을 갖춘 프로그래밍 가능한 에이전트처럼 다룹니다. 이 가이드는 터미널에 claude를 입력했을 때 어떤 일이 일어나는지 이미 알고 있다고 가정하고, 두 번째 유형의 사용자를 위해 작성되었습니다.

  1. 기본기를 넘어선 클로드 코드 # 클로드 코드를 프롬프트를 입력하고 기다리는 챗봇으로 생각하는 것을 멈추고, 가드레일이 필요한 자율 에이전트로 취급하기 시작하면 여러분의 워크플로우는 완전히 바뀝니다. 보리스 체르니(Boris Cherny)와 Anthropic 팀이 강조하는 가장 중요한 원칙은 바로 '클로드가 스스로 자신의 작업을 검증할 수 있는 방법을 제공하라'는 것입니다. 이것이 없다면 여러분이 유일한 피드백 루프가 됩니다. 이것이 있다면 클로드는 제대로 작동할 때까지 스스로 반복하며, 보리스는 이것만으로도 품질이 2~3배 향상된다고 말합니다. 일상적인 작업 방식을 바꾸는 몇 가지 패턴은 다음과 같습니다:

탐색하고, 계획하고, 코딩하세요. 계획 모드(Shift+Tab 두 번)는 클로드를 읽기 전용 탐색 모드로 전환합니다. 파일을 읽고, 흐름을 추적하고, 데이터 모델을 이해합니다. 그다음 계획을 세우고 실행합니다. 사소한 수정에는 계획을 건너뛰고, 두 개 이상의 파일을 건드리는 작업에는 계획을 사용하세요.

계획 모드를 설계 문서처럼 활용하세요. 한 클로드 세션에서 계획을 작성한 다음, 컨텍스트 편향 없이 수석 엔지니어처럼 계획을 검토하기 위해 완전히 새로운 세션에서 두 번째 클로드를 실행하여 실제로 빈틈을 찾아내도록 하세요. 구현이 어긋나면 계획 모드로 돌아가서 검증 단계를 포함하여 다시 계획하세요.

설명 대신 참조하세요. "인증 모듈을 봐"라고 말하는 대신 @src/auth/login.py를 입력하세요. 에러를 복사해서 붙여넣는 대신 파이프로 연결하세요: cat error.log | claude. 정확한 컨텍스트는 대략적인 설명을 항상 이깁니다.

페어 프로그래밍 대신 위임하세요. 클로드 코드 팀의 캣 우(Cat Wu)는 "모델을 한 줄씩 안내하는 페어 프로그래머가 아니라, 작업을 위임하는 엔지니어처럼 대할 때 가장 좋은 성능을 발휘합니다."라고 말합니다. 처음에 명확한 지시를 내리고, 그 다음에는 알아서 진행하게 두세요.

계획 편집 팁: Ctrl+G를 눌러 클로드가 진행하기 전에 에디터에서 계획을 열고 수정하세요. 계획은 단순한 텍스트이므로 코드가 되기 전에 내용을 조정하면 됩니다.

자가 교정 습관: 클로드가 실수를 했을 때, 프롬프트 끝에 "같은 실수를 반복하지 않도록 CLAUDE.md를 업데이트해."라고 추가하세요. 보리스는 클로드가 자신의 실패로부터 스스로 규칙을 작성하는 데 '놀라울 정도로 뛰어나다'고 말합니다. 이 습관은 이 가이드의 그 어느 것보다 큰 복리 효과를 냅니다.

  1. .claude 디렉토리에 대한 정확한 이해 # 대부분의 사람들은 .claude/를 한 번 열어보고, CLAUDE.md만 확인한 뒤 더 이상 살펴보지 않습니다. 하지만 이것은 실제로 계층화된 구성 시스템입니다.

두 가지 범위가 있습니다: 프로젝트 범위는 리포지토리 내의 .claude/에 위치하며 git에 커밋되어 팀이 공유합니다. 전역 범위는 ~/.claude/에 위치하며 컴퓨터의 모든 프로젝트에 적용됩니다.

참고: 프로젝트 파일은 프로젝트를 설명하고, 전역 파일은 사용자(당신)를 설명한다고 생각하시면 됩니다.

파일 | 범위 | 커밋 여부 | 역할 CLAUDE.md | 프로젝트 및 전역 | 예 | 매 세션마다 로드되는 지시사항 CLAUDE.local.md | 프로젝트 전용 | 아니요 (gitignore 처리) | 개인적인 프로젝트 메모 settings.json | 프로젝트 및 전역 | 예 | 권한, 훅(hooks), 환경 변수, 모델 기본값 settings.local.json | 프로젝트 전용 | 아니요 | 개인 설정 오버라이드, 자동으로 gitignore 처리됨 .mcp.json | 프로젝트 전용

원문 보기
원문 보기 (영어)
Table of Contents 1. Claude Code Beyond the Basics 2. The .claude Directory, Properly Understood 3. CLAUDE.md, The Way Boris Writes It 3.1 The Real CLAUDE.md From the Claude Code Team 3.2 Popular CLAUDE.md Files Worth Studying 4. CLAUDE.local.md as a Daily Driver 5. Skills, In Depth 5.1 What Skills Actually Are 5.2 Writing a Real Skill: Go API Conventions 5.3 Popular Skills Worth Installing 6. Building Custom Subagents 6.1 Walking Through a /pr-review Agent 6.2 Popular Subagents Worth Stealing 7. Plugins and the Marketplace 8. Underused Claude Code Commands 8.1 /goal, the Ralph Loop Built In 9. MCPs as Power Tools 9.1 A Real Obsidian Workflow 10. Optimizing Your Daily Workflow 11. s From the Anthropic Team 12. Resources Closing Notes Claude Code is one of those tools where the difference between a casual user and someone who has internalized it is enormous. The casual user types prompts, accepts suggestions, and treats it like a fancier autocomplete. The daily driver uses it like a programmable agent with memory, custom commands, parallel sessions, and a project setup that compounds over time. This guide is for the second kind of person, assuming you already know what claude does when you type it in a terminal. 1. Claude Code Beyond the Basics # Once you stop thinking of Claude Code as a prompt-and-wait chatbot and start treating it as an autonomous agent that needs guardrails, your workflow shifts. The single most important principle from Boris Cherny and the Anthropic team: give Claude a way to verify its own work . Without that, you are the only feedback loop. With it, Claude iterates until things actually work, and Boris says this alone gives a 2-3x quality improvement. A few patterns that change how you operate day to day: Explore, then plan, then code. Plan mode ( Shift+Tab twice) puts Claude into read-only exploration. Read files, trace flows, understand the data model. Then get a plan. Then execute. Skip planning for small fixes; use it for anything touching more than one file. Use plan mode like a design document. Have one Claude write the plan, then spin up a second Claude in a fresh session to review it as a staff engineer, with no context bias, so it actually catches gaps. If implementation goes sideways, go back to plan mode and re-plan with verification steps included. Reference, do not describe. Instead of &ldquo;look at the auth module&rdquo;, type @src/auth/login.py . Instead of pasting an error, pipe it: cat error.log | claude . Exact context beats approximate description every time. Delegate, do not pair-program. Cat Wu (Claude Code team): &ldquo;The model performs best if you treat it like an engineer you&rsquo;re delegating to, not a pair programmer you&rsquo;re guiding line by line.&rdquo; Write a crisp brief upfront, then let it run. : Press Ctrl+G to open Claude&rsquo;s plan in your editor and tweak it before Claude proceeds. The plan is just text, so shape it before it becomes code. : When Claude makes a mistake, end your prompt with &ldquo;Update CLAUDE.md so you do not repeat this.&rdquo; Boris calls Claude &ldquo;eerily good at writing rules for itself&rdquo; from its own failures. This habit compounds more than any other in this guide. 2. The .claude Directory, Properly Understood # Most people open .claude/ once, see CLAUDE.md , and never look further. It is actually a layered configuration system. Two scopes: Project scope lives in .claude/ inside your repo, committed to git so your team shares it. Global scope lives in ~/.claude/ and applies across every project on your machine. Mental model: project files describe the project, global files describe you. File Scope Commit What it does CLAUDE.md Project and global Yes Instructions loaded every session CLAUDE.local.md Project only No, gitignore it Your private project notes settings.json Project and global Yes Permissions, hooks, env vars, model defaults settings.local.json Project only No Personal overrides, auto-gitignored .mcp.json Project only Yes Team-shared MCP servers skills/<name>/SKILL.md Project and global Yes Reusable prompts invoked with /name commands/*.md Project and global Yes Single-file slash commands agents/*.md Project and global Yes Subagent definitions rules/*.md Project and global Yes Topic-scoped instructions, optionally path-gated A typical layout: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 my-repo/ ├── .claude/ │ ├── settings.json │ ├── agents/ │ │ ├── pr-review.md │ │ └── test-writer.md │ ├── skills/ │ │ └── api-conventions/SKILL.md │ └── rules/ │ ├── frontend.md # path-gated to src/frontend/ │ └── migrations.md # path-gated to db/migrations/ ├── CLAUDE.md # checked in, team-shared ├── CLAUDE.local.md # gitignored, personal └── .mcp.json # team-shared MCP servers A few things easy to miss: CLAUDE.md files cascade. In a monorepo, both root/CLAUDE.md and root/services/billing/CLAUDE.md load when you work in the billing service. Powerful for codebases with different conventions per folder. rules/*.md is path-gated. Guidance specific to your migrations folder does not belong in CLAUDE.md bloating every session; it belongs in .claude/rules/migrations.md with a glob. Skills over commands. .claude/commands/*.md and .claude/skills/<name>/SKILL.md both create slash commands, but skills support supporting files, disable-model-invocation , allowed tools, and agent overrides. New work should go in skills/ . : Run claude project purge ~/path/to/repo --dry-run to see exactly what local state Claude holds for a project, handy before handing off a laptop. 3. CLAUDE.md, The Way Boris Writes It # CLAUDE.md is loaded at the start of every session. Get it wrong and Claude repeats the same mistakes. Get it right and the same prompt produces dramatically better output. Boris is direct about two things that matter more than the rest: Keep it short. Long files bury important rules. For every line, ask: &ldquo;Would removing this cause Claude to make a mistake?&rdquo; If not, cut it. Let Claude write rules for itself. Any time Claude does something wrong, tell it: &ldquo;Update CLAUDE.md so you do not repeat this.&rdquo; Claude is surprisingly good at distilling its own mistakes into precise rules. Do this for a few weeks and the file becomes a curated list of every gotcha your project has. 3.1 The Real CLAUDE.md From the Claude Code Team # Boris has shared the actual CLAUDE.md the Claude Code team checks into their own repo. The whole team contributes mulle times a week: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 # Development Workflow **Always use `bun`, not `npm`.** # 1. Make changes # 2. Typecheck (fast) bun run typecheck # 3. Run tests bun run test -- -t &#34;test name&#34; # Single suite bun run test:file -- &#34;glob&#34; # Specific files # 4. Lint before committing bun run lint:file -- &#34;file1.ts&#34; bun run lint # 5. Before creating PR bun run lint:claude && bun run test That is the entire file. Build commands Claude cannot guess, the exact order to run things, single-test invocations, the pre-PR ritual. No style preferences. No codebase tours. No platitudes. Boris also uses @claude in PR comments to have Claude commit a rule directly: 1 2 nit: use a string literal, not a ts enum @claude add to CLAUDE.md to never use enums, always prefer literal unions He calls this &ldquo;Compounding Engineering,&rdquo; where every PR review becomes a CLAUDE.md improvement. A fleshed-out template following the same philosophy: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 # Code style - Use ES modules (import/export), not CommonJS (require) # Workflow - Always use `bun` , not `npm` - Run `bun run typecheck` before claiming done - Never push to main directly. Always open a PR. # Architecture - All API routes go through src/api/middleware/auth.ts - New database queries go in src/db/queries/. No inline raw SQL. # Gotchas - `User` and `UserRecord` are distinct types. UserRecord is the DB row, User is the runtime object. - `formatCurrency` assumes USD. For internatio
클로드 코드 코딩 에이전트 워크플로우 최적화 Anthropic 개발자 도구