모두가 프롬프트(prompts)를 수집하고 있습니다. 하지만 진짜 결과를 만들어내는 사람들은 다른 것을 구축하고 있습니다.

지난 연휴 동안, 제가 Claude Code를 사용하는 방식에 변화가 생겼습니다.

몇 달 동안 저는 이것을 매우 똑똑한 자동 완성(autocomplete) 기능처럼 취급했습니다. 터미널을 열고, 요청을 입력하고, 답변을 읽고, 반복하는 식이었죠. 작동은 했습니다. 결과물도 만들어냈습니다. 하지만 저는 다른 개발자들이 여러 개의 에이전트(agents)를 동시에 가동해 두고, 자리를 비웠다가 돌아와서 완성된 풀 리퀘스트(pull requests)를 검토하는 것에 대해 이야기하는 것을 계속 지켜보았습니다. 그것은 제 경험과는 전혀 달랐습니다. 제 경험은 마치 '베이비시팅(babysitting)'을 하는 것과 같았습니다.

그래서 저는 그들이 무엇을 다르게 하고 있는지 찾아 나섰고, 정답이 "더 나은 프롬프트"일 것이라고 완전히 예상했습니다. 심지어 남들이 다 말하는 것처럼 좋은 프롬프트들을 노트에 저장하며 저만의 작은 프롬프트 라이브러리를 만들기 시작하기도 했습니다.

하지만 프롬프트가 정답은 아니었습니다. 그 노트는 여전히 거의 사용되지 않은 채 그대로 놓여 있습니다.

제 결과를 실제로 변화시킨 것은 Claude Code가 다섯 가지의 뚜렷한 레이어(layers)를 가지고 있으며, 저는 그중 단 하나만을 사용하고 있었다는 사실을 깨달은 것이었습니다.

단일 도구의 문제

메시지 박스(message box)만 사용한다면, 모든 것이 그것을 거쳐야만 합니다. 프로젝트 컨벤션(Project conventions), 일회성 요청, 재사용 가능한 워크플로우(workflows), 안전 주의 사항 등 모든 것을 매 세션마다 새로 입력해야 합니다. 이는 마치 방 건너편에 대고 소리를 질러 팀을 운영하는 것과 같습니다. 잠시는 괜찮을지 몰라도, 곧 확장성(scaling)의 한계에 부딪힙니다.

두 가지 벽이 나타납니다. 첫 번째는 컨텍스트 부패(context rot)입니다. 리팩토링(refactor) 내용, 몇 개의 설계 문서, 마이그레이션(migration) 계획을 하나의 대화에 쏟아부으면, 창의 40% 지점을 지나면서 모델이 맥락을 놓치기 시작합니다. 20분 전에 내린 결정을 스스로 부정하기도 합니다. 이미 읽었던 파일을 다시 읽기도 합니다. 제가 접한 Databricks의 연구에 따르면, 모델의 정확도가 광고된 한계치에 도달하기 훨씬 전인 약 32,000 토큰(tokens) 부근에서 떨어지기 시작한다고 합니다. 이는 제가 정확히 느끼고 있던 바와 일치했습니다.

두 번째 벽은 기억 상실(amnesia)입니다. 에이전트가 작업을 잘 수행하더라도, 터미널을 닫으면 다음 날 그 어떤 것도 이어지지 않습니다. 귀하의 명명 규칙(naming conventions), 금지된 라이브러리, 팀의 커밋(commits) 포맷 방식 등이 모두 사라집니다. 당신은 그것을 다시 설명해야 합니다. 그리고 또 반복해야 합니다.

이 중 그 어느 것도 프롬프트(prompt)의 문제는 아닙니다. 문장 하나로 해결될 수 있는 것도 아닙니다. 이것들은 시스템의 문제이며, 시스템적인 해답이 필요합니다.

가장 저렴한 것부터 가장 강력한 것까지, 5가지 계층

저의 관점을 완전히 바꿔놓은 모델을 소개합니다. Claude Code는 5가지 계층으로 구축되어 있으며, 이들은 저렴하고 항상 존재하는 것부터 강력하고 비용이 많이 드는 것까지 단계별로 실행됩니다.

CLAUDE.md가 가장 상위에 위치합니다. 이는 저장소(repo) 루트에 있는 일반 마크다운(markdown) 파일로, 당신이 무엇인가를 입력하기 전 모든 세션에 자동으로 로드됩니다. 이곳에 고정된 규칙들이 존재합니다. 당신의 기술 스택(stack), 관례(conventions), 허용하지 않는 라이브러리, 그리고 '완료(done)'가 실제로 무엇을 의미하는지 등이 여기에 담깁니다.

다음은 MCP 서버(MCP servers)입니다. 이들은 에이전트(agent)를 외부 세계, 즉 당신의 GitHub, 데이터베이스, 웹 페처(web fetcher)와 연결합니다. MCP 서버가 없다면 에이전트는 눈앞에 있는 파일들만 볼 수 있습니다.

스킬(Skills)은 에이전트가 스스로 실행하는 재사용 가능한 워크플로(workflows)입니다. 스킬은 설명이 포함된 아주 작은 폴더이며, 당신의 요청이 그 설명과 일치하면 Claude는 요청받지 않아도 이를 가져와 실행합니다. "소스 파일을 편집한 후, 린터(linter)를 실행하고 경고를 수정하라"는 하나의 스킬입니다. 한 번 작성해 두면 다시는 기억할 필요가 없습니다.

훅(Hooks)은 가이드레일(rails)입니다. 스킬이 에이전트가 사용하기로 선택하는 것이라면, 훅은 시스템이 강제하는 것입니다. "테스트에 실패하는 모든 커밋(commit)을 차단하라"는 훅입니다. 이는 에이전트의 의사와 상관없이 실행됩니다.

서브에이전트(Subagents)는 팀입니다. 각각은 자신만의 컨텍스트 윈도우(context window), 프롬프트(prompt), 도구(tools)를 가진 별도의 인스턴스입니다. 코드 리뷰나 조사 작업(research detour)을 서브에이전트에게 위임하면, 복잡한 작업은 다른 곳에서 처리되는 동안 당신의 메인 세션은 깔끔하고 집중된 상태를 유지할 수 있습니다.

제가 기억하는 핵심 패턴은 이것입니다: 문제를 해결할 수 있는 가장 가벼운 계층을 활용하십시오. 대부분의 사항은 CLAUDE.md나 스킬에 속해야 합니다. 서브에이전트는 작업이 진정으로 독립된 공간을 가질 가치가 있을 때만 가동하십시오.

가장 큰 효과를 낸 파일

만약 단 한 가지만 변경해야 한다면, 그것은 바로 CLAUDE.md로 만드십시오.

저는 그동안 제 파일을 인간을 위한 친절한 프로젝트 설명서인 README처럼 취급해 왔습니다. 그것이 실수였습니다. 그것은 문서(documentation)가 아닙니다. 그것은 명령형(imperative)으로 작성된 에이전트(agent)를 위한 운영 지침(operating instructions)입니다. '이것을 하라. 저것은 절대 하지 마라. 완료된 상태는 이러하다.'와 같은 지침 말입니다.

제 파일은 약 30줄 정도입니다. 스택(Stack)과 버전(versions), 테스트 및 린트(lint)를 위한 명령어, 짧은 컨벤션(conventions) 목록, 그리고 제가 수정하느라 지쳤던 네 가지 사항을 담은 "하지 마시오(do NOT)" 섹션이 있습니다. 또한 테스트를 통과하고 린트가 깨끗해질 때까지는 변경 사항이 완료된 것이 아니라고 명시하는 완료 정의(definition of done)도 포함되어 있습니다.

이 단 하나의 파일이 다른 어떤 것을 건드리기 전에 제 일상적인 마찰(friction)의 대부분을 제거해 주었습니다. 에이전트는 우리가 금지한 라이브러리를 제안하는 것을 멈췄습니다. 스스로 파일 이름을 지어내는 것도 멈췄습니다. 시키지 않아도 테스트를 실행하기 시작했습니다. 이 중 어느 것도 영리한 프롬프트(prompt)에서 나온 것이 아닙니다. 에이전트가 매번 읽는 30줄의 내용에서 나온 것입니다.

한 가지 알아둘 점은, CLAUDE.md의 모든 줄은 매 세션마다 로드되므로 영구적으로 컨텍스트 예산(context budget)을 소모한다는 것입니다. 내용을 간결하게 유지하십시오. 집중된 40줄짜리 파일이 방대한 300줄짜리 파일보다 낫습니다. 방대한 파일은 실제 작업에 필요한 컨텍스트 창(window)을 조용히 갉아먹기 때문입니다.

기술(Skills), 또는 내가 반복을 멈춘 방법

CLAUDE.md 이후, 다음 단계의 도약은 기술(skills)이었습니다.

깨달음은 간단했습니다. 제가 반복해서 요청했던 것들은 창의적인 결정이 아니었습니다. "수정 후에 린터를 실행해라", "커밋을 우리 형식에 맞춰 작성해라", "완료하기 전에 인젝션(injection) 여부를 확인해라"와 같은 것들 말입니다. 이것들은 워크플로우(workflows)이며, 워크플로우는 파일이 될 수 있습니다.

기술(skill)은 단순히 내부에 SKILL.md가 들어 있는 폴더일 뿐입니다. 두 부분으로 구성됩니다. 해당 기술이 언제 관련이 있는지를 Claude에게 알려주는 설명(description)과 실제 지침이 담긴 본문(body)입니다. 설명 부분이 가장 중요한데, 왜냐하면 Claude가 해당 기술을 실행할지 여부를 결정하기 위해 이를 읽기 때문입니다. 모호한 설명은 절대 트리거(trigger)되지 않습니다. 정밀한 설명만이 신뢰할 수 있게 트리거됩니다.

이제 저는 제가 의식하지 않아도 거의 매 세션마다 실행되는 작은 세트(set)를 갖게 되었습니다. 수정 후 린트(Lint) 수행, 테스트 실행, 커밋(commit) 메시지 제대로 작성하기, 실제 설명을 포함하여 PR(Pull Request) 열기 등입니다. 에이전트(agent)는 적절한 순간에 스스로 각 작업을 실행합니다. 이 지점이 바로 Claude Code가 단순한 챗봇(chatbot)처럼 느껴지는 것을 멈추고, 규율을 갖춘 팀원(teammate)처럼 느껴지기 시작한 지점이었습니다.

만약 제가 오늘 다시 시작한다면

저는 단 한 번의 오후 만에 다섯 가지 레이어(layer)를 모두 설치하려고 시도하지 않을 것입니다. 그렇게 하면 이해할 수 없는 엉망진창인 상태에 빠지게 됩니다.

먼저 가장 활발하게 사용하는 레포지토리(repo)를 열고, 해당 프로젝트에 맞게 조정된 약 30줄 정도의 CLAUDE.md 파일을 작성할 것입니다. 그다음 세 가지 기술(skills)을 추가하겠습니다: 수정 후 린트(lint), 테스트 실행, 커밋 작성. 그리고 새로운 세션을 시작하여 무언가를 변경해 달라고 요청한 뒤, 린터(linter)가 스스로 실행되는 것을 지켜볼 것입니다. 바로 그 순간 모든 것이 이해되기 시작합니다.

서브에이전트(subagents)와 훅(hooks)은 기초가 습관으로 자리 잡은 후에 도입합니다. 필요할 때마다 생성할 수 있는 코드 리뷰어(code reviewer)와 디버거(debugger), 그리고 실패한 코드가 커밋에 도달하는 것을 거부하는 훅(hook) 같은 것들 말입니다. 각 요소는 그것이 필요하다고 느끼는 시점에 제 자리를 찾게 됩니다.

Claude Code의 30% 성능을 내는 것과 모두가 이야기하는 결과를 얻는 것 사이의 격차는 결코 프롬프트(prompt)의 문제가 아니었습니다. 그것은 프롬프트를 둘러싼 시스템(system)의 문제였습니다. 일단 시스템을 구축하고 나면, 프롬프트는 거의 부차적인 문제가 됩니다.

바로 복사해서 사용할 수 있는 전체 구성이 필요하다면

저는 이 모든 내용을 복사해서 바로 사용할 수 있는 전체 파일들과 함께 'The Claude Code Operating System'이라는 현장 매뉴얼(field manual)로 정리했습니다. 여기에는 실전에서 검증된 CLAUDE.md, 8가지 프로덕션 기술(production skills), 12가지 서브에이전트(subagents), 그리고 안전 훅(safety hooks)이 포함되어 있으며, 레포지토리에 바로 넣어서 몇 분 안에 작동시킬 수 있는 실제 .claude/ 폴더 키트도 함께 제공됩니다.

👉 여기서 확인하실 수 있습니다: https://growthlibstore.gumroad.com/l/TheClaudeCodeOperatingSystem

만약 이 글에서 단 하나의 아이디어만 가져가야 한다면, 바로 이것을 가져가십시오. 당신이 입력하는 문장을 최적화하는 것을 멈추고, 에이전트 (Agent)가 실행되는 시스템을 구축하기 시작하십시오. 그것이 핵심적인 전환입니다.