Claude Code를 미니멀하게 운용하기

서론

Claude Code를 업무나 개인 개발에 도입하고 싶다. 하지만 Skill / Hook / Agent / CLAUDE.md / 서브 에이전트 (Sub-agent) / 하네스 엔지니어링 (Harness Engineering)…… 새로운 용어들이 속속 등장하여 무엇부터 시작해야 할지 모르는 사람도 많지 않을까.

개인적인 결론은, 표준 기능에 약간의 살을 붙이는 정도가 딱 적당하다.

• Claude Code의 표준 스킬 (Skill)을 활용한다
• 인간이 눈으로 쫓을 수 있는 자산 (SKILL / Agent / CLAUDE.md 등)을 중시한다
• Hook은 인간에게도 유익한 것을 중심으로 한다
• 프로젝트 고유의 Skill을 준비한다 ("이런 순서로 진행해 주었으면 좋겠다"라고 쓸 수 있으면 된다)
• 한 작업을 마친 후에는 회고를 한다.

이것만으로 개인 개발용 프리 소프트웨어 2개와 Salesforce 2GP 매니지드 패키지(Managed Package) 2개(심사에는 제출하지 않았지만)를 만들 수 있었다. 프로젝트를 넘나들며 Skill이 재사용될 수 있을 정도로 추상화가 성립되어 있다.

규모와 적용 범위

본 기사는 개인 개발 규모 (1인 / 수 대의 머신)에서의 실천 기록이다.

미니멀 운용 5개 항목은 팀 개발의 기초로서도 사용할 수 있다는 가정하에 작성했다. "개인이니까 이것으로 충분하다, 조직이라면 다른 무언가가 필요하다"가 아니라, "개인이든 조직이든 이것이 토대이며, 조직에서는 그 위에 메커니즘을 추가한다"라는 구조로 생각하고 있다.

미니멀 운용 5개 항목

1. Claude Code의 표준 스킬을 활용한다

처음에 사용하면 좋은 것이 Anthropic 공식이 제공하는 표준 스킬군이다. 대표적인 것은 다음과 같다.

스킬 / 플러그인	역할
claude-md-improver	CLAUDE.md 채점 / 오래된 기술(記述) 검출 / 개선 제안
claude-automation-recommender	새로운 Skill / Hook 제안
skill-creator	대화 형식의 Skill 생성

이것으로 Claude Code를 사용하는 데 필요한 것은 일단 모두 갖춰진다.

2. 인간이 눈으로 쫓을 수 있는 자산을 중시한다

Claude Code의 핵심 자산은 모두 Markdown으로 작성되어 있다.

• SKILL.md (태스크 단위의 절차서)
• Agent 정의 (.claude/agents/*.md)
• CLAUDE.md (프로젝트 전체의 메모리)
• AGENTS.md (프로젝트 고유의 문서)
• Rules (.claude/rules/*.md)

이것들은 모두 Claude가 읽을 뿐만 아니라, 인간이 읽고 쓸 수 있으며 버전 관리도 가능하다. 바이너리나 독자적인 포맷을 처음부터 도입하면 유지보수도 이식도 할 수 없게 된다.

미니멀 운용에서는 Claude가 읽는 정보와 인간이 읽는 정보를 동일한 매체로 다루는 것을 우선시하고 있다.

• Skill의 설명은 markdown으로 작성한다 (frontmatter + 본문)
• Agent 정의도 markdown으로 작성한다
• 프로젝트 고유의 문맥은 CLAUDE.md / AGENTS.md에 집약한다
• 로그나 관찰은 구조화된 텍스트 (JSONL 등)로 한다

Claude를 위한 문서가 그대로 팀의 온보딩 (Onboarding) 자료가 되는 부수적인 효과가 발생한다.

3. Hook은 인간에게도 유익한 것을 중심으로 한다

Hook은 Claude Code의 이벤트 (PreToolUse / PostToolUse / SessionStart 등)에 따라 기동하는 스크립트다. Claude를 제어하기 위한 강력한 메커니즘이지만, 처음에는 인간에게도 유익한 것만 넣는다.

구체적인 예:

• main 브랜치에 직접 push 하지 않기 (block-main-commit)
• PR 생성 전에 코드 리뷰를 실행하기
• 파일 저장 시 lint / test를 자동 실행하기
• commit message 규약을 체크하기

흔히 있는 개발 환경의 자동 체크라고 생각한다.

반대로, AI 전용의 정교한 Hook (Claude의 거동을 세밀하게 제어하는 hook, Claude만을 위해 존재하는 자동화)은 미니멀 운용에서는 넣지 않는다. 진부화가 빠르고, "AI를 위해 특별한 무언가를 익혀야 한다"라는 부담을 팀에 강요하기 때문이다.

「인간에게도 기쁜가」를 Hook 채용의 판단 기준으로 삼으면, 결과적으로 AI를 사용하지 않는 멤버에게도 받아들여질 수 있는 하네스 (Harness)가 만들어진다.

4. 프로젝트 고유의 Skill을 준비하기

표준 스킬 (Standard Skill)은 범용적이지만, 프로젝트 고유의 문맥 (Context)은 그 안에 포함되어 있지 않다. "우리 DB는 이 구조다", "우리 배포는 이 순서다", "이 기능을 변경할 때는 이 파일도 확인한다"와 같은 구체적인 절차는 직접 작성할 필요가 있다.

미니멀 운용에서는 "이런 순서로 진행해 주었으면 좋겠다"라고 쓸 수 있는 정도면 충분하다. 정교한 Skill을 쓰려고 하면 좌절하게 되지만, 신입 사원에게 OJT (On-the-Job Training)로 설명할 때의 어휘로 쓰면 된다. 예를 들어,

• 이 프로젝트에서 X 기능을 추가할 때는, 먼저 A 파일을 보고, 다음으로 B를 편집하며, 마지막으로 C의 테스트를 업데이트한다
• 이 리포지토리 (Repository)에서는 PR (Pull Request)을 보내기 전에, 반드시 Y 명령어로 lint를 실행한다
• 이 기능을 수정할 때, Z의 제약 사항 (예: 하위 호환성)을 어겨서는 안 된다

이것들을 SKILL.md의 frontmatter (description)와 본문에 작성한다. frontmatter의 description은 Claude가 "이 Skill을 호출해야 하는가"를 판단하기 위한 색인 (Index)이므로, 트리거 조건 (Trigger condition)을 명확하게 쓰는 것이 요령이다.

정교하게 만드는 것은 외부 리소스 (scripts/나 references/) 측에서 하며, 그것은 Skill과는 독립적으로 키워나가면 된다. Skill 본체는 얇게 유지하고, 필요한 정보를 필요한 때에 전달하기 위한 색인이라고 단정 짓는다.

5. 한 작업이 끝나면 회고를 한다

미니멀 운용의 마지막 기둥은 회고 (Retrospective)다.

나는 retrospective라는 이름을 붙여 다음과 같은 내용으로 구성하고 있다.

### 좋았던 점
- 계획대로 진행된 점, 잘 이루어진 판단
- 효과적이었던 패턴이나 수법
...

표준 claude-automation-recommender나 claude-md-improver와 조합하면 더욱 효과적이다.

마치며

Claude Code 도입을 망설이고 있는 사람에게 가장 먼저 전하고 싶은 말은, "무겁게 시작할 필요는 없다"는 것이다. 표준 스킬을 활용하고, 인간이 읽고 쓸 수 있는 문서를 준비하며, 인간에게도 기쁜 Hook을 배치하고, 프로젝트 고유의 Skill을 가볍게 작성하며, 회고 루프 (Retrospective loop)를 돌린다. 이것만으로도 개인 개발 프리 소프트웨어부터 업무 시스템까지 실용적인 수준으로 동작한다.

새로 온 사람이 즉시 개발할 수 있게 만드는 것과 (개발의 재미가) 놀라울 정도로 일치한다. Anthropic이 Claude를 지성체로 대우하고 있으니 그리 이상한 일도 아니다.