TL;DR

Claude Code를 개인 개발의 메인 환경으로 깊이 있게 사용하다 보면, 아무런 설정이 없는 상태에서는 "매번 같은 지시를 해야 한다", "같은 실수가 반복된다", "세션이 끝나면 문맥(Context)이 사라진다"라는 벽에 부딪히게 된다.

이 기사에서는 그 벽을 넘기 위해 구축한 나의 개발 환경을 통째로 투어 형식으로 소개한다. 단순히 도구의 이름을 나열하는 것이 아니라, "왜 그런 구성으로 했는지", "어디와 어디가 연동되는지"를 각 항목별로 해설한다. 환경 구축에 참고가 된다면 좋겠다.

전체상: 5층 구조로 작동함

나의 환경은 다음 5개 층으로 구성되어 있다.

위에서 아래로 "지시가 구체화되는" 구조로 되어 있다. 설정층(Configuration layer)은 항구적인 규칙, 스킬층(Skill layer)은 그 규칙을 실행하는 절차, 에이전트층(Agent layer)은 복잡한 판단이 필요한 작업의 위임처, 훅층(Hook layer)은 "말하지 않아도 발화하는" 자동화, 메모리층(Memory layer)은 세션을 넘나드는 기억이다.

이 구조로 만든 이유는 심플하다. "매번 구두로 설명하는 것"을 극력 줄이고 싶었기 때문이다. CLAUDE.md에 적어두면 매번 읽어온다. 스킬로 만들면 절차가 고정된다. 훅으로 만들면 요청하지 않아도 동작한다. 인간이 기억해야 할 것을 줄일수록, 실제 개발에 사용할 수 있는 시간이 늘어난다.

~/.claude/를 git 리포지토리로 만들기

설정층: 나의 환경의 기점은 ~/.claude/ 디렉토리 자체를 git으로 관리하고 있다는 점이다. CLAUDE.md, rules, skills, agents, hooks, settings.json을 모두 하나의 리포지토리에 넣어 설정의 변경 이력을 추적할 수 있도록 하고 있다.

왜 이렇게 했는가. 하네스(Harness, Claude의 거동을 제어하는 메커니즘 전체)는 "한 번 만들고 끝"나는 것이 아니라, 실패할 때마다 키워나가는 것이기 때문이다. 어떤 세션에서 같은 실수가 2번 발생하면, 그 자리에서 규칙을 한 줄 추가한다. 추가한 규칙이 어떻게 효과가 있었는지는 나중에 다시 돌아볼 수 없으면 검증할 수 없다. 설정 자체를 버전 관리(Version control) 하에 둠으로써 "언제·왜 그 규칙을 추가했는지"가 커밋 로그(Commit log)로 남는다.

E:\Documents\Claude\
├── documents/ - 설계 문서·조사 자료
├── code/ - 개발 중인 툴 모음
...

~/.claude/는 설정 그 자체, E:\Documents\Claude\는 성과물이라는 역할 분담을 하고 있다. 설정과 성과물을 같은 장소에 두면 어느 리포지토리에서 무엇을 관리하고 있는지 혼란스러워지기 때문에 처음부터 분리했다.

스킬층: 20개의 "절차서"

스킬은 SKILL.md라는 형식으로, 여러 단계의 워크플로(Workflow)를 정의한 것이다. 대표적인 것을 소개한다.

스킬을 이만큼이나 준비한 이유는 "같은 판단을 매번 Claude에게 제로 베이스에서 생각하게 하지 않기" 위해서다. 예를 들어 git-management는 여러 리포지토리 중 어느 것을 언제 커밋해야 하는지에 대한 판단을, 매번 대화하는 것이 아니라 스킬 안에 절차로서 고정하고 있다. 대화의 문맥에 의존하면 판단이 흔들릴 수 있지만, 절차서가 있으면 매번 같은 기준으로 동작한다.

에이전트층: 12체의 전문가 팀

에이전트는 스킬보다 한 단계 추상도가 높으며, "판단이나 생성 그 자체"를 맡기는 위임처다. 중심이 되고 있는 것은 3체가 한 세트인 코딩 하네스다.

• planner: 구현 전에 계획을 세운다. 여기서 "구현 가설"과 "이해도 스코어"를 반드시 출력하게 함으로써, 요구사항을 오해한 채 구현이 진행되는 것을 방지하고 있다.
• evaluator: 정적인 관점(패스 해결 방식, 예외 처리 유무, Windows 특유의 고려 사항 누락 등)에서 코드를 리뷰한다.
• runtime-evaluator: 실제로 실행해 보며 거동을 검증한다. 정적 리뷰만으로는 찾아낼 수 없는 실행 시점(Runtime) 에러를 잡아낸다.

또 다른 한 세트는 기사 집필용 3종 세트다.

article-writer: 기사 본문을 작성한다 -
article-reviewer: 과장된 표현, 검증되지 않은 수치, 개인정보 침해 여부를 리뷰한다 -
article-reader: 독자 관점에서 이해하기 어려운 부분을 지적한다

이 두 세트의 공통점은 "쓰는 사람과 체크하는 사람을 분리한다"는 발상이다. 같은 Claude가 쓰고 같은 Claude가 체크하면, 자신이 쓴 것을 비판 없이 긍정하기 쉽다. 역할을 나눈 에이전트(Agent)에게 독립적으로 리뷰하게 함으로써 이러한 "자기 긍정 편향 (Self-affirmation bias)"을 피하고 있다.

그 외에도 Git 조작이나 파일 정리와 같은 복잡한 워크플로우를 총괄하는 navi, 외부 정보를 조사해 오는 researcher 등이 있다.

훅(Hook) 계층: 7개의 스크립트로 "말하지 않아도 움직이는" 환경 구축

훅(Hook)은 이벤트 발생형 자동화다. 나의 환경에서는 다음 7개를 실행하고 있다.

훅을 사용하는 판단 기준은 "매번 부탁하는 것이 번거로운가"이다. 예를 들어 push 금지는 CLAUDE.md에 적어두는 것만으로도 대부분 지켜진다. 하지만 "대부분"으로는 불충분한 조작(이력을 망가뜨리거나 기밀 정보를 포함하는 경우)은 PreToolUse 훅을 통해 명령 실행 자체를 차단하고 있다. 지시와 강제를 구분해서 사용하는 것이 포인트다.

또 하나 마음에 드는 것은 harness_audit.sh이다. 세션이 끝날 때마다 "스킬이 실제로 호출되었는지", "규칙이 형식적으로만 남지는 않았는지"를 기계적으로 체크하여 리포트를 남긴다. 하네스(Harness) 자체가 비대해지는 문제를 하네스 스스로가 감시하게 하고 있다.

메모리(Memory) 계층: 파일 기반의 기억과 retro 루프

메모리는 MEMORY.md(인덱스)와 그 아래에 매달려 있는 개별 파일군(사용자 프로필, 피드백, 진행 중인 프로젝트 등)으로 구성되어 있다. 세션 종료 시에는 retro 스킬이 대화를 되돌아보며, 학습 내용을 다음 세 곳 중 하나로 분류한다.

이 루프의 핵심은 "같은 실수가 반복된 횟수"를 의식적으로 확인하는 것이다. 한 번의 실수는 메모리에 기록하는 것만으로 충분하다. 하지만 같은 패턴의 실수가 여러 세션에 걸쳐 재발한다면, 그 자리에서 규칙으로 승격시킨다. 이것이 failure-promote 스킬의 역할이며, 기억을 "떠올리는 것"에서 "두 번 다시 일어나지 않게 하는 것"으로 격상시키는 메커니즘이다.

MCP도 기억을 보강하는 역할로 사용하고 있다. filesystem MCP로 로컬 파일에 대한 액세스를, local-rag MCP로 뉴스나 문서를 의미 검색(Semantic search)할 수 있도록 하고 있다. 이를 통해 "과거에 읽은 자료의 내용을 기억하고 있는" 상태에 가깝게 만들고 있다.

하루 개발 플로우 실례

실제 하루의 흐름을 전형적인 패턴으로 재현하면 다음과 같다.

나: "어제 버그 수정하던 부분부터 이어서"
[UserPromptSubmit hook 발생]
→ harness_inject.sh 가 최근의 feedback.md 내용을
...

이 플로우에서 내가 하는 일은 "이어서"라고 말하는 것과, planner·evaluator의 판단을 승인하는 것 정도다. 문맥의 재현, 규칙의 적용, 리뷰, 회고의 대부분은 시스템 측에서 담당한다.

앞으로 개선하고 싶은 점

아직 이상적인 형태와는 거리가 있는 부분도 있다.

스킬·에이전트의 카탈로그화: 20개, 12체까지 늘어나면 어떤 스킬이 어떤 상황에서 발생하는지 나 자신도 잊어버리게 된다. 일람성을 갖춘 문서가 필요하다 -
훅의 에러 핸들링 강화: 현재는 셸 스크립트가 단순히 동작하고 있는 부분이 있어, 훅 자체가 실패했을 때의 알림이 약하다 -
메모리 파일의 비대화 대책: MEMORY.md를 인덱스 방식으로 구성해도 상세 파일의 수는 계속 늘어난다. 정기적인 정리(Inventory) 메커니즘을 어떻게 자동화할지가 과제

환경은 완성품이 아니라, 실패할 때마다 한 줄씩 키워나가는 것이라고 생각한다.

요약

• 설정(Setting) → 스킬(Skill) → 에이전트(Agent) → 훅(Hook) → 메모리(Memory)의 5층 구조로 구성하여, "매번 구두로 설명하는 것"을 줄이고 있다
• 스킬은 절차의 고정, 에이전트는 판단의 위임, 훅은 강제, 메모리는 기억의 인계라는 역할 분담을 하고 있다
• 쓰는 사람과 체크하는 사람을 분리함으로써 자기 확증 편향(Self-confirmation bias)을 피하고 있다
• 하네스(Harness) 자체의 건전성을 하네스가 직접 감시하게 함으로써, 비대화를 감지할 수 있도록 하고 있다
• 환경은 한 번 만들고 끝나는 것이 아니라, 실패할 때마다 키워나가는 것이다

이 환경을 구축하는 방법을 설계 사상부터 구현 절차까지 더욱 체계적으로 해설하고 있는 것이 유료 도서 「Claude Code 하네스 엔지니어링 실전 Playbook」이다.

좋아요나 댓글로 반응해 주시면 큰 힘이 됩니다!

Discussion