준비: 기본 설정

왜 미리 갖추는가

본 실습은 설정 파일이 어디 있고 무엇을 하는지 안다고 가정합니다. 여기서 한 번 확인해 두면 6단계(규칙을 강제로)와 7단계(병렬 작업)에서 헤매지 않습니다.

이 단계에서 하는 것

버전을 확인하고, 설정 파일 4종의 위치를 확인하고, 퍼미션 모드를 정하고, 본 실습에서 쓸 기록표 형식을 확정합니다. 각 선택의 근거는 나의 기본 세팅과 권한 정책에 있습니다.

따라하기

1. 버전을 확인하고 최신으로 맞춥니다.

claude --version
claude update

2. 설정 파일 4종의 역할을 확인합니다. 이 페이지는 한 화면에서 끝나야 하므로 링크 대신 표를 그대로 둡니다.

파일	성격
~/.claude/settings.json	사람이 쓰는 선언적 설정. 사용자 전체에 적용됩니다
.claude/settings.json	프로젝트에서 공유하는 설정. 6단계의 훅을 여기에 등록합니다
.claude/settings.local.json	프로젝트 개인 설정. git에 올리지 않으며, “다시 묻지 않기”로 승인한 퍼미션이 여기에 쌓입니다
~/.claude.json	앱이 실행 중 write back하는 UI 상태. 앱 실행 중 손편집하지 않습니다

3. 퍼미션 모드를 정합니다. ~/.claude/settings.json에 다음을 둡니다. 이미 다른 값이 있다면 그대로 두고, 왜 그런지는 권한 정책을 읽어 확인합니다.

{
  "permissions": {
    "defaultMode": "auto"
  }
}

4. 기록표 형식을 확정합니다. 1단계에서 프로젝트를 만들 때 docs/tutorial-log.md로 저장할 내용입니다. 지금은 형식만 읽어 둡니다. 열은 여섯 개입니다.

열	적는 것
단계	단계 번호와 이름. 단계별로 한 행이 미리 들어 있고, 7단계와 10단계는 세션별로 행을 나눕니다
세션 수	그 단계에서 쓴 세션 개수
단계 끝 컨텍스트 사용률	커밋 직전 상태줄 또는 /context의 사용률
시작 비용	단계를 시작할 때의 세션 누적 비용
끝 비용	커밋 직전의 세션 누적 비용
메모	그 단계에서 특별했던 것 한 줄

아래 내용을 그대로 저장합니다. 각 행은 단계 이름만 두고, 나머지 칸은 값을 적을 때 채웁니다. GFM 표는 머리 행보다 짧은 행의 빈 칸을 채워서 그립니다.

# 튜토리얼 기록표

| 단계 | 세션 수 | 단계 끝 컨텍스트 사용률 | 시작 비용 | 끝 비용 | 메모 |
|---|---|---|---|---|---|
| 1. 스펙 |
| 2. 계획 |
| 3. 게이트 |
| 4. 구현 |
| 5. 디자인 |
| 6. 규칙 강제 |
| 7. 병렬 |
| 8. 리뷰 |
| 9. 검증 |
| 10. 버그픽스 |
| 11. 마무리 |

비용은 세션 누적값입니다. /clear로 새 세션이 시작되면 0으로 돌아갑니다. 그래서 단계 시작과 끝의 값을 따로 적고 차액을 그 단계의 비용으로 읽습니다. 끝 비용은 그 단계의 커밋 직전에 읽고, 기록표를 그 커밋에 함께 담습니다. 다음 단계의 “시작 상태”가 깨끗한 작업 트리를 요구하기 때문입니다. 세션을 /clear로 비우더라도 다음 단계로 넘어가기 전에는 기록표가 커밋에 들어가 있어야 합니다. 같은 세션으로 다음 단계를 시작하면 이전 끝 값이 다음 시작 값이 됩니다. 세션이 여럿인 단계(7단계, 10단계)는 세션별로 한 행씩 추가합니다. 비용을 보여주지 않는 환경은 N/A로 둡니다.

값은 상태줄(활용 팁) 또는 /context·/cost에서 읽습니다. /cost는 /usage의 별칭입니다. 이 비용은 API 정가로 계산한 추정치이며 구독 요금과 무관합니다. 단계 간 상대 비교 용도로만 씁니다.

완료 확인

claude --version
ls ~/.claude/settings.json

버전이 출력되고 파일이 있으면 됩니다.

계측 기록

이 페이지는 기록할 것이 없습니다. 기록표는 1단계에서 만듭니다.

어긋났을 때

claude update가 채널을 바꿨는지 헷갈리면 설정한 대로 동작하지 않을 때를 확인합니다. 설정을 고쳤는데 반영이 안 되면 ~/.claude.json과 ~/.claude/settings.json을 섞어 읽었는지 의심합니다. 두 파일의 차이는 나의 기본 세팅에 있습니다.

가이드에서 더 읽기

• 나의 기본 세팅
• 권한 정책