Claude Code와 합의서

이 장은 Claude Code가 무엇인지, 어떻게 시작하는지, 작업 전에 어떤 합의서를 쓰는지 다룹니다. 코드를 모르는 실무자도 따라 할 수 있도록 개념과 순서 위주로 설명합니다.

Claude Code란 무엇인가

Claude Code는 내 컴퓨터의 프로젝트 폴더 안에서 파일을 읽고, 수정하고, 명령을 실행하는 Claude입니다. 공식 문서는 이를 코드베이스를 읽고 파일을 편집하며 명령을 실행하는 에이전트형 도구라고 설명합니다(Claude Code 개요, 2026년 11월 기준). 이름에 코드가 들어 있지만 쓰임이 개발에만 한정되지는 않습니다. 폴더 안의 문서를 정리하고, 데이터 파일을 분석하고, 웹페이지를 만드는 일에도 같은 방식으로 씁니다. 3부의 실무 장이 이 방식을 씁니다.

8장의 대화형 Claude와 차이는 이렇습니다.

• 대화형 Claude는 붙이거나 첨부한 내용만 압니다. Claude Code는 폴더 전체를 직접 열어 봅니다.
• 대화형 Claude는 답을 줍니다. Claude Code는 파일을 직접 만들고 고칩니다.
• 그래서 결과가 빠르지만, 잘못 시키면 파일도 잘못 바뀝니다. 이 장의 합의서와 권한 설정이 그 위험을 줄이는 장치입니다.

Claude Code는 터미널, VS Code 같은 편집기, 데스크탑 앱, 웹에서 쓸 수 있고 같은 엔진을 공유합니다. 이 책은 어느 화면을 쓰든 같은 원리로 설명합니다.

GUI와 CLI

Claude Code는 글로 일을 시키는 도구입니다. 이 방식이 왜 힘을 내는지는 화면으로 조작하는 방식(GUI)과 글로 조작하는 방식(CLI, Command Line Interface)을 비교하면 보입니다.

언어 모델은 글로 소통하므로 글로 조작하는 CLI와 잘 맞습니다. 다만 CLI에는 단점이 있습니다. 명령어를 외워야 하고, 무엇을 할 수 있는지 보이지 않으며, 한 글자만 틀려도 실패합니다. Claude Code는 이 단점을 덜어 줍니다. 명령어 대신 평소 말투로 요청하고, "이거 할 수 있어?"라고 물어볼 수 있고, 요청이 모호하면 되물어 줍니다. GUI의 쉬움과 CLI의 범위를 합친 도구라고 보면 됩니다.

설치와 첫 실행

설치 방법은 자주 바뀌므로 공식 문서의 명령을 그대로 따릅니다. 이 책에 명령을 옮겨 적지 않는 이유입니다.

• 설치 안내: Claude Code 개요와 같은 문서의 시작하기 항목
• 터미널이 처음이라면: 공식 문서에 터미널 여는 법부터 안내한 가이드가 있습니다.
• 터미널 없이 시작하려면: 8장의 데스크탑 앱에서 Code 탭을 쓰는 방법이 있습니다. 앱에 Claude Code가 포함되어 있습니다.

설치한 뒤의 기본 흐름은 세 단계입니다.

1. 작업할 폴더를 정합니다. 업무별로 폴더를 따로 둡니다.
2. 그 폴더에서 Claude Code를 시작합니다. 처음에는 로그인 안내가 나옵니다. 본인의 Claude 계정이나 조직에서 안내한 계정으로 로그인합니다.
3. 첫 요청은 읽기 전용으로 시작합니다. 예를 들어 "이 폴더에 어떤 파일이 있는지 설명해 줘"가 좋은 첫 질문입니다.

핵심 첫 세션에서는 아무것도 바꾸지 않는 요청으로 시작합니다. 도구가 폴더를 어떻게 이해하는지 먼저 확인합니다.

합의서: 일을 시키기 전에 쓰는 한 장

일을 맡기기 전에 목표, 제약, 우선순위를 짧은 문서 한 장으로 합의해 두는 것이 합의서입니다. 건축주와 건축가가 도면을 합의한 뒤 짓는 것과 같습니다. 도면 없이 시작하면 중간마다 무엇이 우선인지 다시 협상하게 됩니다.

Claude Code에서 합의서의 실제 파일이 CLAUDE.md입니다. 프로젝트 폴더 맨 위에 두면 Claude Code가 세션을 시작할 때마다 읽습니다. 공식 문서는 CLAUDE.md를 세션마다 불러오는 지속 지침이라고 설명하며, 대화가 새로 시작돼도 이 파일 덕분에 맥락이 이어집니다(기억 관리 문서). 이 책은 CLAUDE.md를 합의서라고 부르겠습니다.

합의서에 들어갈 세 가지

1. 목표: 이 프로젝트에서 결국 얻으려는 것. "분기 보고서 초안을 매달 10분 안에 만든다"처럼 결과로 씁니다.
2. 제약: 어기면 안 되는 규칙. 건드리면 안 되는 폴더, 외부로 보내면 안 되는 정보, 지켜야 할 문체와 형식.
3. 완료 기준: 어떤 상태면 끝인지. "표의 합계가 원본과 일치", "오탈자 검사 통과"처럼 확인 가능하게 씁니다.

필요하면 네 번째로 충돌할 때의 우선순위를 한 줄 더합니다. 예를 들어 "정확성, 일정, 문체 순으로 우선한다"처럼 씁니다.

쓸 때의 규칙

• 짧게 씁니다. 공식 문서는 파일당 200줄 이하를 권하고, 길수록 지침이 잘 지켜지지 않는다고 설명합니다. 일부 영역에만 필요한 규칙은 별도 파일로 나누는 방법이 있습니다.
• 구체적으로 씁니다. "깔끔하게"보다 "표는 4열 이하로"가 따르기 쉽습니다.
• 코드나 폴더를 보면 알 수 있는 것은 적지 않습니다. 보고 알 수 없는 것, 즉 목표, 금지 사항, 용어 약속만 씁니다.
• 합의서는 강제 규칙이 아니라 참고 맥락입니다. 절대 어기면 안 되는 일은 다음 절의 권한 설정으로 막습니다.
• /init 명령으로 초안을 자동 생성할 수 있습니다. 자동 초안은 출발점일 뿐이며 목표와 제약은 사람이 채웁니다.

작업 폴더의 기억

Claude는 어제 한 일을 기억하지 못합니다. 대신 파일에 적어 두면 다음 세션에서도 읽습니다. 합의서 하나에 모든 것을 담지 말고, 역할이 다른 파일 세 개를 둡니다.

• CLAUDE.md: 이 폴더의 규칙(위의 합의서)
• PROGRESS.md: 지금 어디까지 했는지와 다음 시작점. 목표, 상태, 결정, 다음 할 일, 막힌 것의 다섯 칸
• HISTORY.md: 무엇을 왜 그렇게 정했는지 한 줄씩. 되돌아갈 때의 근거

CLAUDE.md 맨 위에 다음 한 줄을 둡니다.

작업을 시작하면 PROGRESS.md와 HISTORY.md를 먼저 읽고, 지금 상태와 다음 할 일을 한 줄로 요약한 뒤 시작한다.

제대로 깔렸는지는 새 세션에서 "이어서 하자" 한마디로 확인합니다. Claude가 PROGRESS.md를 읽고 현재 상태부터 말하면 됩니다. 사용하는 화면에 따라 지침 파일을 읽는 방식이 다를 수 있으므로, 말하지 않는다면 "PROGRESS.md부터 읽어"라고 한 번 시키고 합의서 위치를 점검합니다. 새 일은 새 폴더에서 시작하고 규칙 파일만 옮겨 와 용도에 맞게 고치며, 진행·이유 기록은 새로 만듭니다. 문서 업무에 쓰는 자세한 운영은 16장에서 다룹니다.

권한과 안전: 허용한 것만 실행된다

Claude Code는 파일 수정이나 명령 실행 같은 행동을 하기 전에 허락을 구하는 것이 기본 동작이며, 어디까지 묻지 않고 할지는 권한 모드로 정합니다. 공식 문서의 주요 모드를 간단히 옮기면 다음과 같습니다(2026년 11월 기준, 권한 모드 문서).

이 밖에 모든 것을 허용하는 모드(bypassPermissions)가 있지만, 공식 문서는 격리된 컨테이너나 가상 머신에서만 쓰라고 경고합니다. 실무에서는 쓰지 않는다고 생각하면 됩니다. 터미널에서는 Shift+Tab으로 모드를 순환하고, 데스크탑 앱에서는 입력창 아래의 모드 선택기를 씁니다. 자동 모드는 지원하는 모델과 제공 환경에서만 쓸 수 있고 조직 관리자가 끌 수도 있습니다. 최신 버전의 터미널과 VS Code 세션은 자동 모드로 시작할 수 있습니다. 세션을 열면 화면 하단의 현재 모드부터 확인합니다.

안전을 위한 습관은 다음과 같습니다.

• 허락 창이 뜨면 무엇을 허락하는지 읽고 누릅니다. 눌러 넘기는 습관이 가장 큰 위험입니다.
• 중요한 파일은 작업 전에 복사본을 만들거나 버전 관리를 해 둡니다. 되돌릴 수 있어야 맡길 수 있습니다.
• 비밀번호, API 키, 개인정보 파일이 있는 폴더는 작업 폴더에서 분리합니다.
• 자동 모드도 안전을 보장하지 않습니다. 방향을 믿을 수 있는 작업에만 쓰고, 민감한 작업은 직접 검토합니다.
• 외부 발송이나 삭제처럼 되돌릴 수 없는 행동은 항상 사람이 승인합니다.

먼저 계획하게 하기: 계획 모드

계획 모드에서 Claude Code는 파일을 읽고 조사한 뒤 계획을 제안하며, 계획을 승인하기 전에는 원본 파일을 수정하지 않습니다. 시작할 때 계획 모드로 열 수도 있고 세션 중에 모드를 바꿀 수도 있습니다.

계획을 보면서 확인할 질문은 세 가지입니다.

• 내가 말한 목표와 완료 기준이 계획에 그대로 들어 있는가
• 건드리지 말라고 한 것을 건드리려 하지 않는가
• 계획의 단계 중 이해되지 않는 단계가 있는가

이해되지 않는 단계가 있으면 승인하지 않고 설명을 요구합니다.

계획의 깊이: No plan, Local plan, Two-pass

모든 일에 같은 무게의 계획을 붙이면 단순한 일은 느려지고, 복잡한 일에 계획이 없으면 되돌릴 일이 쌓입니다. 액티전스 사용설명서는 일의 크기에 따라 계획의 깊이를 세 단계로 나눕니다.

• No plan: 한두 문장으로 설명되고 영향받는 파일이 분명한 일. 오탈자 수정이나 간단한 정리입니다. 바로 시킵니다.
• Local plan: 몇 개 파일이 바뀌지만 한 영역 안에서 끝나는 일. 계획 모드로 계획을 먼저 받고 승인합니다.
• Two-pass: 여러 영역에 걸치거나 구조 변경, 되돌리기 어려운 일. 첫 계획을 받은 뒤 한 번 더 별도로 검토합니다. 19장에서 자세히 다룹니다.

파일 수보다 되돌리기 어려운 정도가 더 중요한 기준입니다. 경계가 애매하면 한 단계 위로 올립니다. 과한 계획으로 잃는 것은 시간이고, 부족한 계획으로 잃는 것은 결과물 자체일 수 있기 때문입니다.

실습

작은 프로젝트의 CLAUDE.md 초안 만들기

업무 폴더 하나를 정하고(예: 월간 보고서 작성) 그 폴더에서 Claude Code를 시작합니다. 아래 프롬프트로 합의서 초안을 받습니다. 대괄호를 채워 쓰십시오. 합의서는 사람이 읽고 확정합니다.

이 폴더는 [업무 이름]을 위한 프로젝트 폴더야. 폴더 안 파일을 먼저 읽고 어떤 자료가 있는지 파악해 줘. 아직 아무 파일도 수정하지 마.
그다음 이 프로젝트의 CLAUDE.md 초안을 만들어 줘. 구성은 다음과 같아.
1) 목표: [이 업무에서 얻으려는 결과]
2) 제약: 건드리면 안 되는 파일과 폴더, 외부로 보내면 안 되는 정보, 지켜야 할 문체
3) 완료 기준: 확인 가능한 문장으로 3개
4) 충돌할 때의 우선순위: 한 줄
60줄 이내로 쓰고, 내가 말하지 않은 사실을 지어내지 마. 모르는 항목은 [확인 필요]로 표시해 줘.
초안을 보여 주고, 내 승인 후에만 CLAUDE.md 파일로 저장해 줘.

저장한 뒤 새 세션을 열어 "이 프로젝트의 목표와 제약을 요약해 줘"라고 물어봅니다. 합의서가 읽혔는지 확인하는 방법입니다.

선택 과제. 파일 이름 일괄 변경으로 CLI의 범위 느끼기

연습용 폴더에 가상의 파일(예: 사진 22장)을 복사해 두고 시킵니다. 원본은 건드리지 않도록 복사본 폴더에서만 합니다.

이 폴더의 파일 이름을 [날짜_번호] 형식으로 바꾸려고 해. 바꾸기 전에 현재 이름과 새 이름을 표로 먼저 보여 주고, 내가 확인하면 실행해 줘. 되돌릴 수 있도록 원래 이름 목록도 파일로 남겨 줘.

한 줄로 수십 개가 바뀌는 속도와, 실행 전에 표로 확인하는 절차의 필요를 함께 느껴 보는 것이 목적입니다.

정리

• Claude Code는 프로젝트 폴더 안에서 파일을 읽고 쓰고 명령을 실행하는 Claude이며, 글로 조작하는 CLI의 범위를 쉬운 말투로 열어 줍니다. 설치는 공식 문서의 안내를 따릅니다.
• 합의서(CLAUDE.md)에는 목표, 제약, 완료 기준을 짧고 구체적으로 쓰고, 진행(PROGRESS.md)과 결정 이유(HISTORY.md)는 따로 적어 다음 세션이 이어받게 합니다.
• 합의서는 참고 맥락이므로, 절대 막아야 하는 일은 권한 설정과 사람의 승인으로 지킵니다.
• 바꾸기 전에는 계획 모드로 계획을 받아 확인하고, 일의 크기에 따라 계획의 깊이를 정합니다.
• 첫 세션은 읽기 전용 요청으로 시작하고, 중요한 파일은 되돌릴 수 있게 해 둡니다.