Claude Code로 개발하기

이 저장소는 Claude Code 로 개발하는 것을 1급 워크플로우로 삼습니다. 이 페이지는 Claude Code 공식 문서의 기능 개요·메모리·.claude 디렉토리 세 글을 요약하고, Neul 저장소가 실제로 그 기능들을 어떻게 쓰는지를 함께 설명합니다.

출처: Claude Code 확장하기(features-overview), Claude가 프로젝트를 기억하는 방법(memory), .claude 디렉토리 탐색(claude-directory).

핵심 개념: 내장 도구 + 확장 계층

Claude Code 는 코드를 추론하는 모델에 내장 도구(파일 읽기/쓰기, 검색, 실행, 웹 접근)를 결합합니다. 내장 도구가 대부분의 코딩 작업을 처리하고, 그 위에 확장 계층을 얹어 "Claude 가 알아야 할 것"을 커스터마이즈하거나 외부 서비스에 연결하거나 워크플로우를 자동화합니다.

기능 개요 (features-overview 요약)

확장은 에이전트 루프의 서로 다른 지점에 연결됩니다.

유사 기능 구별 (요약)

• Skill vs Subagent: skill 은 어느 컨텍스트로든 로드되는 재사용 콘텐츠, subagent 는 주 대화와 분리되어 도는 격리 워커(요약만 반환). 컨텍스트 격리가 필요하거나 윈도우가 찰 때 subagent.
• CLAUDE.md vs Skill: 항상 알아야 할 규칙 → CLAUDE.md. 가끔 필요한 참조/워크플로우 → skill. 경험칙: CLAUDE.md 는 200줄 이하로 유지.
• CLAUDE.md vs Rules vs Skill: .claude/rules/ 는 paths frontmatter 로 특정 파일에만 로드되어 컨텍스트를 절약.
• Subagent vs Agent team: subagent 는 주 에이전트에 보고, agent team 은 팀원끼리 직접 메시징하며 자체 조정(토큰 비용 높음).
• MCP vs Skill: MCP 는 "연결(능력)", skill 은 "그 도구를 잘 쓰는 법(지식)". 함께 쓰면 강력.
• Hook vs Skill: hook 은 이벤트에서 결정론적으로 항상 실행, skill 은 Claude 가 해석해 적용. 가드레일은 hook 으로(프롬프트 지침은 요청일 뿐 강제가 아님).

시간이 지남에 따라 설정 쌓기

미리 다 만들 필요 없습니다. 트리거가 보이면 추가합니다.

메모리 (memory 요약)

Claude Code 세션은 매번 새 컨텍스트로 시작합니다. 세션 간 지식 전달은 두 가지로 합니다.

CLAUDE.md 계층

가장 넓은 범위부터 좁은 범위 순으로 로드되며 서로를 덮어쓰지 않고 누적됩니다(더 구체적인 지침이 보통 우선).

작업 디렉토리 위쪽의 CLAUDE.md 는 시작 시 전부 로드되고, 하위 디렉토리의 파일은 그 디렉토리의 파일을 만질 때 로드됩니다.

@path import

CLAUDE.md 는 @경로 구문으로 다른 파일을 가져옵니다. 가져온 파일은 펼쳐져 시작 컨텍스트에 함께 로드되며, 최대 4 홉까지 재귀 import 됩니다. 상대 경로는 작업 디렉토리가 아니라 import 를 포함한 파일 기준입니다.

AGENTS.md 와의 관계 — Neul 의 핵심 패턴

@AGENTS.md

AGENTS.md 에는 이 저장소의 v5 아키텍처, 핵심 결정/주의(자체 인증, AI 라우터, Workers DB 요청별 생성, day-key UTC, 모바일 네트워킹), 로컬 실행 명령, 작업 규칙, 그리고 테스트 정책이 정리되어 있습니다. 이 문서 사이트의 다른 페이지들도 AGENTS.md 를 원본으로 삼아 작성되었습니다.

자동 메모리 (auto-memory)

Claude 는 작업하며 빌드 명령·디버깅 인사이트·선호도 등을 스스로 노트로 남깁니다. 저장 위치는 저장소별로:

~/.claude/projects/<project>/memory/
├─ MEMORY.md   # 간결한 인덱스 (모든 세션에 앞 200줄/25KB 로드)
└─ *.md        # 주제별 상세 노트 (필요할 때만 읽음)

<project> 경로는 git 저장소에서 파생되므로 같은 저장소의 모든 워크트리·하위 디렉토리가 하나의 메모리 디렉토리를 공유합니다(머신 로컬, 클라우드 미공유). /memory 명령으로 로드된 CLAUDE.md/규칙 파일을 확인하고 자동 메모리를 켜고 끌 수 있습니다.

.claude 디렉토리 구조 (claude-directory 요약)

Claude Code 는 두 곳의 .claude 디렉토리를 읽습니다 — 프로젝트의 ./.claude/(팀과 공유, 커밋) 와 홈의 ~/.claude/(개인 전역, 머신 로컬). 같은 종류의 파일이 두 곳에 있을 수 있고, 보통 사용자(전역) → 프로젝트 순으로 로드돼 더 구체적인 프로젝트 설정이 뒤에 옵니다.

프로젝트 ./.claude/ (커밋 — 팀 공유)

홈 ~/.claude/ (머신 로컬 — 모든 프로젝트)

CLAUDE.md(개인 전역 선호), settings.json(전역 기본 설정), keybindings.json, themes/, rules/·skills/·commands/·agents/·workflows/(전역판), output-styles/(시스템 프롬프트 변형), 그리고 자동 메모리가 사는 projects/<project>/memory/. .claude.json 은 앱 상태/UI 선호도.

.claude/
├─ settings.json               # Stop 훅 등록 (committed)
└─ hooks/
   ├─ enforce-tests.mjs        # 테스트 강제 Stop 훅
   └─ enforce-artifacts.mjs    # Storybook/docs 동기화 강제 Stop 훅
# .claude/settings.local.json 은 .gitignore (개인 오버라이드)

Neul 에서 Claude Code 쓰기 — 실전 체크리스트

• 규칙의 원본은 AGENTS.md. 반복되는 실수나 새 결정은 채팅 일회성 수정이 아니라 AGENTS.md 편집으로 남깁니다(루트 CLAUDE.md 가 @AGENTS.md 로 가져옵니다).
• 새 API 라우트는 메서드 체이닝으로. 그래야 Hono RPC 타입이 web 으로 추론됩니다.
• 워크스페이스 경계를 지키세요. .ts/.tsx 변경은 해당 워크스페이스 안에서. 백엔드 응답 shape 은 프론트 화면 호환을 위해 보존합니다.
• 테스트는 정책입니다. 버그를 고치면 회귀 테스트를 같은 커밋에 포함합니다(unit / integration TZ=UTC / e2e 중 버그 성격에 맞는 레벨 — 테스트 참고).
• DB/네이티브 명령은 신중히. pnpm db:* 는 로컬 Postgres 상태를 바꾸고, cap 명령은 네이티브 프로젝트를 건드립니다. 실행 전 영향을 확인하세요.
• 컨텍스트 비용을 의식하세요. 항상 필요한 규칙만 AGENTS.md/CLAUDE.md 에, 가끔 필요한 참조는 skill 로, "매번 자동" 보장이 필요하면 hook 으로.

더 보기

• 기능별 상세: features-overview
• 메모리 상세(계층·import·auto-memory·문제 해결): memory
• .claude 디렉토리 전체 구성: claude-directory
• 이 저장소 규칙 원본: 루트 AGENTS.md