Files

- CLAUDE.md 운영 규칙
- wiki/ 정리된 지식 페이지 (Nuxt + Claude Code)
- raw/ 원본 자료
- reference/ Nuxt 4.x 공식 문서

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-05-13 00:31:51 +09:00

4.0 KiB

Raw Permalink Blame History

Claude Code 핵심 개념

카테고리: 패턴 & 레시피 최종 수정: 2026-05-13 관련: claude-code-project-setup, claude-code-hooks, claude-code-workflow-patterns

요약

Claude Code는 챗봇이 아니라 에이전틱 코딩 환경이다. 파일 읽기·명령 실행·자율적 문제 해결이 가능하며, 모든 성능 전략은 하나의 핵심 제약에서 출발한다: 컨텍스트 윈도우.

에이전트 루프

효과적인 에이전트는 이 사이클을 반복한다:

Gather Context → Take Action → Verify Work → Iterate
(정보 수집)      (도구 실행)    (출력 검증)    (목표까지 반복)

컨텍스트 윈도우 — 모든 것의 근원

임계치	현상
0~20%	최적 성능
20~40%	품질 저하 시작
60% 초과	⚠️ 실무 검증 경계선 — 이 이상 채우지 말 것

컨텍스트 관리 명령:

명령	용도
`/clear`	무관한 작업 사이 컨텍스트 전체 초기화
`/compact <지시>`	부분 요약 (예: `/compact API 변경 위주로`)
`/btw`	컨텍스트에 남기지 않는 사이드 질문 (오버레이)
`Esc + Esc` / `/rewind`	이전 체크포인트로 복원

작업 흐름: Explore → Plan → Implement → Commit

곧바로 코딩하면 잘못된 문제를 풀 위험이 있다. Plan mode로 탐색과 실행을 분리하라.

1. Explore  (Plan mode): 파일 읽기, 질문 — 수정 없음
2. Plan     (Plan mode): 상세 구현 계획 작성
3. Implement          : Plan mode 해제, 코딩 + 테스트
4. Commit             : 설명적 메시지 + PR

💡 경험: 오타 수정, 변수 이름 변경 같은 작은 수정은 계획 없이 바로 실행해도 된다. 계획은 오버헤드다.

효과적인 프롬프트 작성

검증 수단을 항상 함께 제공

Claude는 스스로 검증할 수 있을 때 성능이 극적으로 오른다.

상황	Before	After
기능 구현	"이메일 검증 함수 구현해줘"	"validateEmail 작성. 테스트: user@example.com → true, invalid → false. 구현 후 테스트 실행해"
UI 변경	"대시보드 보기 좋게 만들어줘"	"[스크린샷] 이 디자인 구현. 결과 스크린샷 찍어서 원본과 비교. 차이점 나열 후 수정"
버그 수정	"빌드가 실패해"	"빌드 오류: [오류]. 수정 후 빌드 성공 확인. 에러 억제 말고 근본 원인 해결해"

구체적인 컨텍스트 제공

전략	예시
파일 직접 참조	`@src/auth.ts` — Claude가 파일을 먼저 읽고 답변
기존 패턴 지목	"HotDogWidget.php 패턴 따라서 캘린더 위젯 만들어줘"
증상 + 위치 + 완료 기준	"세션 만료 후 로그인 실패. src/auth/ 확인. 실패 재현 테스트 먼저 작성 후 수정"
이미지/파이프	`cat error.log \| claude`

Subagent로 조사 위임

조사 시 파일을 많이 읽어 컨텍스트를 소비한다. 조사는 subagent에 위임해 메인 컨텍스트 오염을 방지하라.

Use subagents to investigate how our authentication system handles token refresh,
and whether we have any existing OAuth utilities I should reuse.

흔한 실수 패턴

패턴	문제	해결
주방 싱크 세션	무관한 작업이 섞여 컨텍스트 오염	작업 사이마다 `/clear`
반복 수정 루프	틀림 → 수정 → 또 틀림 → 컨텍스트 오염	두 번 실패 후 `/clear` + 더 구체적인 프롬프트로 재시작
비대한 CLAUDE.md	규칙이 묻혀서 무시됨	불필요한 내용 제거, hook으로 이전
검증 없이 신뢰	그럴듯하지만 엣지케이스 미처리	항상 검증 수단 제공
무한 탐색	수백 개 파일 읽어 컨텍스트 폭발	조사 범위 좁게 잡거나 subagent 사용

참고 / 출처

raw/claude-code-best-practices-official.md (code.claude.com 공식 문서)
raw/claude-agent-sdk-overview.md (claude.com 블로그)

4.0 KiB Raw Permalink Blame History