Claude Code 개인 개발 환경의 비망록 (2026.06)

예상 독자

Claude Code를 사용하기 시작하면서 "멋대로 파일을 바꿔버렸다", "rm -rf를 태연하게 제안했다", "대화를 계속하다 보니 중간부터 말이 통하지 않게 되었다"를 경험한 사람.

혼자서 개발을 진행하며, AI를 "관리"하는 측면의 메커니즘에 관심이 있는 사람.

서론

개인 개발 (Next.js) 및 문서 관리 (Obsidian)에서 Claude Code를 일상적으로 사용하고 있다. 편리한 것은 틀림없지만, 사용하기 시작하자마자 "이 녀석은 관리하지 않으면 위험하다"는 것을 깨달았다.

• 확인 없이 파일을 수정한다
• rm -rf나 git checkout .을 태연하게 실행하려고 한다
• 컨텍스트 (Context)가 방대해지면, 중간부터 말이 통하지 않게 된다
• "계획을 세워줘"라고 말했는데, 갑자기 코드를 쓰기 시작한다

AI에게 코드를 쓰게 하기 전에, AI를 관리하는 메커니즘이 필요하다. 이 기사는 그 메커니즘을 한 차례 공개하는 비망록이다.

여기에 적는 구성이 "정답"이라고 생각하지 않는다.

더 좋은 방법은 분명히 존재할 것이라 생각한다. 오히려 이 기사의 주장은 그 반대다.

AI 주변의 설정은 금방 낡아버릴 수 있다. 어제 밤에 도입한 설정이 다음 날 아침에 공식적으로 제공되기도 하고, 모델은 몇 달 만에 똑똑해진다.

그렇기에 처음부터 "떼어낼 수 있고, 버릴 수 있도록" 느슨한 결합 (Loose Coupling)으로 구성하여 정기적으로 정리한다.

...라는 운용 그 자체에 핵심이 있다.

제목에 굳이 (2026.06)이라고 넣은 것도, 이 내용 자체가 금방 진부해질 것이라는 전제 때문이다.

Skyrim이나 Fallout 같은 대형 게임의 MOD를 너무 의존하게 되면 업데이트 하나에 전부 무너지는 그 감각을 설정에도 가져오지 않도록 하고 있다.

읽는 분에게 단 하나라도 힌트가 된다면 좋겠다.

전체 구성

설정은 모두 ~/.claude/ 하위에 있다.

실체는 별도의 git 리포지토리 (본인의 경우 ai-contexts)에 두고 있으며, ~/.claude/ 쪽은 그곳을 가리키는 **심볼릭 링크 (symlink)**이다. 이렇게 해두면 설정을 커밋하기만 해도 그대로 GitHub에 백업된다.

.bashrc 등의 설정 파일을 하나의 리포지토리에 모아서 심볼릭 링크를 거는, 이른바 dotfiles 관리 방식이다.

~/.claude/
├── CLAUDE.md ← 모든 프로젝트 공통 행동 강령
├── settings.json ← hooks의 배선·권한·실험 플래그 (이 부분만 git 관리 대상 제외)
...

settings.json만은 MCP의 인증 정보를 포함하므로, 심볼릭 링크가 아니라 실체 파일로서 git 관리 대상에서 제외하고 있다.

CLAUDE.md — "무엇을 해도 되는가"에 대한 헌법

CLAUDE.md는 모든 프로젝트 공통의 행동 강령이며, Claude Code가 가장 먼저 읽는 파일이다.

복잡한 지적 노동에 있어서 며칠 뒤의 자신은 이미 다른 사람이므로, 아무것도 모르는 신입에게 건네줄 인수인계 자료를 작성한다는 마음가짐으로 만들면 딱 적당하다.

핵심이 되는 원칙은 다음과 같다.

- 파괴적인 조작 (rm / git reset --hard / push --force 등)은 사전 확인 필수
- 추측으로 진행하지 않는다. 가설을 세웠다면 증거로 확인한다
- 보고는 사실을 먼저, 제안을 나중에
...

예를 들어 "작동시키기 → 바로잡기 → 깔끔하게 만들기".

Claude Code에게 맡기면 처음부터 완벽한 설계의 코드를 내놓으려 하기 때문에, 대개 과도한 추상화(Abstraction)로 치닫는다.

"우선 작동하는 것을 내놓아라. 구체적인 이야기는 그 다음에"라고 명문화해 두어, 조기에 피드백을 주어 엉뚱한 방향으로 달려가지 않도록 하고 있다.

그리고 CLAUDE.md 자체도 비대하게 만들지 않는다.

처음에는 이것저것 적다 보니 50줄을 넘었지만, 지금은 "포인터와 치명적인 주의사항만" 남겨 가볍게 유지하고 있다.

상세 내용은 rules/ 하위의 파일로 분리했다. CLAUDE.md는 매 세션 반드시 읽히기 때문에, 이곳이 비대해지면 그만큼 매번 토큰 (Token)을 소비하게 된다.

헌법은 짧게, 조문은 별도 파일로.

hooks — 자동 가드레일 (본론)

hooks는 Claude Code의 특정 타이밍에 자동으로 쉘 스크립트 (Shell Script)를 삽입하는 메커니즘이다.

settings.json에서 "어떤 이벤트에서 어떤 스크립트를 실행할지"를 배선한다.

실제로 배선하고 있는 것은 대략 3가지 카테고리다.

전제 조건이 하나 있다. 평소에는 이것을 automode(defaultMode: "auto", 1액션마다 확인 과정을 생략하고 자동으로 진행하는 모드)로 실행한다.

확인 과정을 거치지 않는 만큼 빠르지만, 그것만으로는 폭주했을 때 아무도 멈출 수 없다. automode가 성립하는 이유는 이후에 가드레일 (Guardrail)이 작동하기 때문이며, 반대로 가드레일이 없는 automode는 무모하다고 생각한다.

여담이지만, 이전에 사용하던 bypassPermissions는 hooks 자체가 무효화되어, 공들여 만든 안전장치가 전부 죽어버렸다. auto로 전환한 이후에는 hooks가 작동하므로, 자동으로 진행하면서도 위험한 상황만 차단하고 있다.

🔒 안전 계통 — 파괴적인 조작을 차단

block-destructive.sh (PreToolUse)는 Bash 명령어를 실행하기 전에 개입하여 위험한 명령어를 자동으로 차단한다. 여기서 한 가지 기교를 부렸는데, git과 시스템 명령어를 구분하여 방식을 적용하고 있다.

git은 화이트리스트 (Whitelist) 방식이다.

status, log, diff와 같은 읽기 계열과 add, commit, pull 같은 일상적인 조작만 허용하며, 리스트에 없는 git 명령어는 모두 차단하여 사용자 확인 단계로 넘긴다.

push / reset --hard / clean -f / branch -D, 그리고 add -A / commit --amend / checkout .은 상시 차단한다.

시스템 명령어는 블랙리스트 (Blacklist) 방식이며, rm -rf, curl | bash (원격 스크립트 즉시 실행), crontab -r, shutdown 계열, chmod 777 등을 걸러낸다.

왜 git만 화이트리스트로 만들었냐 하면, 뼈아픈 경험을 했기 때문이다.

어느 날 Claude Code에게

세 가지는 서로 의존하지 않는다. 어느 하나를 삭제해도 나머지는 작동하며, 불필요해지면 단독으로 제거할 수 있다.

그전까지는 자료를 조금씩 만들게 하여 저와 Claude가 파악할 수 있도록 해왔다.

현재는 모델이 똑똑해진 영향도 있겠지만, "이야기가 어긋나는" 일은 거의 발생하지 않으므로 정답에 가까운 구성이라고 생각된다.

그 외의 뒷받침용 hook

.md를 편집하면 서두의 "최종 업데이트" 행을 자동으로 다시 쓰는 md-timestamp-hook.sh (문서 후반부에서 자세히 다룬다)와,

git commit으로 HEAD가 움직이면 Slack에 알림을 보내는 git-commit-notify.sh.
알림은 커밋 문자열을 해석하는 것이 아니라 "HEAD가 변했는가"로 판정하기 때문에 오검출이 적다.

hooks 이외의 메커니즘

skills (자동 발화하는 절차·규약)

skills는 특정 작업에 들어가면 Claude Code가 자동으로 읽으러 가는 "절차서·규약집"이다.

Anthropic 공식 스킬군 (PDF 처리·프론트엔드 설계·문서 공동 저술 등)에 직접 만든 것을 추가하고 있다.

독자성이 드러나는 부분은 횡단 가드(cross-cutting guard) 계열이다.

인증·Cookie·localStorage·OAuth·리다이렉트에 영향을 주는 변경을 감지하면 자동으로 발화하여 "상태 저장 위치와 덮어쓰기 리스크를 조사하라"고 촉구하는 스킬이나, 여러 상태·저장소·경로에 걸친 변경에서 발화하여 영향 범위를 표로 정리하게 만드는 스킬을 배치해 두었다.

포인트는 이것들이 "언어의 작성 방식"이 아니라 "실수하기 쉬운 상황의 절차"를 고정하고 있다는 점이다. 인증 관련하여 저장 위치 확인을 잊는 것과 같은 사고는 인간이 매번 주의하는 것보다 발화 조건이 있는 스킬에 맡기는 편이 확실했다.

그 외에도, AI스러운 일본어를 고치는 humanizer-ja나, Slack 전용 채널에 던져놓은 "떠오른 태스크"를 프로젝트별 ToDo 리스트로 분류하는 inbox 등이 있다.

commands (커스텀 슬래시 명령어)

작업 흐름을 정형화한 슬래시 명령어군.

/report (문서 업데이트 → 완료된 내용의 아카이브를 순차적으로 실행하여 작업을 마무리),

/digest (과거 N일간의 세션 이력·git log를 묶어 요약 생성),

/review (코드 리뷰),

/claude-md-check (CLAUDE.md를 코드의 실체와 대조),

그리고 후술할 /quarterly-review (환경 점검).

단어 하나만 입력해도 정형 작업이 실행되어, 절차를 누락하는 사고도 줄어든다.

per-project hook — 글로벌에 올리지 않는 것은 프로젝트 측으로

이것은 사소하지만 마음에 든다. lint와 같이 "프로젝트마다 설정이 다른 것"은 글로벌 hook에 올리지 않고, 프로젝트의 .claude/ 측에 둔다.

예를 들어 Next.js / TypeScript 개인 프로덕트에서는, .claude/hooks/ts-lint.sh를 편집 시 실행하여 ESLint를 적용하고, 문제가 있으면 그 자리에서 Claude에게 반환한다.

나아가 해당 프로젝트에서만 적용하고 싶은 "답변 전에 설명 스타일을 스스로 체크하게 하는" hook이나, node_modules 등을 읽으러 가지 않게 하는 설정도 함께 두고 있다.

글로벌은 최소한으로, 프로젝트 고유의 것은 프로젝트로. 이것도 의존 범위를 좁게 유지하기 위한 궁리로, 글로벌 hook이 비대해지는 것을 막는다.

agents (서브 에이전트)

planner / reviewer / security-reviewer를 정의해 두었다.

/review에서 명시적으로 호출하는 방식은 실용적으로 사용 중이지만, "Claude가 자율적으로 호출을 구분하는" 운용은 아직 실험 플래그를 기다리는 단계라는 온도감이다.

스테이터스 라인(Status Line) — "지금 어디를 만지고 있는가"를 항상 표시

hook은 아니지만, settings.json의 statusLine을 통해 화면 하단의 표시를 직접 만든 스크립트로 교체했다. 3행 구성이며,

1행: 모델명／현재 있는 프로젝트명／컨텍스트 사용률／작업 트리의 증감 (+추가・−삭제)／git 브랜치 -
2·3행: 최근 5시간·7일의 이용 한도 사용률 바와 리셋 시각

여러 프로젝트를 오가기 때문에, "지금 어느 리포지토리의 어느 브랜치를 만지고 있으며, 커밋되지 않은 작업이 얼마나 쌓여 있는지"를 한눈에 알 수 있다는 점이 은근히 효과적이다.

automode로 자동 진행되는 만큼, 자신이 지금 어디에 있는지 놓치지 않기 위한 "현재 위치 표시"이기도 하다.

Claude의 이용 한도(5h／7d) 잔량도 항상 보이기 때문에, 무거운 작업을 하기 전에 페이스 조절을 할 수 있다.

구현 진행 방식: 마이크로 커밋 합의 프로토콜 (Micro-commit Agreement Protocol)

메커니즘 이야기에서 잠시 벗어나, 구현 그 자체의 진행 방식. 기본은 "1단계씩 제시하고, 사용자의 OK를 기다리는" 방식으로 하고 있다.

## Step #n: [파츠명]
### 합의 대상 내용
1. (항목 1)
...

핵심은 1단계의 합의 대상을 3개 이내로 좁히는 것이다.

4개 이상이 되면 무엇을 승인했는지 스스로도 알 수 없게 되어, "OK"라고 말한 뒤에 "어라, 이것도 포함되어 있었나?" 하는 상황이 발생한다.

3개 이내라면 승인의 입도(granularity)가 유지된다. "한꺼번에 진행해"라고 말하면 스킵할 수 있지만, 기본은 1단계씩이다.

아울러, 동작 증명(테스트·로그·실제 동작 확인) 없이 Step을 완료 처리하지 않는 규칙도 두고 있다.

소재: 혼자서 운영하는 16개 화면의 Web 서비스

구체적인 예시가 있는 편이 전달이 잘 되므로, 실제로 Claude Code로 개발·운영하고 있는 개인 프로덕트를 소재로 삼는다.

최애(VTuber 등)의 방송 스케줄 이미지를 AI로 해석하여, 자신의 캘린더에 가져올 수 있도록 하는 Web 앱. (오시스케: https://oshi-sche-webapp.vercel.app/) (무료로 사용할 수 있습니다.)

기술 스택은 Next.js (App Router) / React / TypeScript / Tailwind CSS / shadcn/ui / NextAuth.js / Upstash Redis / Vercel이다. SPA로 화면 수는 16개. 이것을 혼자서 전부 하고 있다.

#	화면	역할
A	로그인	Google 로그인 + 기능 소개 + 데모 링크
...

AI가 코어 기능, JP가 보조·법무 계열이다. 혼자서 16개 화면을 돌릴 수 있는 것은, Claude Code를 설계의 벽치기(Brainstorming) 상대로 활용할 수 있는 점이 크다. 실제로 벽치기를 통해 결정한 설계 판단을 3가지만 소개한다.

캘린더 연동은 iCal 구독 URL로 일원화. Google Calendar API는 기능이 풍부하지만 락인(Lock-in)될 수 있고, 사용자에게 무거운 권한 연동을 요구하게 된다. iCal 구독이라면 어떤 캘린더 앱에서도 사용할 수 있다. -
과금은 프리미엄(Freemium) + BYOK (Bring Your Own Key). 무료 사용자는 개발자의 API 키를 사용하고, 헤비 유저는 자신의 키를 가져온다. 운영 비용을 억제하면서도, 많이 사용하는 사람에게는 제한 없는 경험을 제공할 수 있다. -
데이터 동기화는 localStorage + Redis의 하이브리드 방식. 우선 localStorage에 저장하고, 백그라운드에서 Upstash Redis로 동기화한다. 오프라인에서도 동작하며, 기기 간 동기화도 가능하다.

AI는 선택지와 논점을 정리해 주지만, "왜 그것을 선택하지 않을 것인가"를 결정하는 것은 인간의 일이다.

문서를 미아로 만들지 않기

Claude Code에는 코드뿐만 아니라 제안서·조사 메모·설계 자료도 산더미처럼 쓰게 하고 있다.

이유는 작업 내용과 상황을 항상 내가 파악할 수 있는 상태로 두고 싶기 때문이다.

다만, 이것을 방치하면 미아가 된다. 어디에 두었는지 잊어버리고, 최종 업데이트가 언제인지 알 수 없으며, "나중에 읽기"를 두 번 다시 열어보지 않게 된다. 코드에는 lint도 CI도 있지만, 문서는 쓰고 버려지기 쉽다.

그래서 Obsidian과 hooks를 사용하여 관리 체계를 구축했다.

보관 장소는 우선 이분한다. AI가 자신을 위해 쓰는 것(조사 메모·설계 자료·제안서)은 모두 Obsidian의 vault로.

코드 리포지토리에 넣는 것은 "코드를 읽는 사람이 같은 장소에서 읽어야 할 것"뿐이다 (README.md, CLAUDE.md, LICENSE 등).

자신용 메모까지 리포지토리에 섞으면 커밋 히스토리가 "기능 추가"와 "메모 업데이트"로 엉망이 된다. Obsidian 쪽이라면 Obsidian Sync를 통해 스마트폰·PC 어디에서든 읽을 수 있다.

Obsidian 도입은 과거에 두 번 정도 시도했으나 일본어화가 되어 있지 않다는 등의 이유로 단념했었지만, 생성형 AI와 조합하면 정말 정말 편리하므로 추천한다.

timestamp hook 의 frontmatter 사고

문서 관리에서 은근히 효과를 발휘하는 것이 파일 서두의 "최종 수정" 행(> 최종 수정: 2026-06-09（Mon）08:45)이다.

사람도 AI도 수동으로 수정하는 것을 잊어버리기 때문에, .md 파일을 Edit / Write 하면 hook이 현재 시각으로 다시 작성한다.

구조는 sed로 1행을 치환하는 것뿐이지만…… 여기에 주의해야 할 함정이 하나 있다.

Obsidian의 노트나 스킬(Skill) 정의는 파일 상단에 frontmatter(---로 둘러싸인 YAML)를 가지는 경우가 있다. 스킬의 경우, Claude는 이 frontmatter의 name과 description을 읽고 "이 작업이라면 이 스킬을 사용하자"라며 자동으로 발화(Trigger)한다. 그런데 최종 수정 행을 아무 생각 없이 맨 앞에 삽입하는 구현 방식을 사용하면, frontmatter가 첫 번째 줄부터 밀려나 파싱(Parsing)이 불가능해지며, 스킬이 자동으로 발화되지 않게 된다.

"최근 그 스킬을 불러도 반응이 없네"의 정체가 바로 이것이었다.

해결 방법은 간단하다. 상단에 frontmatter가 있으면 닫는 --- 직후에 최종 수정 행을 넣고, 없으면 기존처럼 맨 앞에 넣도록 분기 처리를 하는 것뿐이다.

위치 선정과 "현재 위치"

폴더는 내버려 두면 계속 늘어나기 때문에(ideas/, memo/, tmp/, old/ 등), 각 프로젝트를 원칙적으로 다음 5가지 종류로 고정하고 있다.

폴더	방향	용도
core/	작업의 핵심	세션 로그 · 설계 자료 · 작업 노트
outputs/	Claude → 나	Claude가 생성한 결과물 (HTML · PDF · 도표)
responses/	나 → Claude	나의 답변 · 결정
_Archives/	퇴피(보관)	완료 · 중단된 자료
assets/	소재	이미지 · 첨부 파일

폴더를 늘리지 않고, 분류는 "장소"가 아니라 "헤딩(Heading)"으로 하고 있다.

"아이디어"도 "보류"도 새로운 폴더를 만들지 않고 core/에 두며, 분류는 각 프로젝트의 중심 노트인 MOC (Map of Content)의 헤딩으로 표현한다.

MOC는 프로젝트의 입구로서, 상태 · 다음에 할 일(최대 3개) · 관련 자료 링크만을 적어두는 "현재 위치의 지도"이다.

작업 로그나 긴 설계 자료는 MOC에 남기지 않고 별도 파일로 흘려보낸다. 목표는 50행 내외이며, "항상 아름답게"보다는 "다음에 열었을 때 헤매지 않게"를 우선한다.

확인 대기 상태를 쌓아두지 않기: review-queue

Claude가 제안서나 설계 자료를 작성해도 그 자리에서 전부 읽을 수 있다는 보장은 없다. "나중에 읽기"가 사장되는 것을 방지하기 위해, 확인 대기 중인 항목을 한곳에 모으는 큐(Queue)를 Obsidian의 Bases(프로퍼티로 노트를 필터링하여 표로 만드는 기능)로 구성해 두었다.

자료 1건 = 스텁(Stub) 노트 1장으로 구성하며, frontmatter에 read: false (읽음 체크)와 한 줄 요약을 포함시킨다. 표에서 "✅ 읽음"을 누르면 미독 뷰(Unread view)에서 사라지며 Archive로 이동한다.

Claude 측에는 "제안서 · 조사 노트를 만들면 스텁을 1장 추가한다"라는 규칙을 배선(Wiring)해 두었으며, 추가로 /report 명령어가 결과물 폴더를 스윕(Sweep)하여 누락된 것을 보완한다.

이 시스템 덕분에 "시간이 좀 있으니 자료를 좀 볼까. ... 어떤 자료였더라?"라며 길을 잃는 일이 없어졌다.

로그는 흐르고, 지식은 남는다

문서에는 "흘려보내는 것"과 "남기는 것"이 있다.

매일의 작업 로그는 core/session-log.md에 날짜 내림차순으로 쌓기만 한다 (기본적으로 다시 읽지 않는다).

재발 시 재사용하고 싶은 지견이 쌓이면 30-Notes/knowledge/에 영구 노트로 승격시키고, 더 나아가 재사용 가능한 "절차"가 확립되면 **스킬(Skill)**로 승격시킨다.

매일의 작업 → session-log (흐름)
↓ 재사용하고 싶은 지견
30-Notes/knowledge (남는 사실 · 재발 대응)
...

아래로 내려갈수록 "다음에 같은 상황이 되었을 때, 손을 움직이지 않고 끝낼 수 있는" 정도가 높아진다.

설정은 노후화된다 — 그러므로 정리(Inventory)한다

여기까지 읽은 사람이라면 눈치챘겠지만, 이런 종류의 설정은 내버려 두면 반드시 부패한다.

• 모델이 똑똑해져서 더 이상 필요 없어진 규칙
• 한 번도 발화되지 않은 hook
• description이 실태와 어긋나서 자동 발화되지 않게 된 skill

그래서 「만들고 끝」내지 않고, 1~2개월마다 재고 조사(Inventory)를 하는 것을 루틴으로 삼고 있다.

/quarterly-review

라는 명령어를 준비해 두었는데 (이름은 quarterly = 분기이지만, 실제로는 훨씬 더 빈번하게 돌리고 있다), CLAUDE.md / hooks / rules / skills를 한 바퀴 돌며 각 항목에 대해 「유지 / 축소 / 삭제」를 판정한다.

판단 기준은 심플하다. hooks라면 「최근에 실제로 발화(trigger)된 흔적이 있는가」, 「Claude Code 본체의 신기능으로 대체되지 않았는가」를 묻는다.

지금까지의 설계를 전부 「서로 의존시키지 않는다」는 방침으로 짜온 것은, 이 재고 조사를 가볍게 만들기 위해서다.

CLAUDE.md를 얇게 유지하고, 글로벌 hook을 최소한으로 하며, 기억 계통을 3개의 독립된 장치로 나누고, lint를 프로젝트 측으로 넘긴다——이 모든 것들은 단독으로 떼어낼 수 있기 때문에, 재고 조사 시에 「이것을 지우면 다른 어딘가가 망가진다」는 것을 걱정할 필요가 없다.

서두의 Skyrim MOD 비유로 돌아가면, 상호 의존을 늘리지 않을수록, 하나를 뽑고 끼워도 전체가 무너지지 않는다.

요약

• CLAUDE.md는 「AI를 위한 인수인계 자료」다. 아무것도 모르는 신입에게 건네준다는 생각으로 작성하며, 내용을 비대하게 만들지 말고 상세 내용은 별도 파일로 넘긴다.
• hooks는 「자신이 매번 하기 귀찮은 일, 확실히 해주었으면 하는 일」을 자동화하는 것이다. 파괴 방지 · lint · 컨텍스트 관리 · 세션 간의 인수인계 등.
• 장치들은 서로 의존시키지 않고, 단독으로 떼어낼 수 있도록 만든다. 기억 계통조차 하나로 뭉치지 않는다.
• 만든 설정은 부패한다. 그러므로 1~2개월마다 재고 조사하여 버린다.

서두에도 썼지만, 이것이 정답이라고 생각하지는 않는다.

더 똑똑하고 좋은 방법은 분명히 있을 것이다. 그리고 (2026.06)이라고 날짜를 적어둔 대로, 반년 후에는 이 구성의 절반 정도는 버리고 있을 것이다.

그래도 괜찮다. 버리기 쉽게 만들어 두었으니까.

현재로서는, 이로써 「AI에게 작업을 맡기는 것」이 「AI에게 휘둘리는 것」이 되지 않게 되었다.

도구 등 여러 가지를 만들고 있습니다.

일부 도구는 공개 중입니다 (포트폴리오: https://yoyogipinball.github.io ).

구직 중입니다. 연락처는 포트폴리오 사이트 하단에 있습니다.

편하게 연락해 주시기 바랍니다.

Discussion