AI 협업 시스템 만드는 법 2026 – CLAUDE.md Skills 검증 루프를 나누는 순서

Posted on by

AI 협업 시스템은 프롬프트를 더 길게 쓰는 기술이 아니라, 다음 세션이 덜 헤매게 만드는 운영 구조다. 2026년 기준으로는 CLAUDE.md, Skills, hooks, 시트 원장, preflight 같은 장치를 어디에 둘지 나누는 쪽이 훨씬 중요해졌다.

이 볼트에서도 같은 문제가 반복된다. 글감팀은 Google Sheets를 원장으로 쓰고, 파이프라인팀은 draft, review, publish, sync를 거치며, 각 팀 문서는 .claude/agents/ 아래에 쪼개져 있다. 처음엔 문서가 많아 보이지만, 실제로는 “항상 읽을 규칙”과 “필요할 때만 읽을 절차”를 분리한 구조다.

지금 결론은 이렇다. CLAUDE.md에는 항상 지켜야 할 행동 기준만 두고, 반복 업무는 Skill이나 agent runbook으로 뺀다. 반드시 실행돼야 하는 검증은 hooks나 preflight script로 내려야 한다.

먼저 나눌 기준

AI 협업 시스템을 만들 때 제일 먼저 정할 질문은 “무엇을 어디에 적을까”다. 모든 규칙을 한 파일에 몰아넣으면 시작은 편하지만, 몇 주 지나면 모델도 사람도 충돌을 찾기 어려워진다.

Anthropic의 Claude Code memory 문서는 CLAUDE.md가 조직, 사용자, 프로젝트, 로컬 범위로 나뉠 수 있다고 설명한다. 프로젝트 instructions는 팀이 공유하는 빌드 명령, 테스트 명령, 아키텍처 결정, 공통 workflow를 담는 용도에 가깝다. 반대로 개인 sandbox URL이나 임시 테스트 데이터는 로컬 지시로 분리하는 편이 안전하다.

실무 기준으로는 아래처럼 나누면 덜 꼬인다.

넣을 곳 맡길 내용 넣으면 안 좋은 내용
CLAUDE.md 항상 지켜야 할 프로젝트 규칙, 금지 행동, 경로 정책 매번 달라지는 긴 업무 절차
Skill 주 1회 이상 반복되는 입력-절차-검증-출력 흐름 한 번만 쓸 뉴스 요약
Agent runbook 여러 워커가 나뉘는 팀 작업, gate 기준 개인 취향 메모
Hook / script 반드시 실행돼야 하는 포맷터, preflight, 알림 모델 판단이 필요한 글쓰기
Sheet / status file 상태 지속, URL, publish 결과, 다음 점검일 장문 리서치 본문

이 표의 핵심은 “AI가 읽어야 할 것”과 “기계가 실행해야 할 것”을 섞지 않는 것이다. 모델에게 “항상 테스트해”라고 말하는 것보다 blog_preflight_check.py처럼 실패하면 막히는 검문을 두는 편이 재현성이 높다.

1단계: CLAUDE.md는 헌법처럼 짧게 쓴다

CLAUDE.md는 프로젝트에 들어온 AI가 처음 읽는 운영 규칙이다. 그래서 여기에 들어갈 내용은 자주 바뀌는 할 일 목록이 아니라, 바뀌면 안 되는 행동 기준이어야 한다.

예를 들어 이 볼트의 운영 규칙에는 no-focus Obsidian 원칙, .claude/ 공통 사용, 경로 하드코딩 금지, 블로그 작성 시 규칙 문서 확인 같은 기준이 들어 있다. 이런 규칙은 거의 모든 작업에 영향을 주므로 시작 문서에 들어갈 가치가 있다.

반대로 “오늘 Google AI 검색 글을 발행한다” 같은 작업 지시는 CLAUDE.md에 넣으면 안 된다. 그건 backlog, task note, 또는 이번 세션의 사용자 지시로 충분하다. 헌법에 오늘 점심 메뉴까지 적으면 나라가 아니라 식단표가 된다. 괜히 국정이 배고파진다.

Claude Code 공식 memory 문서도 모호하거나 충돌하는 지시는 따르기 어려워질 수 있다고 경고한다. “잘 작성해”보다 “frontmatter에 seo_title, meta_description, focus_keyphrase, tags를 넣어라”가 훨씬 낫다.

2단계: Skills는 반복 업무를 접는 폴더다

Skills는 길고 반복되는 업무를 매번 프롬프트에 붙이지 않기 위한 장치다. Anthropic의 Agent Skills 문서는 Skill이 instruction, executable code, reference materials를 폴더로 묶고, 필요한 단계에서만 내용을 읽는 progressive disclosure 구조라고 설명한다.

이 말은 꽤 실용적이다. 스킬 설명 메타데이터는 가볍게 항상 노출되고, 실제 SKILL.md는 필요할 때만 읽히며, 추가 참고 파일이나 스크립트는 더 필요할 때만 열린다. 반복 업무가 커질수록 이 차이가 체감된다.

블로그 운영으로 치면 “글감 수집”은 하나의 Skill이나 agent team으로 빼기 좋다. 입력은 Inbox, 분석 보드, Search Console 신호이고, 절차는 후보 선별, 중복 제거, Sheets 저장이며, 출력은 TOP7과 sync 결과다. 매번 이걸 프롬프트로 다시 설명하면 인간도 질리고 모델도 슬슬 표정이 없어질 것이다.

좋은 Skill은 문서 뭉치가 아니라 실행 단위다. 입력 -> 절차 -> 검증 -> 출력 네 줄로 요약되지 않으면 아직 Skill이 아니라 참고 문서일 가능성이 높다.

3단계: hooks와 preflight는 모델에게 부탁하지 않는다

반드시 실행돼야 하는 일은 모델의 선의에 맡기면 안 된다. Claude Code hooks 문서는 lifecycle의 특정 지점에서 shell command, HTTP endpoint, LLM prompt를 자동 실행할 수 있다고 설명한다. 즉 “상황이 오면 무조건 실행되는 장치”다.

블로그 파이프라인에서는 이 역할을 preflight script가 맡고 있다. Markdown 파일에 필수 frontmatter가 없거나, 금지된 AI식 헤더가 있거나, FAQ와 출처가 빠지면 발행을 막는다. 이건 글쓰기 취향이 아니라 운영 품질 검문이다.

AI 협업 시스템에서도 같은 기준을 적용하면 된다. 코드라면 formatter, test, typecheck, secret scan을 hooks나 CI로 둔다. 문서라면 lint, 링크 검사, frontmatter 검사, 출처 검사 같은 식이다.

여기서 중요한 구분이 있다. “이 문장이 독자에게 자연스러운가”는 모델이 판단할 일이고, “필수 섹션이 빠졌는가”는 스크립트가 판단할 일이다. 둘을 섞으면 검증이 감상문이 된다.

4단계: 상태는 대화창 밖에 남긴다

AI 협업이 복리처럼 쌓이려면 결과와 상태가 대화창 밖에 남아야 한다. 이번 세션에서 아무리 잘 정리해도, 다음 세션이 그 사실을 못 찾으면 복리가 아니라 일회성 할인쿠폰이다.

이 볼트의 블로그 파이프라인은 Google Sheets를 SSOT로 둔다. blog-ideas.md는 view 파일이고, 실제 상태는 Sheets의 idea_id, status, published_url, notes에 남는다. 그래서 글감팀이 저장한 후보를 파이프라인팀이 다시 불러오고, 발행 뒤에는 mark-published와 sync로 상태를 닫을 수 있다.

개발팀이라면 이 자리에 GitHub issue, Linear, Jira, Notion database, 또는 repo 안의 status file이 들어갈 수 있다. 핵심은 모델이 다음에 읽을 수 있고, 사람이 봐도 현재 위치를 알 수 있어야 한다는 점이다.

상태가 없으면 AI는 친절하게 같은 질문을 또 한다. 사람도 친절하게 또 답한다. 그렇게 친절한 무한루프가 생긴다. 업무 생산성의 적은 가끔 악의가 아니라 예의다.

5단계: 위임은 검증 가능한 단위로 쪼갠다

AI에게 일을 맡길 때 “알아서 잘해줘”는 좋은 목표가 아니다. 좋은 위임은 성공 조건, 입력 범위, 금지 행동, 검증 방법이 같이 붙는다.

예를 들어 “블로그 백로그 다 발행”이라는 요청도 내부에서는 두 개 레인으로 갈라진다. 각 레인은 idea 복원, 리서치, draft, preflight, review, publisher, sheet write-back을 거쳐야 한다. 중간에 preflight가 실패하면 발행하지 않는다.

코드 작업도 비슷하다. 한 에이전트에게 전체 앱을 맡기기보다, 한쪽은 인증 모듈, 다른 한쪽은 테스트 보강, 또 다른 한쪽은 문서 검증처럼 write set과 성공 기준을 나누는 편이 낫다. Anthropic의 Claude Code advanced patterns 자료도 큰 코드베이스에서 CLAUDE.md, hooks, MCP, 병렬 작업, worktree 격리를 함께 다룬다.

다만 병렬화는 만능이 아니다. 바로 다음 판단이 특정 결과에 막혀 있으면 직접 처리하는 게 빠르다. 위임은 일이 커졌을 때 쓰는 도구지, 책임을 증발시키는 향수는 아니다.

실수 TOP 5

첫 번째 실수는 CLAUDE.md를 일기장처럼 쓰는 것이다. 개인 취향, 오늘 할 일, 오래된 임시 규칙이 섞이면 프로젝트 규칙의 신뢰도가 떨어진다.

두 번째 실수는 Skill을 문서 창고로 만드는 것이다. Skill은 “읽을거리 모음”보다 “반복 가능한 업무 절차”에 가까워야 한다.

세 번째 실수는 검증을 말로만 두는 것이다. “꼭 테스트해”보다 npm test, pytest, markdown preflight, URL check처럼 실행 가능한 검증을 붙이는 편이 낫다.

네 번째 실수는 상태를 대화창에만 남기는 것이다. 대화는 흘러가고, 원장과 파일은 남는다. 남는 쪽이 시스템이다.

다섯 번째 실수는 모든 것을 AI에게 읽히는 것이다. 긴 참고자료는 resources로 두고, 필요한 순간만 열어야 한다. 컨텍스트 창은 창고가 아니라 작업대다.

언제 이 구조가 맞고, 언제 과한가

이 구조는 반복 작업이 있는 팀이나 개인에게 잘 맞는다. 블로그 발행, 리서치 정리, 코드 리뷰, 릴리즈 노트, 테스트 보강처럼 같은 흐름을 여러 번 돌리는 업무라면 금방 효과가 난다.

반대로 한 번만 할 작은 일에는 과하다. 파일 하나 고치고 끝날 작업에 .claude/agents/, Skills, hooks, Sheets까지 붙이면 자동화가 아니라 장식장이 된다.

내 기준은 간단하다. 같은 설명을 세 번 했다면 문서화 후보이고, 같은 절차를 세 번 돌렸다면 Skill 후보이며, 같은 실수를 세 번 막았다면 hook이나 preflight 후보다. 이 기준만 지켜도 시스템은 꽤 천천히, 하지만 덜 부서지게 자란다.

FAQ

Q. CLAUDE.md와 Skill의 차이는 뭐야?

CLAUDE.md는 프로젝트 전체에 항상 적용되는 기본 행동 규칙에 가깝다. Skill은 특정 작업이 들어왔을 때만 불러오는 반복 업무 절차다.

Q. CLAUDE.md에 모든 규칙을 넣으면 더 잘 따르지 않을까?

오히려 반대가 될 수 있다. Claude Code memory 문서는 큰 파일과 충돌 지시가 adherence를 떨어뜨릴 수 있다고 설명한다. 항상 필요한 규칙만 남기고 나머지는 scope를 나누는 편이 낫다.

Q. hooks는 꼭 써야 해?

항상 필요한 건 아니다. 다만 포맷팅, 테스트, 시크릿 검사, 발행 preflight처럼 실패하면 안 되는 검증은 모델에게 부탁하기보다 hook이나 script로 내리는 편이 안정적이다.

Q. 개인도 이런 시스템이 필요할까?

반복 작업이 있으면 필요하다. 개인 블로그라도 글감 수집, 초안 작성, preflight, 발행, URL 기록이 반복된다면 작은 시스템이 시간을 아껴준다.

Q. 제일 먼저 만들 것은 뭐야?

작은 CLAUDE.md와 하나의 checklist script부터 추천한다. 그다음 반복 업무 하나를 골라 SKILL.md로 빼면 된다.

공식 출처

관련 글