진정한 Claude Code 사용법

진정한 claude 사용

컨텍스트는 60%를 초과하지 마세요. 작업을 4단계로 분할하세요: 연구 → 계획 → 구현 → 검증. 각 단계 간 컨텍스트를 명확히 하세요. 모든 것을 심볼릭 링크된 thoughts/ 디렉터리에 저장하세요 (npx humanlayer thoughts init 사용).

제가 강조하고 싶은 가장 강력한 포인트 중 하나는 바로 이 심볼릭 링크된 ‘thoughts’ 디렉터리입니다. 중요한 점은 이 디렉터리가 전역적으로, 리포지토리 간에 공유될 수 있다는 것입니다. 따라서 팀원 및 조직 전체가 클로드가 편집하고 구축하는 문서에 접근할 수 있습니다. 이는 매우 강력한 기능입니다.

humanlayer의 .claude/commands 및 .claude/agents를 다운로드하여 코드베이스에 맞게 편집하는 것을 적극 권장합니다. 여기에서 다운로드하세요!

이제 본격적인 내용으로 넘어가 보죠 :)

컨텍스트 천국

6개월 전만 해도 AI 코딩 어시스턴트와의 대화는 대략 이랬습니다: 기능 작업을 시작하고, 여러 파일을 불러오고, 질문하고, 답변 받고, 수정하고, 오류 발생하고, 컨텍스트를 위해 파일을 더 추가하고, 또 질문하고. 어느새 컨텍스트 용량이 95% 차고, 반쯤 구현된 코드와 수십 개의 “final_implementation_final_feature.md” 파일이 쌓여 있었습니다💀

컨텍스트 엔지니어링에 집중하면서 상황이 바뀌었습니다. 이제 구조화된 워크플로우를 통해 컨텍스트를 깔끔하게 유지하고 계획을 탄탄히 세우며 구현 결과를 훨씬 더 예측 가능하게 만들 수 있어 수천 줄의 코드를 더 자신 있게 배포할 수 있습니다.

컨텍스트 엔지니어링이 전부다

핵심은 더 많은 컨텍스트가 아니라, 적절한 시점에 올바른 컨텍스트를 확보하는 것이다.

컨텍스트 창에 할당하는 양이 많을수록 결과(품질과 예상치 못한 동작 모두)는 악화된다. 이는 어떤 LLM을 사용하든 변함없는 진리다.

엔터 키를 누르거나 클릭하여 이미지를 전체 크기로 보세요

제 개인적인 규칙: 컨텍스트를 절대 60% 이상 넘기지 마세요. 저는 작업 중 항상 /context로 확인합니다.

참고로, 새 대화 시작 시 제 컨텍스트는 다음과 같습니다

엔터 키를 누르거나 클릭하여 이미지를 전체 크기로 보세요

따라서 대화 시작 시 약 32% 수준입니다.

저는 일반적으로 워크플로를 네 가지 핵심 단계로 나누고, 각 단계 사이에 컨텍스트를 지웁니다. 예를 들면 다음과 같습니다:

1. 연구: Claude 프롬프트: “/research_codebase + 다음에 구현할 기능 또는 일반 코드베이스 연구” → 연구가 60%를 초과하면(보통 그렇습니다) /context 및 /clear 컨텍스트 실행 → 나머지 3단계도 동일하게 진행

2. 계획: Claude 프롬프트: “/create_plan + @thoughts/research/researched_feature.md” → /context → 70% → /clear

3. 구현: Claude 프롬프트: “/implement_plan + @thoughts/plans/research_and_planned_feature.md Phase 1 only of this plan” → /context → 67% → /clear

4. 검증: 내 Claude 프롬프트: “/validate_plan + @thoughts/plans/research_and_planned_feature.md + 이 계획 문서의 1단계를 구현했습니다. 검증해 주세요” → /context → 42% → 스레드 계속 (즉, 컨텍스트 지우지 않음)

각 단계는 특정 역할을 수행합니다. 각 단계는 다음 단계가 소비하는 산출물을 생성합니다.

엔터 키를 누르거나 클릭하여 이미지를 전체 크기로 보세요

네, 좀 복잡하네요. 그래서 제가 설명해 드릴게요

제 Claude 코드 워크플로

1단계: 연구 (@research_codebase.md)

엔터 키를 누르거나 클릭하여 이미지를 전체 크기로 보세요

목표: 기존 시스템 이해 및 변경 필요 사항 파악. 이 단계에서는 코드를 절대 작성하지 않습니다.

새로운 기능을 시작할 때 저는 절대 구현부터 뛰어들지 않습니다. 항상 먼저 연구를 진행하며, 제 커스텀 Claude 명령어(.claude/commands/research_codebase.md)를 호출합니다:

/research_codebase + {연구하거나 구축하려는 대상 또는 구현하려는 기능}

그런 다음 명령어 뒤에 연구 질문을 제공합니다. 예를 들어, 웹 자동화 프레임워크에서 브라우저 페이지 관리 방식을 이해해야 했을 때:

/research_codebase + 현재 브라우저 페이지 관리 시스템은 어떻게 작동하나요? 또는

/research_codebase + 페이지 생성, 추적, 정리 위치는 어디인가요?

이 연구 명령어는 병렬 서브 에이전트를 생성해 다양한 측면을 동시에 조사합니다:

• 코드베이스 로케이터 에이전트: 관련 파일 전체 탐색
• 코드베이스 분석기 에이전트: 현재 구현 방식 작동 방식 검토
• 생각 로케이터 에이전트: 기존 문서 또는 과거 연구 검색
• 생각 분석 에이전트는 관련 문서에서 통찰력을 추출합니다

이 에이전트들은 병렬로 작동하며 특정 파일 경로와 줄 번호를 반환합니다.

연구 단계는 thoughts/ 디렉토리에 포괄적인 연구 문서를 생성하며 완료됩니다:

thoughts/shared/research/2025-10-09_browser-page-management.md

이 문서는 포괄적이며 다음을 포함합니다:

• 연구 결과 요약
• 파일:줄 번호가 포함된 코드 참조 *매우 중요*
• 아키텍처 통찰
• 명확히 해야 할 미해결 질문

병렬 에이전트를 생성함으로써 수십 개의 파일을 직접 읽지 않고도 신속하게 포괄적인 답변을 얻을 수 있습니다. 또한 모든 내용이 thoughts/ 디렉터리에 저장되므로, 저와 팀원, 클로드가 컨텍스트에 보관하지 않고도 나중에 참조할 수 있습니다.

 

 

2단계: 계획 (@create_plan.md)

엔터 키를 누르거나 클릭하여 이미지를 전체 크기로 보기

목표: 상세하고 반복 가능한 실행 계획 수립.

조사 후 컨텍스트를 초기화하고 계획 수립을 새로 시작합니다:

@create_plan.md thoughts/shared/research/2025-10-09_browser-page-management.md

이 명령어는 조사 문서를 읽고 대화형 계획 세션을 시작합니다. 클로드의 초기 응답 후, 일반적으로 .md 파일을 꼼꼼히 읽으며 계획을 약 5회 반복한 후 최종 확정합니다.

이 계획 문서는 우리의 신뢰할 수 있는 정보원입니다

왜 이렇게 많이 반복할까요? 첫 초안은 결코 완성되지 않기 때문입니다. 계획 단계는 상호작용적입니다:

1. 초안: Claude가 연구를 읽고 명확히 하기 위한 질문을 합니다

2. 수정안: 제가 답변을 제공하면 Claude가 접근 방식을 다듬습니다

3. 3차 수정안: 설계상의 절충점을 논의하고 Claude가 단계를 업데이트합니다

4. 4차 수정안: 경계 사례를 식별하고 Claude가 성공 기준을 추가합니다

5. 다섯 번째 초안: 최종 검토, 모든 내용이 실행 가능함

각 반복을 통해 계획은 더욱 구체화됩니다. 제가 작업을 완료할 때쯤이면 계획에는 다음이 포함됩니다:

• 구체적인 변경 사항이 포함된 명확한 단계
• 수정할 정확한 파일 경로
• 추가/변경할 내용을 보여주는 코드 스니펫
• 자동 검증(테스트, 린팅, 타입 검사)
• 수동 검증(인간이 테스트해야 할 사항)
• 각 단계별 성공 기준

최종 계획은 다음 위치에 저장됩니다:

thoughts/shared/plans/2025-10-09-browser-page-management.md

계획 내 단계 예시는 다음과 같습니다:

1단계: BrowserContext에 페이지 추적 기능 추가

개요BrowserContext에 페이지 레지스트리를 추가하여 생성된 모든 페이지와 그 수명 주기 상태를 추적합니다. 필요한 변경 사항: 1. BrowserContext 클래스 업데이트 파일: src/browser/browser_context.py class BrowserContext:     def __init__(self, ...):         self._pages: Dict[str, Page] = {}         self._active_page: Optional[Page] = None 성공 기준: 자동 검증: - [ ] 단위 테스트 통과: uv run pytest src/browser/tests/- [ ] 린팅 오류 없음: make lint- [ ] 타입 검사 완료: make check수동 검증:- [ ] 다중 페이지 동시 추적 가능- [ ] 헤딩 브라우저 모드에서 페이지 정리 정상 작동- [ ] 반복 페이지 생성 시 메모리 누수 없음

여기서 핵심 통찰은 계획을 반복하는 데 시간을 투자하면 구현 과정에서 시간을 절약하고 불량 코드를 방지할 수 있다는 점입니다. 탄탄한 계획은 막히거나 되돌아가야 할 일이 거의 없음을 의미합니다.

연구 명령어가 이미 관련 코드 라인을 찾아냈기 때문에, 계획 명령어는 방대한 컨텍스트를 확보하여 계획을 더 효과적으로 구현할 수 있게 되었습니다.

3단계: 구현 (@implement_plan.md)

엔터 키를 누르거나 클릭하여 이미지를 전체 크기로 보기

목표: 한 번에 한 단계씩 자신 있게 실행하기.

계획 후, 다시 컨텍스트를 정리하고 구현을 시작합니다:

@implement_plan.md thoughts/shared/plans/2025-10-09-browser-page-management.md

나의 규칙: 한 번에 한 단계씩 구현한다.

구현 명령어:

1. 계획을 완전히 읽음

2. 1단계에서 언급된 모든 파일 읽음

3. 지정된 변경 사항 적용

4. 자동 검증 실행

5. 수동 테스트를 위해 일시 중지

마지막 항목이 핵심입니다. 모든 자동 검사를 통과한 후, 클로드가 알려줍니다:

1단계 완료 - 수동 검증 준비 완료

자동 검증 통과:- ✓ 단위 테스트 통과- ✓ 린팅 오류 없음- ✓ 타입 검사 클린수동 검증을 수행해 주세요:- [ ] 여러 페이지를 동시에 추적 가능- [ ] 헤더드 브라우저 모드에서 페이지 정리 기능 작동수동 테스트 완료 시 알려주세요.

그런 다음 기능을 수동으로 테스트합니다. 작동하면 Claude에게 2단계로 진행하라고 지시합니다(현재 작업 진행률이 60% 미만인 경우). 작동하지 않으면 실패한 부분을 보고하고, 진행 전에 수정합니다.

이 접근법은 흔한 함정을 방지합니다: 모든 것을 구현한 후, 1단계에 모든 후속 단계를 망가뜨리는 치명적 버그가 있었다는 사실을 발견하는 경우를 말합니다.

핵심 통찰: 한 번에 한 단계씩 = 지속적인 검증 = 예상치 못한 문제 감소

4단계: 검증 (@validate_plan.md)

엔터 키를 누르거나 클릭하여 이미지를 전체 크기로 보세요

목표: 전체 구현을 체계적으로 검증합니다.

모든 단계(또는 단일 단계) 구현 후 컨텍스트를 한 번 더 초기화하고 검증합니다:

@validate_plan.md thoughts/shared/plans/2025-10-09-browser-page-management.md

검증 명령어:

1. 계획을 읽습니다

2. 최근 git 커밋을 확인합니다

3. 모든 자동 검증 명령 실행

4. 계획 사양 대비 코드 변경 사항 검토

5. 종합 검증 보고서 생성

보고서에는 다음이 표시됩니다:

- ✓ 올바르게 구현된 내용

- ⚠️ 계획과의 모든 편차

- ✗ 수정 필요 사항

- 수동 테스트 체크리스트

이 최종 단계에서 다음과 같은 사항을 포착합니다:

- “2단계에서 추가 검증 추가됨(좋음!)”

- “경계 사례 X에 대한 오류 처리 누락 (수정 필요)”

- “자동화 테스트는 통과했으나 수동 테스트에서 UX 문제 발견”

핵심 통찰: 검증은 안전망입니다. 출시 전에 누락된 사항이 없도록 보장합니다.

비장의 무기: thoughts/ 디렉터리

이 워크플로우 전반에 걸쳐 모든 내용은 제 thoughts/ 디렉터리에 저장됩니다:

thoughts/

├── ashley/│   ├── tickets/│   │   └── eng_1478.md          # 원본 선형 티켓│   └── notes/│       └── notes.md              # 개인적 관찰 및 브레인 덤프├── shared/│   ├── research/│   │   └── 2025-10-09_browser-page-management.md│   ├── plans/│   │   └── 2025-10-09-browser-page-management.md│   └── prs/│       └── pr_456_browser_pages.md└── searchable/                    # 검색용 심볼릭 링크

이것이 강력한 이유는?

1. 지속적 기억: 컨텍스트 정리 후에도 연구 및 계획이 유지됨

2. 재사용 가능한 지식: 향후 기능이 과거 결정을 참조할 수 있음

3. 팀 협업: 공유된 연구가 모두에게 도움

4. 감사 추적: 몇 달 후에도 결정 배경 확인 가능

searchable/ 디렉토리에는 모든 문서의 하드 링크가 포함되어 있어 Claude의 검색 도구가 필요 시 관련 컨텍스트를 쉽게 찾을 수 있습니다.

이 워크플로가 효과적인 이유

이 워크플로는 인간과 AI 모두의 최적 작업 방식과 부합하기 때문에 효과적입니다:

AI(Claude)를 위한:

• 명확한 목표: 각 단계는 하나의 임무만 수행
• 관련 컨텍스트: 필요한 것만, 그 이상은 없음
• 검증 루프: 자동화된 점검으로 편차 방지
• 파일 내 기억: 세션 간 “기억” 불필요

인간(나와 당신)을 위해:

• 인지 부하: 한 번에 한 단계씩 처리 가능
• 확신: 탄탄한 계획으로 불확실성 감소
• 품질: 다중 검증 포인트로 문제 조기 발견
• 속도: 병렬 연구와 명확한 단계 = 더 빠른 전달

코드베이스에 대해:

• 문서화: 모든 기능에 연구 + 계획 포함
• 일관성: 연구에서 발견된 패턴 따르기
• 유지보수성: 향후 개발자가 결정 사항 이해
• 품질: 체계적 검증 = 버그 감소

팁

1. 연구를 생략하지 마세요

코드베이스를 안다고 생각해도 연구를 진행하세요. 잊고 있던 패턴과 경계 사례를 발견하게 될 것입니다.

2. 생각보다 더 자주 계획을 수정하라

초기 계획은 항상 너무 피상적이었다. 지금은 계획 수립에 30~45분을 할당하고 5회 이상 수정한다. 시간 투자는 보상을 받는다.

3. 맥락 파악에 철저하라

맥락 파악이 60%에 도달하면 멈추고 자문하라: “파일로 저장해 나중에 참조할 수 있는 내용은 무엇인가?” 대개 연구 결과나 계획 세부사항이다.

4. 수동 테스트의 중요성

자동화 테스트는 코드 수준 문제를 포착합니다. 수동 테스트는 UX 문제, 성능 문제, 실제 환경의 경계 사례를 포착합니다. 둘 다 수행하세요.

5. 실행 중 계획 업데이트

2단계에서 3단계에 영향을 미치는 새로운 사항을 발견하면 계획 파일을 업데이트하세요. 이를 진실의 원천으로 유지하세요.

6. thoughts 디렉터리를 철저히 활용하세요

모든 연구 문서, 계획, 노트는 thoughts/에 저장하세요.

미래의 당신이 현재의 당신에게 고마워할 거예요 :)

이 워크플로를 시도해보고 싶으신가요? 시작하는 방법은 다음과 같습니다:

1. 명령어 파일 설정

다음과 같이 .claude/commands/ (또는 .cursor/commands/) 디렉터리를 생성하세요:

• research_codebase.md
• create_plan.md
• implement_plan.md
• validate_plan.md

공유한 명령어를 수정하거나 자신만의 변형을 만들 수 있습니다.

2. 심볼릭 링크된 thoughts 디렉터리 생성

mkdir -p thoughts/{personal,shared,searchable}

mkdir -p thoughts/shared/{research,plans,prs}

mkdir -p thoughts/personal/{tickets,notes}

3. 전체 워크플로로 한 기능 시도하기

작은 기능 하나를 선택하세요. 한 번에 모든 걸 배우려 하지 마세요:

1. 연구 → 컨텍스트 정리

2. 계획 (반복!!!) → 컨텍스트 정리

3. 구현 (한 단계) → 컨텍스트 정리

4. 검증 → 컨텍스트 정리

반복~

4. 효과적인 부분을 관찰하세요

첫 기능 후 반성하세요:

• 어디서 막혔나요?
• 명령어 중 더 명확히 할 부분은?
• <60% 컨텍스트 유지했나요?

워크플로 자체를 반복 개선하세요.

결론적으로, 메타 스킬: 컨텍스트 엔지니어링

제가 진정으로 깨달은 점은 이렇습니다: AI 작업은 항상 올바른 질문을 하는 것이 아니라, 올바른 컨텍스트를 설계하는 것입니다.

클로드를 호출할 때마다 특정 컨텍스트를 작업 메모리에 로드합니다. 하나의 함수를 변경하기 위해 전체 코드베이스를 컴파일하지 않는 것처럼, 하나의 기능을 구현하기 위해 전체 프로젝트 이력을 로드해서는 안 됩니다.

제가 공유한 워크플로는 컨텍스트 엔지니어링의 실제 적용 사례입니다:

• 연구: 이해를 위한 컨텍스트 로드
• 계획: 설계를 위한 컨텍스트 로드
• 구현: 실행을 위한 컨텍스트 로드
• 검증: 확인을 위한 컨텍스트 로드

각 단계는 집중된 목적을 가지며, 산출물을 생성하고 다음 단계를 위한 준비를 완료합니다.

AI와 함께 코딩하는 데 여전히 어려움을 겪고 컨텍스트 한계에 부딪혀 좌절한다면, 이 워크플로를 시도해 보세요.

작게 시작하세요. 반복하세요. 자신만의 방식으로 만드세요.

읽어 주셔서 감사합니다,

 

부록: 빠른 참조

4단계 워크플로

1. 연구 (@research_codebase.md)

• 기존 코드 이해
• 병렬 에이전트 생성
• 연구 문서 생성
• 컨텍스트 정리

2. 계획 (@create_plan.md)

• 구현 계획 수립
• 5회 이상 반복
• 성공 기준 정의
• 컨텍스트 정리

3. 구현 (@implement_plan.md)

• 한 번에 한 단계씩 실행
• 자동 검증 실행
• 수동 테스트 수행
• 단계 간 컨텍스트 정리

4. 실행된 계획 검증 (@validate_plan.md)

• 체계적 검증
• 검증 보고서 생성
• 누락 사항 없음 확인
• 컨텍스트 정리

컨텍스트 관리 규칙

• 컨텍스트 용량 60% 초과 금지
• 주요 단계마다 컨텍스트 정리
• 모든 내용 thoughts/ 디렉터리에 저장 (npx humanlayer thoughts init)
• 메모리 보관 대신 파일 참조
• 정보 수집 효율화를 위한 병렬 에이전트 활용

디렉터리 구조

thoughts/

├── [개인]/           # 개인 노트/티켓│   ├── tickets/│   └── notes/├── shared/               # 팀 공유 문서│   ├── research/│   ├── plans/│   └── prs/└── searchable/          # 검색용 하드 링크

 

 

참고 자료 및 노트

노트

아래 동영상과 자료를 꼭 확인해 보시길 강력히 추천합니다. Dex와 humanlayer 팀이 이러한 명령어와 에이전트를 개척하는 데 정말 훌륭한 일을 해냈습니다. 다시 한번 그들의 팀에 큰 감사를 드립니다❤

동영상

• 코딩 에이전트를 위한 고급 컨텍스트 엔지니어링
• 12-Factor 에이전트: 신뢰할 수 있는 LLM 애플리케이션 패턴 — Dex Horthy, HumanLayer
• 에이전트를 위한 고급 컨텍스트 엔지니어링

블로그 게시물 및 기사

• AI의 새로운 기술은 프롬프팅이 아닌 컨텍스트 엔지니어링입니다 — 컨텍스트 엔지니어링에 관한 Phil Schmid의 글
• AI 에이전트를 위한 효과적인 컨텍스트 엔지니어링 — AI 에이전트를 위한 컨텍스트 엔지니어링에 관한 Anthropic의 글

도구 및 자료

• Humanlayer GitHub — 컨텍스트 관리 및 사고 디렉토리 도구
• X에서 연결하기