Claude Code 베스트 프랙티스

생각 덩어리

Claude Code는 챗봇이 아니다 — 자율 에이전트다

Claude Code is an agentic coding environment. Unlike a chatbot that answers questions and waits, Claude Code can read your files, run commands, make changes, and autonomously work through problems while you watch, redirect, or step away entirely.

Instead of writing code yourself and asking Claude to review it, you describe what you want and Claude figures out how to build it. Claude explores, plans, and implements.

모든 베스트 프랙티스의 근원 — 컨텍스트 창은 가장 귀한 자원

Most best practices are based on one constraint: Claude's context window fills up fast, and performance degrades as it fills.

This matters since LLM performance degrades as context fills. When the context window is getting full, Claude may start "forgetting" earlier instructions or making more mistakes. The context window is the most important resource to manage.

검증 수단을 먼저 쥐어줘라 — 가장 큰 레버리지

Include tests, screenshots, or expected outputs so Claude can check itself. This is the single highest-leverage thing you can do.

Claude performs dramatically better when it can verify its own work, like run tests, compare screenshots, and validate outputs.

Without clear success criteria, it might produce something that looks right but actually doesn't work. You become the only feedback loop, and every mistake requires your attention.

Explore → Plan → Implement → Commit

Four-phase workflow:

1. Explore: Enter Plan Mode. Claude reads files and answers questions without making changes.
2. Plan: Ask Claude to create a detailed implementation plan.
3. Implement: Switch back to Normal Mode and let Claude code, verifying against its plan.
4. Commit: Ask Claude to commit with a descriptive message and create a PR.

계획이 필요 없는 경우는 과감히 건너뛰어라

For tasks where the scope is clear and the fix is small (like fixing a typo, adding a log line, or renaming a variable) ask Claude to do it directly.

Planning is most useful when you're uncertain about the approach, when the change modifies multiple files, or when you're unfamiliar with the code being modified. If you could describe the diff in one sentence, skip the plan.

구체적 맥락이 교정 횟수를 줄인다

Claude can infer intent, but it can't read your mind. Reference specific files, mention constraints, and point to example patterns.

Before: "add tests for foo.py" After: "write a test for foo.py covering the edge case where the user is logged out. avoid mocks."

Before: "fix the login bug" After: "users report that login fails after session timeout. check the auth flow in src/auth/, especially token refresh. write a failing test that reproduces the issue, then fix it"

모호한 프롬프트도 쓸모가 있다

Vague prompts can be useful when you're exploring and can afford to course-correct. A prompt like "what would you improve in this file?" can surface things you wouldn't have thought to ask about.

CLAUDE.md — 세션마다 읽히는 지속 컨텍스트

CLAUDE.md is a special file that Claude reads at the start of every conversation. Include Bash commands, code style, and workflow rules. This gives Claude persistent context it can't infer from code alone.

CLAUDE.md는 짧게 — 매 줄을 심사하라

Keep it concise. For each line, ask: "Would removing this cause Claude to make mistakes?" If not, cut it. Bloated CLAUDE.md files cause Claude to ignore your actual instructions!

If Claude keeps doing something you don't want despite having a rule against it, the file is probably too long and the rule is getting lost.

포함 vs 제외 — 추려야 할 것

Include:

• Bash commands Claude can't guess
• Code style rules that differ from defaults
• Testing instructions and preferred test runners
• Repository etiquette (branch naming, PR conventions)
• Architectural decisions specific to your project
• Developer environment quirks (required env vars)
• Common gotchas or non-obvious behaviors

Exclude:

• Anything Claude can figure out by reading code
• Standard language conventions Claude already knows
• Detailed API documentation (link to docs instead)
• Information that changes frequently
• Self-evident practices like "write clean code"

Hooks — 조언이 아니라 결정론적 보장

Hooks run scripts automatically at specific points in Claude's workflow. Unlike CLAUDE.md instructions which are advisory, hooks are deterministic and guarantee the action happens.

권한 관리 세 가지 전략

Auto mode: a separate classifier model reviews commands and blocks only what looks risky: scope escalation, unknown infrastructure, or hostile-content-driven actions.

Permission allowlists: permit specific tools you know are safe, like npm run lint or git commit

Sandboxing: enable OS-level isolation that restricts filesystem and network access, allowing Claude to work more freely within defined boundaries

큰 기능은 Claude가 당신을 인터뷰하게 하라

I want to build [brief description]. Interview me in detail using the AskUserQuestion tool. Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered. Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.

Once the spec is complete, start a fresh session to execute it. The new session has clean context focused entirely on implementation, and you have a written spec to reference.

두 번 이상 같은 교정을 반복했다면 /clear

If you've corrected Claude more than twice on the same issue in one session, the context is cluttered with failed approaches. Run /clear and start fresh with a more specific prompt that incorporates what you learned. A clean session with a better prompt almost always outperforms a long session with accumulated corrections.

서브에이전트 — 맥락이 자원이라면 가장 강력한 도구

Since context is your fundamental constraint, subagents are one of the most powerful tools available. When Claude researches a codebase it reads lots of files, all of which consume your context. Subagents run in separate context windows and report back summaries.

체크포인트가 있으면 위험한 시도를 해라

Instead of carefully planning every move, you can tell Claude to try something risky. If it doesn't work, rewind and try a different approach.

병렬 세션 — Writer/Reviewer 패턴

Beyond parallelizing work, multiple sessions enable quality-focused workflows. A fresh context improves code review since Claude won't be biased toward code it just wrote.

흔한 실패 패턴들

The kitchen sink session:

You start with one task, then ask Claude something unrelated, then go back to the first task. Context is full of irrelevant information.

Correcting over and over:

Claude does something wrong, you correct it, it's still wrong, you correct again. Context is polluted with failed approaches.

The over-specified CLAUDE.md:

If your CLAUDE.md is too long, Claude ignores half of it because important rules get lost in the noise.

The trust-then-verify gap:

Claude produces a plausible-looking implementation that doesn't handle edge cases.

The infinite exploration:

You ask Claude to "investigate" something without scoping it. Claude reads hundreds of files, filling the context.

직관은 규칙을 이긴다

Sometimes you should let context accumulate because you're deep in one complex problem and the history is valuable. Sometimes you should skip planning and let Claude figure it out because the task is exploratory. Sometimes a vague prompt is exactly right because you want to see how Claude interprets the problem before constraining it.

Over time, you'll develop intuition that no guide can capture. You'll know when to be specific and when to be open-ended, when to plan and when to explore, when to clear context and when to let it accumulate.