해당 글은 바이브 코딩을 더 효율적으로 하기 위해 공식 문서를 하나씩 읽고 정리하는 글입니다.

참고 자료
https://code.claude.com/docs/en/how-claude-code-works

1. The Agentic Loop

사용자가 task를 주면 세 가지 단계로 일을 수행

1. Gather context

• 문제 해결에 필요한 맥락과 정보를 수집 (예: 코드베이스 파일 읽기, 관련 내용 검색 등)

2. Take action

• 코드를 편집하거나 명령을 실행하는 등 실제 작업을 수행

3. Verify results

• 수행한 작업의 결과를 확인하고, 문제가 해결되었는지 검증

사용자는 중간에 언제든 개입해 지시를 변경하거나 보완할 수 있고, 맥락을 추가할 수 있음

해당 루프는 Models와 Tools를 통해 구동 : 추론하는 모델, 행동하는 도구

Claude Code는 Claude를 감싸는 에이전틱 하네스(구동 프레임) 역할을 함

하니스(Harness)란 원래 말이나 가축을 제어하기 위해 착용하는 ‘마구(馬具)’를 의미합니다. AI 에이전트 맥락에서 하니스는 모델을 감싸서 장기 실행 작업을 신뢰성 있게 관리하는 시스템을 뜻합니다. 쉽게 비유하자면, 모델이 강력한 엔진이라면 하니스는 조향장치, 브레이크, 안전장치를 갖춘 완성된 자동차라고 할 수 있습니다.
출처 - https://leansprint.kr/ai-agent-harness-competitive-advantage-for-startups/

Claude Code는 언어 모델을 coding 에이전트로 만들기 위해 tools, context management and execution environment를 제공함

1-1. Models

언어 모델의 경우 Claude, Sonnet, Opus 등 여러 모델이 있어서 각각 잘하는 거 사용하면 됨

1-2. Tools

툴이 없다면 클로드는 오직 text로만 답함.

툴이 있기 때문에, 클로드는 코드를 읽을 수 있고, 파일을 수정할 수 있고 명령을 실행시킬 수 있음.

각 도구 사용의 결과값으로 Claude는 다음 행동을 판단.

Built-in Tools 의 예시

Category

1. File operations

• read edit, create, rename and reorganize

2. Search

• Find files by pattern, search content with regetx, explore codebases

3. Execution

• Run shell commands, start servers, run tests, use git

4. Web

• Search the web, fetch documentation, look up error maessages

5. Code intelligence

• See types erros and warnings after edits .. (requires code intelligence plugins)

추가적으로 Subagent 생성이나 다른 오케스트레이션 작업 도구들도 있다.

Extending the base capabilities

• skills
• connect to external services with MCP
• automate workflows with hooks
• offload tasks th subagent

What Claude can access

터미널에서 작업할 때 기준으로 클로드 코드는 아래에 접근 권한을 가진다.

• 프로젝트
• 터미널
• 깃
• CLAUDE.md
• Extensions (MCP servers, skills, subagent, Claude in Chrome)

클로드가 inline code assistants 와 다른 점은 프로젝트 전체 파일을 볼 수 있는 것. 이런 장점으로 스스로 문제 해결을 광범위하게 할 수 있다.

Work with sessions

클로드 코드는 작업하는 동안 대화 내용을 로컬에 저장한다. 메시지와, 도구 사용 그리고 결과가 저장되어 세션을 되감기, 재개, 분기 할 수 있다.

클로드 코드는 클로드와 달리 영구적인 기억이 없다. 따라서 세션이 끊어지면 새롭게 시작하여, 이전에 작업한 내용을 알 수 없다. 이전에 작업한 내용을 저장과 같이 특정한 지식을 넣어주기 위해서는 CLAUDE.md를 활용해야 한다.

Work across branches

클로드 코드의 대화 세션은 디렉토리에 연결된다. 즉, 해당 디렉토리 안에서의 대화만 볼 수 있다.

Claude는 현재 브랜치의 파일들을 본다. 브랜치를 전환하면 해당 브랜치의 파일을 볼 수 있다. 하지만 대화는 디렉토리와 연결되어 있기 때문에 히스토리는 그대로 남는다.

git worktrees를 이용해서 병렬 Claude 세션을 실행할 수 있다.

주의할 점

맥락-코드 불일치

• 브랜치가 바뀌면 파일은 바뀌는데, 세션(대화 히스토리)은 같은 디렉터리 안에서는 그대로 이어진다.
  예를 들어, Claude가 이전 대화를 기반으로 “이미 파일에 A가 있다”라고 가정했는데,
  브랜치를 바꿔서 실제 파일엔 A가 없을 수 있다.

“git worktree로 병렬 세션”

git worktree는 브랜치마다 별도 디렉터리를 만들어주는 기능이야.
같은 레포를 “복제”하는데, .git을 통으로 복사하는 게 아니라 공유해서 가볍게 만든다.
예:
• repo/ (main 브랜치 작업용)
• repo-feature-a/ (feature-a 브랜치 전용 worktree)
• repo-hotfix/ (hotfix 브랜치 전용 worktree)

이렇게 하면:
• 디렉터리가 다르니까 Claude 세션도 완전히 분리
• 각 디렉터리는 고정된 브랜치를 체크아웃해 쓰니까 파일도 안 섞임
• 결과: 병렬로 여러 Claude를 돌려도 안전해짐

Resume or fork sessions

세션은 디렉터리 단위로 묶인다.
[현재 디렉터리]
└─ .claude/
└─ sessions/
└─ session-xxxx.json

세션을 continue 하거나, 이 대화를 그대로 다른 시도를 해보고 싶을 때 분기 처리하는 것을 다룬다.

만약 이 대화 그대로 여러 시나리오를 머리 속에 가지고 있다면 fork를 사용한다.

그리고 해당 디렉토리에서 이전 세션을 이어서 하고 싶을 때 resume 또는 continue를 사용한다.

The context window

클로드의 context window는 아래로 구성되어 있다.
1. 대화 이력
2. 파일 내용
3. 명령 결과 (실행 결과)
4. CLAUDE.md
5. loaded skills
6. system instruction

클로드의 context window가 가득 차면 자동으로 compacts 해주지만 초기 instructions은 사라진다.

따라서 지속적인 rules가 필요할 경우 CLAUDE.md에 넣어줄 것

When context fills up

autocompact의 경우 오래된 tool outputs 부터 지운다. 이후 대화가 필요한 경우 요약한다.

요청들과 key code snippets 들은 보존된다. 초기 디테일한 지시사항은 삭제될 수 있다.

만약 complaction에서 어떤 부분을 보존할지를 컨트롤하고 싶다면, 아래처럼!
1. Claude.md에 "Compact Instructions" 섹션을 추가로 넣는 것
2. /compact focus on the API changes - 이렇게 구체적으로 지시하는 방법

Manage context with skills and subagents

compaction 말고도, 컨텍스트 내용을 제어하는 다른 기능들이 있다. compaction은 가득 찼을 때 쓰는 방법이고, 여기서는 필요할 때만 올리는 전략을 말한다.

Skills - 더 공부 필요

스킬은 클로드가 필요할 때 알아서 쓰게 하는 방식이다. 다만 이걸 쓰게 하려면 클로드가 스킬에 대한 설명은 context에 들고 있어야 한다.

set disable-model-invocation: true

이 옵션을 활용하면 내가 필요할 때까지 클로드는 스킬의 존재(설명)도 모르게 할 수 있다.

Subagents

메인 대화와 아예 분리된 새 컨텍스트를 가지는 subagent 활용하는 것

subagent가 작업이 끝나면 필요한 정보만 요약해서 가져온다.

이런 구조 덕분에 특히 긴 세션에서 유리하다.

Stay safe with checkpoints and permissions

클로드는 safety mechanisms이 두 가지 존재한다.

1. checkpoints let you undo file changes
2. permissions control what Claude can do without asking

Undo changes with checkpoints

모든 파일 수정은 reversible하다.

클로드가 파일 수정하기 전 snapshot을 남긴다. 뭔가 잘못되고 있을 땐
1. Esc 두 번 누르면 이전 상태로 돌아갈 수 있다
2. 클로드한테 되돌리라고 말하는 방법도 있다.

Control what Calude can do

모드를 통해서 권한을 다르게 줄 수 있다.

Default: Claude asks before file edits and shell commands
Auto-accept edits: Claude edits files without asking, still asks for commands
Plan mode: Claude uses read-only tools only, creating a plan you can approve before execution

또한, .calude/settings.json 에서 특정 명령을 허락할 수 있다.

Work effectively with Claude Code

1. Ask Claude Code for help

그냥 클로드한테 묻는 방법이다.

예를 들어, what’s the best way to structure my CLAUDE.md?

아래 명령어들도 활용할 수 있다.

/init walks you through creating a CLAUDE.md for your project
/agents helps you configure custom subagents
/doctor diagnoses common issues with your installation

2. It’s a conversation

완벽한 지시가 아니어도 대화를 통해서 풀어나갈 수 있다.

3. Interrupt and steer

잘못된 길로 가고 있으면 중간에 수정해라

4. Be specific up

처음부터 구체적으로 말해라. 초반 지시가 정확할수록, 나중에 고쳐달라고 할 일이 줄어든다.

구체적인 파일을 지목하고, 제약 조건을 명시하고, 참고할 패턴을 알려줘라.

5. Give Claude something to verify against

클로드가 자신을 검증할 수 있게 하라.

test cases, paste screenshots of expected UI,

6. Explore before implementing

실행 이전에 충분히 계획하고 해라.

plan 모드 활용을 적극적으로 하는 것이 더 좋은 결과가 나온다.

plan - implementation 정도로 이해할 수 있다.

This two-phase approach produces better results than jumping straight to code.

7. Delegate, don’t dictate

유능한 동료에게 일을 맡긴다고 생각해라. 상황과 방향만 주고, 세부 사항은 Claude가 알아서 해결하도록 맡겨라.

음.. 지시를 내가 해주는게 좋지 않나..?