작은 자동화가 주는 큰 편함: CLAUDE.md 자동 생성 플러그인 만들기

Claude Code를 사용하면 CLAUDE.md 파일을 작성해야 하고 이 파일을 "잘" 작성해야 효율적인 컨텍스트 관리와 재작업을 줄일 수 있습니다.

매번 새로운 프로젝트를 할 때마다 작성하는데 기술 스택은 뭔지, 커밋 컨벤션은 어떻게 할 건지, 테스트 전략은 뭔지 — 매번 손으로 작성하거나, 기존 프로젝트에서 복붙하고 조금씩 고쳐야 합니다. 규칙 파일, 스킬 파일도 마찬가지입니다.

그래서 ! 어느 순간 이 반복이 피로하게 느껴졌어요.

왜 귀찮은가

/init 명령어도 있긴 합니다. 하지만 결과물이 너무 generic합니다. 프로젝트 특성을 거의 반영하지 못하고, 결국 손으로 다듬는 시간이 따로 발생합니다.

대충 머릿속으로 원하는 방향을 떠올렸을 때 아래와 같았어요.

• 프로젝트 구조를 스스로 읽습니다.
• 어떤 스택인지, 어떤 패턴인지 파악합니다.
• 모호한 부분을 사용자에게 질문합니다.
• 곧바로 쓸 수 있는 CLAUDE.md와 규칙들을 만들어 줍니다.

만들자

그래서 만든 게 claude-auto-setup-plugin입니다. Claude Code 플러그인으로 /auto-setup 명령어 하나로 실행되며 내부는 4개의 에이전트가 순서대로 돌아가는 파이프라인입니다.

setup-analyzer (Haiku) : 프로젝트 구조, 언어, 프레임워크 분석

setup-interviewer (Sonnet) : 분석 결과 기반으로 맞춤 질문 (사용자와 대화)

setup-generator (Sonnet) : CLAUDE.md, rules, skills 생성

setup-reviewer (Sonnet) : 품질 검증, 미흡하면 재생성 루프

첫 번째 에이전트(Haiku)가 코드베이스를 빠르게 훑어 전반적인 프로젝트를 파악하고, 그 결과를 가지고 두 번째 에이전트가 사용자에게 의미 있는 질문만 던집니다. 예로 인증 관련 내용이 프로젝트에 있다면 "어디에 인증 코드가 있나요?" 같은 걸 묻는 게 아니라, "JWT 말고 세션 방식도 고려하고 있나요?" 수준의 질문이 나오길 원했습니다.

하네스 엔지니어링, 에이전트를 믿게 만드는 구조

멀티 에이전트를 만들면서 단순히 "에이전트를 연결"하는 것 이상이 필요하다는 걸 느꼈습니다.

에이전트는 자율적으로 움직이고 행동하지만 그 자율성이 의도한 방향으로 흐르도록 하는 하네스가 강제되어야 한다고 생각합니다. 하네스란 에이전트의 입출력, 실행 순서, 실패 처리, 품질 기준을 정의하는 안전한 가드레일이라고 보시면 됩니다.

이 프로젝트에서 하네스 엔지니어링 관점에서 신경 쓴 부분은 세 가지가 있습니다.

1. 역할에 맞는 모델 선택

모든 에이전트에 같은 모델을 쓸 필요가 없습니다. 탐색(분석)은 속도가 중요하고, 생성·검증은 품질이 중요합니다. 따라서 아래와 같이 구성했습니다.

에이전트	모델	이유
setup-analyzer	Haiku	빠른 코드 탐색, 비용 최소화
setup-interviewer	Sonnet	맥락 이해 기반 질문 생성
setup-generator	Sonnet	품질 높은 문서 생성
setup-reviewer	Sonnet	세밀한 검증 판단

Haiku로 사실을 수집하고, Sonnet으로 판단하는 구조. 이 조합만으로 비용과 품질의 균형이 잘 잡히도록 했습니다.

2. 품질이 안 되면 다시

setup-reviewer 가 결과물을 검토해서 기준 미달이면 setup-generator로 다시 돌립니다. 사람이 "이거 좀 이상한데?"라고 느끼는 순간을 에이전트가 대신 잡아내는 구조입니다.

이 루프가 없다면 나쁜 결과물이 그냥 사용자한테 넘어오고 그걸 또 재작업하는 형태가 됩니다. 제가 생각하는 하네스의 핵심은 실패를 조용히 넘기지 않는 것입니다.

3. 앞 에이전트의 결과가 다음 에이전트의 입력

각 에이전트는 이전 에이전트의 결과를 컨텍스트로 받습니다. setup-analyzer가 "이 프로젝트는 Spring Boot + JPA 기반"이라는 사실을 파악하면, setup-interviewer는 그 사실을 전제로 질문을 구성합니다.

에이전트를 단순히 병렬로 풀어놓는 게 아니라, 정보가 축적되면서 흐르는 시퀀셜 파이프라인으로 설계한 이유입니다.

그래서 뭐가 달라졌나?

클로드 코드에서 세팅 후 실행하면 출력물은 세 가지입니다.

• .claude/CLAUDE.md — 프로젝트 규칙, 아키텍처, 패턴 정리
• .claude/rules/ — 코딩 제약사항
• .claude/skills/ — 반복 작업 워크플로우

기존 30분~1시간 걸리던 설정 작업이, 인터뷰 5분 포함해서 10분 안에 끝납니다. 그리고 결과물의 품질이 제가 대충 복붙했을 때보다 훨씬 구체적이라고 생각합니다.

느낀 점

혼자만의 불편함에서 시작한 작은 프로젝트지만, 이걸 만들면서 느낀 게 있습니다.

멀티 에이전트 파이프라인은 대규모 프로젝트를 만들 때만 쓰는 게 아니라고 생각합니다. 단순한 반복 작업, 특히 분석 → 질문 → 생성 → 검증처럼 단계가 명확하게 나뉘는 작업이라면 오히려 더 잘 맞습니다.

AI가 코드를 생성하더라도 결국 사람이 확인하고 검증을 합니다. 하지만 하네스를 잘 짜두면 에이전트를 믿고 맡길 수 있습니다. 결과를 매번 확인하지 않아도 되는 구조, 그게 자동화의 진짜 의미인 것 같습니다.

Repository

https://github.com/yhyuk/claude-auto-setup-plugin

GitHub - yhyuk/claude-auto-setup-plugin: 프로젝트 분석 후 맞춤 인터뷰를 통해 .claude/ 설정을 자동 생성하