심화 과정에서 MCP, 스킬, 플러그인, 훅, 서브에이전트, 자동화까지 붙였습니다. 차에 비유하면 튜닝을 잔뜩 한 상태입니다. 이제 필요한 건 계기판 읽는 법과 정기 점검입니다. 기름(사용량)이 얼마나 남았는지, 트렁크(컨텍스트)가 얼마나 찼는지, 문(권한)은 잘 잠겨 있는지 — 이번 글은 그 계기판 사용 설명서입니다.

1 ★ 컨텍스트 관리 — 작업대 정리하기

컨텍스트는 Claude의 작업대입니다. 대화 내용, 읽은 파일, CLAUDE.md, 켜 둔 도구 설명이 모두 이 작업대 위에 올라갑니다. 작업대가 꽉 차면 오래된 것부터 흐릿해지고, 답이 느려지고 사용량도 늘어납니다.

# 긴 작업 중간에, 필요한 것만 남기고 압축
/compact 결정된 설계와 남은 할 일 목록만 남겨줘. 시행착오 과정은 빼도 돼.

언제 무엇을 쓰나

2 모델 · 노력 수준 고르기

모든 일에 가장 큰 모델을 쓰는 건, 편의점 가는데 트럭을 모는 것과 같습니다. 작업에 맞게 바꿔 타세요.

상황별 추천표

3 비용 · 사용량 — 계기판 보는 법

구독 요금제 vs API 과금 — 무엇이 다른가

4 권한 모드와 허용·차단 규칙

권한 모드는 "Claude가 얼마나 묻고 움직일지"를 정하는 운전 모드입니다. Shift+Tab 으로 default → acceptEdits → plan 순서로 바뀝니다(auto·bypass는 켜 둔 경우에만 순환에 들어옴).

따라해 보기 — .env 읽기 차단 규칙 — /permissions 로 규칙을 보거나, .claude/settings.json 에 직접 적습니다. 규칙은 deny → ask → allow 순서로 검사되므로 차단이 항상 이깁니다.

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

Cowork 승인 모드 (설정 > Cowork)

5 보안 점검 — 문단속 체크

회사 자료를 다룰 때 3원칙

6 정기 점검 루틴 — 한 달에 한 번 15분

자동차 정기 점검처럼 달력에 넣어 두세요. 10단계에서 배운 예약 작업으로 "점검 알림"을 만들어도 좋습니다.

# 점검 알림 예약 작업 프롬프트 예 (Cowork /schedule)
# 예약 빈도는 매시간·매일·매주·평일·수동 중에서 고르므로 "매주"로 두고,
# 한 달에 한 번은 꼼꼼히 읽는 식으로 쓰세요.
매주 월요일 오전 10시에
"Claude 정기 점검 목록"을 체크리스트 형태로 정리해 보여줘.
커넥터 정리, 안 쓰는 스킬·플러그인, 메모리 검토, 예약 작업 점검, claude update.
아무것도 직접 바꾸지는 마.

7 심화 과정을 마치며 & 전문가 과정 예고

여기까지 오셨다면 이제 Claude를 "시키면 해주는 도구"가 아니라 내 일에 맞게 조립하는 플랫폼으로 쓰고 계신 겁니다. 연결(MCP) → 매뉴얼(스킬) → 포장(플러그인) → 규칙(훅) → 팀(서브에이전트) → 자동화 → 운영까지, 12단계를 한 바퀴 돌았습니다.

연결 → 매뉴얼 → 포장 → 규칙 → 팀 → 자동화 → 운영

다음 전문가 과정에서는 "만들어진 것을 쓰는 사람"에서 "직접 만드는 사람"으로 한 걸음 더 나갑니다.

8 정리 & 체크리스트

지금까지 배운 기능들은 따로 보면 "있으면 편한 도구"입니다. 하지만 엮어 놓으면 작은 편집부가 됩니다. 자료 조사 담당, 작가, 교정 담당, 편집장 알람까지 — 그리고 편집장(나)은 마지막에 원고를 읽고 발행 버튼만 누르면 됩니다. 주제는 일부러 이 블로그 자체로 골랐습니다. 매주 Claude에 대한 가이드 글을 샘플 HTML 스타일로 쓰는 일, 바로 그 과정을 자동화합니다.

1 완성 그림 — 파이프라인 한눈에

자료 수집(웹 검색·MCP) → 초안(블로그 스킬) → 검수(리뷰 서브에이전트) → 정기 실행(예약 작업) → 포장(플러그인) → 사람이 발행

2 준비 — 프로젝트 폴더 구조

claude.ai 프로젝트로 쓰던 작업을 이번엔 내 컴퓨터 폴더로 옮깁니다. 폴더가 있어야 훅·서브에이전트·파일 저장까지 다 쓸 수 있기 때문입니다.

modulebit-blog/
├── CLAUDE.md                        # 블로그 운영 원칙 (항상 읽힘)
├── .claude/
│   ├── settings.json                # 훅 등록
│   ├── hooks/
│   │   └── check_html.py            # HTML 검사 스크립트
│   ├── skills/
│   │   └── tistory-guide-writer/
│   │       ├── SKILL.md             # 글쓰기 매뉴얼
│   │       └── references/
│   │           └── sample.html      # 스타일 기준 샘플
│   └── agents/
│       ├── fact-checker.md          # 사실 확인 담당
│       └── style-reviewer.md        # 스타일·맞춤법 담당
├── drafts/                          # AI가 쓴 초안 (검토 대기)
└── published/                       # 내가 발행한 최종본

# 터미널에서 뼈대 만들기 (맥·리눅스 기준)
mkdir -p modulebit-blog/.claude/{hooks,skills/tistory-guide-writer,agents} modulebit-blog/{drafts,published}
cd modulebit-blog
claude

3 1주차 — 뼈대 만들기 Day 1~5

Day 1~2 · CLAUDE.md 작성

CLAUDE.md는 "이 폴더에서 일할 때 항상 지킬 규칙"입니다. 스킬이 글 쓰는 방법이라면, CLAUDE.md는 이 블로그의 운영 원칙입니다. 짧고 단단하게 씁니다.

# 모듈비트 티스토리 블로그 작업 폴더

## 이 폴더는
- 모듈비트 티스토리에 올릴 Claude AI 가이드 글을 만드는 곳이다.
- 모든 글은 .cckr 스타일 HTML이며, 규칙은 tistory-guide-writer 스킬을 따른다.

## 폴더 규칙
- 새 초안은 반드시 drafts/ 에 저장한다. 파일명: YYYY-MM-DD-주제.html
- published/ 는 사람이 직접 옮기는 곳이다. 이 폴더의 파일은 절대 수정·삭제하지 않는다.

## 사실 원칙
- 명령어·메뉴 이름·요금·요금제별 지원 여부는 공식 문서나 출처로 확인한 것만 쓴다.
- 확인하지 못한 내용은 "설정 화면에서"처럼 일반적으로 쓰고, 초안 끝 메모에 남긴다.
- 가격·기능은 "2026년 9월 기준, 변동 가능"처럼 기준 시점을 적는다.

## 작업 순서
1. 초안 작성 후 fact-checker 로 사실 확인, style-reviewer 로 스타일 확인
2. 지적 사항을 반영해 다시 저장
3. 초안 맨 끝 HTML 주석에 "검수 요약"(확인한 출처, 남은 의문점)을 남긴다

## 하지 말 것
- 티스토리에 직접 발행하거나 로그인 시도하지 않는다.
- 실제 회사·고객 데이터를 예시에 넣지 않는다.

Day 3~4 · 글쓰기 스킬 가져오기

6단계에서 만든 블로그 스킬을 그대로 재사용합니다. 폴더째 .claude/skills/tistory-guide-writer/ 로 복사합니다(sample.html은 6단계처럼 references/ 안에). 아직 없다면 핵심만 이렇게 요약해 시작해도 됩니다.

---
name: tistory-guide-writer
description: 모듈비트 티스토리용 Claude 가이드 글을 .cckr 스타일 HTML로 작성할 때 사용
---
# 작성 순서
1. references/sample.html 의 상단 주석과 <style> 블록을 그대로 복사한다 (CSS 수정 금지)
2. 본문은 <div class="cckr"> 로 감싸고, 정의된 클래스만 사용한다
3. 모든 <p> 에 data-ke-size="size16", <h2> 에 data-ke-size="size26"
4. 구성: 머리말(cc-head) → 번호 붙은 h2 섹션 5~8개 → 체크리스트 → cc-foot
5. 말투: 존댓말, 일상 비유, 짧은 문장. 이모지는 ⏱ ★ ☐ 만

# 참고 파일
- 스타일 기준: ${CLAUDE_SKILL_DIR}/references/sample.html

Day 5 · 검수 서브에이전트 2명

검수를 작가와 같은 대화에서 하면 "자기 글에 관대한" 문제가 생깁니다. 별도의 컨텍스트를 가진 서브에이전트에게 맡기면 처음 보는 눈으로 읽어 줍니다. 두 파일을 .claude/agents/ 에 저장합니다.

.claude/agents/fact-checker.md

---
name: fact-checker
description: 블로그 초안 속 명령어·메뉴·요금·기능 설명이 사실인지 확인할 때 사용. 초안 작성 직후 반드시 사용.
tools: Read, Grep, Glob, WebSearch, WebFetch
model: sonnet
---
너는 IT 기술 블로그의 사실 확인 담당이다. 글을 고치지 말고 보고만 한다.

## 확인 대상
- 명령어, 옵션(플래그), 파일 경로, 메뉴 이름
- 요금제별 지원 여부, 가격, 제한(횟수·용량)
- "최근", "새로" 같은 시점 표현

## 방법
1. 초안에서 확인할 문장을 목록으로 뽑는다
2. 공식 문서(code.claude.com, support.claude.com, anthropic.com)를 우선 확인한다
3. 공식 출처가 없으면 "미확인"으로 둔다. 추측으로 "맞음" 처리하지 않는다

## 보고 형식
| 문장 | 판정(맞음/틀림/미확인) | 근거 URL | 수정 제안 |
마지막에 "반드시 고칠 것" 3개 이내로 요약.

.claude/agents/style-reviewer.md

---
name: style-reviewer
description: 블로그 초안이 모듈비트 .cckr 스타일 규칙과 말투를 지키는지 검토할 때 사용
tools: Read, Grep, Glob
model: haiku
---
너는 블로그 편집자다. 글을 고치지 말고 지적 목록만 돌려준다.

## 점검 항목
1. 상단 주석과 <style> 블록이 sample.html 과 동일한가
2. 정의되지 않은 클래스나 인라인 style 을 쓰지 않았는가
3. 모든 <p> 에 size16, <h2> 에 size26 이 있는가
4. 존댓말이 일관적인가, 문장이 너무 길지 않은가(한 문장 80자 안팎)
5. 맞춤법·띄어쓰기, 이모지 사용 규칙(⏱ ★ ☐ 외 금지)
6. 체크리스트와 cc-foot(이전 글·다음 글·공식 문서)이 있는가

## 보고 형식
심각도(높음/보통/낮음) · 위치(섹션 번호) · 문제 · 제안

따라해 보기 — 초안을 하나 만든 뒤 이렇게 부탁합니다.

drafts/2026-09-24-memory-guide.html 을
fact-checker 와 style-reviewer 에이전트로 각각 검토하고,
두 보고서를 합쳐 "고칠 것 목록"을 만들어줘. 아직 파일은 고치지 마.

4 2주차 Day 1~2 — 훅으로 HTML 자동 검사

"태그 닫았어?"를 매번 부탁하지 말고 규칙으로 걸어 둡니다. Claude가 HTML 파일을 저장(Write/Edit)할 때마다 검사 스크립트가 돌고, 문제가 있으면 Claude에게 되돌려 보내 스스로 고치게 합니다.

.claude/hooks/check_html.py

#!/usr/bin/env python3
import sys, json
from html.parser import HTMLParser

data = json.load(sys.stdin)                       # 훅 입력은 stdin 의 JSON
path = data.get("tool_input", {}).get("file_path", "")
if not path.endswith(".html"):
    sys.exit(0)                                   # HTML 이 아니면 통과

VOID = {"br", "img", "hr", "meta", "link", "input"}

class Checker(HTMLParser):
    def __init__(self):
        super().__init__()
        self.stack, self.errors = [], []
    def handle_starttag(self, tag, attrs):
        a = dict(attrs)
        line = self.getpos()[0]
        if tag == "p" and a.get("data-ke-size") != "size16":
            self.errors.append(f"{line}행: <p> 에 data-ke-size=\"size16\" 없음")
        if tag == "h2" and a.get("data-ke-size") != "size26":
            self.errors.append(f"{line}행: <h2> 에 data-ke-size=\"size26\" 없음")
        if tag not in VOID:
            self.stack.append((tag, line))
    def handle_endtag(self, tag):
        if tag in VOID:
            return
        if self.stack and self.stack[-1][0] == tag:
            self.stack.pop()
        else:
            self.errors.append(f"{self.getpos()[0]}행: </{tag}> 짝이 맞지 않음")

c = Checker()
with open(path, encoding="utf-8") as f:
    c.feed(f.read())
for tag, line in c.stack:
    c.errors.append(f"{line}행: <{tag}> 가 닫히지 않음")

if c.errors:
    print("HTML 검사 실패:\n" + "\n".join(c.errors[:20]), file=sys.stderr)
    sys.exit(2)                                   # 2 = Claude 에게 이유 전달
sys.exit(0)

.claude/settings.json — 파일 저장 직후 검사 실행

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check_html.py" }
        ]
      }
    ]
  }
}

5 2주차 Day 3 — 주간 초안 예약 작업 ★

이제 매주 "이번 주 Claude 업데이트 정리" 초안이 알아서 drafts 폴더에 쌓이게 합니다. Cowork(데스크톱 앱)에서 /schedule 을 입력하고 아래 프롬프트를 붙여 넣으세요.

매주 금요일 오후 3시에 실행해줘.

[목표]
이번 주(지난 7일) Claude 관련 업데이트를 정리한
모듈비트 티스토리용 초안 HTML을 만든다.

[자료 수집]
- 웹 검색으로 Anthropic 공식 발표, Claude 공식 문서 변경, 릴리스 노트를 찾는다.
- 공식 출처가 아닌 기사·커뮤니티 글은 "참고"로만 쓰고 단정하지 않는다.
- 주제는 최대 5개. 일반 사용자에게 영향이 큰 것부터.

[작성]
- tistory-guide-writer 스킬의 규칙과 sample.html 스타일을 그대로 따른다.
- 제목: "이번 주 Claude 업데이트 정리 (YYYY년 M월 D일)"
- 항목마다: 무엇이 바뀌었나 / 누구에게 해당되나(요금제) / 따라해 보기 한 줄 / 출처 링크

[검수]
- 저장 전에 fact-checker 기준으로 스스로 점검하고,
  확인 못 한 내용은 본문에서 빼거나 "확인 필요"로 표시한다.
- 초안 맨 끝 HTML 주석에 확인한 출처 목록과 남은 의문점을 적는다.

[저장]
- 연결된 modulebit-blog 폴더의 drafts/ 에
  YYYY-MM-DD-claude-weekly.html 로 저장한다.

[하지 말 것]
- 티스토리 발행, 로그인, 메일 발송은 하지 않는다.
- published/ 폴더는 건드리지 않는다.
- 새 소식이 없으면 "이번 주 주요 업데이트 없음" 메모 파일만 남긴다.

6 2주차 Day 4~5 — 플러그인 포장과 회고

Day 4 · 플러그인으로 포장하기

스킬·에이전트·훅이 폴더 여기저기 흩어져 있으면 다른 컴퓨터로 옮기거나 동료에게 주기 어렵습니다. 플러그인으로 묶으면 설치 한 번으로 끝납니다. 7단계에서 만든 modulebit-blog 플러그인에 에이전트·훅을 더해도 되지만, 여기서는 프로젝트 폴더 이름(modulebit-blog)과 헷갈리지 않도록 tistory-blog 라는 새 이름으로 묶습니다.

tistory-blog/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── tistory-guide-writer/
│       ├── SKILL.md
│       └── references/
│           └── sample.html
├── agents/
│   ├── fact-checker.md
│   └── style-reviewer.md
└── hooks/
    └── hooks.json

.claude-plugin/plugin.json

{
  "name": "tistory-blog",
  "description": "모듈비트 티스토리 Claude 가이드 글 작성·검수 도구 세트",
  "version": "1.0.0",
  "author": { "name": "모듈비트" }
}

# 로컬에서 시험 → 검증
claude --plugin-dir ./tistory-blog
claude plugin validate ./tistory-blog

# 세션 안에서 수정 사항 반영
/reload-plugins

# 이름공간이 붙어 호출됨
/tistory-blog:tistory-guide-writer 프로젝트 기능 가이드

Day 5 · 회고 — 사람 검토 체크리스트

drafts에 초안이 쌓였다면, 발행 전 이 목록으로 직접 확인합니다. 이 과정은 자동화하지 않는 것이 핵심입니다.

7 확장 아이디어 — 어디까지 자동화할까

8 정리 & 체크리스트

심화 과정 1~10단계가 한 폴더 안에서 전부 돌아가면 종합 프로젝트 완성입니다.

지금까지는 내가 말을 걸어야 Claude가 움직였습니다. 비유하자면 "부르면 오는 비서"였죠. 이번 단계에서는 비서에게 알람 시계와 업무 일지를 쥐여 줍니다. "매일 아침 8시에 이것 정리해 둬", "PR이 올라오면 한번 봐 줘" 같은 일을 내가 자리에 없어도 해 두도록 만드는 겁니다.

1 자동화 4가지 도구 한눈에

이름이 비슷해서 헷갈리지만, "어디서 돌아가는지"와 "무엇이 방아쇠인지"만 보면 금방 구분됩니다.

비교표 — 어떤 걸 고를까?

2 ★ 실습 ① Cowork 예약 작업 — 평일 아침 브리핑 ⏱ 20분

가장 먼저 해볼 자동화입니다. 4단계에서 연결한 캘린더·지메일 커넥터를 그대로 활용합니다.

따라해 보기

평일 아침 8시에 오늘 브리핑을 만들어줘.
- 구글 캘린더: 오늘 일정을 시간순으로, 회의는 참석자와 준비물까지
- 지메일: 어제 저녁 이후 받은 메일 중 답장이 필요한 것만 5개 이내
- 마지막에 "오늘 가장 먼저 할 일" 한 줄 추천
메일은 읽기만 하고 절대 보내거나 삭제하지 마.

빈도 옵션

3 실습 ② claude -p 기본 — Claude를 명령어 부품으로 ⏱ 30분

-p(print)는 대화창을 열지 않고 질문 하나 → 답 하나를 출력하고 끝나는 모드입니다. Java의 main 메서드를 cron에 걸듯, Claude를 스크립트 한 줄로 부를 수 있습니다.

따라해 보기 — 파이프로 로그 요약

# 1) 에러 로그를 파이프로 넘겨 요약
cat error.log | claude -p "오늘 에러를 유형별로 묶고, 건수가 많은 순서로 요약해줘" > summary.md

# 2) 빌드 에러 원인 찾기 (읽기 도구만 허용)
cat build-error.txt | claude -p "이 빌드 에러의 원인과 고칠 파일을 알려줘" \
  --allowedTools "Read,Grep,Glob"

# 3) JSON으로 받아 결과만 꺼내기 (jq 필요)
claude -p "변경된 파일 목록을 보고 커밋 메시지 초안을 써줘" \
  --allowedTools "Bash(git diff *),Read" \
  --output-format json | jq -r '.result'

OS 스케줄러와 조합하기 — claude -p 는 결국 명령어 한 줄이라, 리눅스·맥의 cron이나 윈도우 작업 스케줄러에 그대로 걸 수 있습니다. 아래는 일반적인 cron 예시입니다.

# crontab -e  (평일 오전 8시 반, 어제 로그 요약을 파일로 저장)
30 8 * * 1-5 cd ~/work/app && cat logs/app.log | claude -p "어제 에러만 유형별로 요약해줘" > reports/daily-summary.md

4 실습 ③ GitHub Actions — 이슈에 @claude 부르기 ⏱ 30분

저장소에 Claude를 "팀원"으로 등록하는 방법입니다. 이슈나 PR 댓글에 @claude 를 달면 GitHub 서버에서 Claude가 작업을 시작합니다.

name: Claude
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

@claude 로그인 실패 시 에러 메시지가 영어로만 나옵니다.
messages_ko.properties 에 한국어 메시지를 추가하고, 테스트도 같이 고쳐주세요.

자주 쓰는 입력값(with:)

5 Routines 소개 — 클라우드에서 도는 Claude Code

Routines는 "Claude Code판 예약 작업"입니다. 아직 research preview라 기능이 바뀔 수 있지만, 개념은 알아둘 만합니다.

# Claude Code 세션 안에서
/schedule

# 대화로 설명하면 됩니다. 예:
매주 월요일 오전 9시에 이 저장소의 열린 이슈를 읽고
"이번 주 처리 우선순위 Top 5"를 이슈 하나로 정리해줘.
코드는 수정하지 마.

6 자동화 설계 원칙 5가지

자동화는 "한 번 잘못 짜면 매일 잘못 돈다"는 점이 무섭습니다. 아래 원칙만 지켜도 사고의 대부분을 막을 수 있습니다.

# 좋은 자동화 프롬프트의 뼈대
[무엇을]   지난 7일간 받은 고객 문의 메일을 읽고
[어떻게]   유형별 건수와 대표 사례 3개로 요약해
[어디에]   reports/주간문의-YYYY-MM-DD.md 로 저장해
[금지]     메일 발송·삭제·라벨 변경은 절대 하지 마
[실패 시]  읽을 메일이 없으면 "이번 주 문의 없음" 한 줄만 저장해

7 정리 & 체크리스트

아래를 모두 해봤다면 다음 단계, 배운 것을 전부 엮는 종합 프로젝트로 넘어갈 준비가 된 겁니다.

1 왜 팀이 필요할까? — 컨텍스트가 차는 문제

Claude의 대화에는 한 번에 기억할 수 있는 양(컨텍스트)이 정해져 있습니다. 파일 수십 개를 읽고, 로그를 뒤지고, 테스트를 돌리다 보면 금방 가득 찹니다.

팀장 한 명이 자료 조사, 코드 리뷰, 문서 작성까지 혼자 하면 책상이 서류로 뒤덮여 정작 중요한 판단을 못 합니다. 좋은 팀장은 팀원에게 일을 나눠 주고 "결론만 한 장으로 보고해"라고 합니다. 서브에이전트가 바로 그 팀원입니다.

2 이미 있는 팀원 — 기본 제공 서브에이전트

아무것도 만들지 않아도 Claude Code는 필요할 때 기본 팀원을 알아서 부릅니다.

3 나만의 팀원 만들기

방법은 두 가지입니다. 대화로 부탁하거나, 파일을 직접 쓰거나.

코드 리뷰어 서브에이전트를 만들어 줘.
- 이름: code-reviewer
- 파일 위치: .claude/agents/ (팀과 공유할 거야)
- 도구는 Read, Grep, Glob 만 (읽기 전용)
- 버그 → 보안 → 가독성 순서로 지적하고, 심각도를 상/중/하로 표시
- 우리 프로젝트는 Java/Spring + Oracle 이야

파일 위치와 우선순위

frontmatter(맨 위 설정) 항목

4 ★ 바로 쓰는 예제 3종

그대로 복사해서 .claude/agents/ 에 저장하면 됩니다. 내용은 내 프로젝트에 맞게 고치세요.

① 코드 리뷰어 — 읽기 전용

파일: .claude/agents/code-reviewer.md

---
name: code-reviewer
description: 코드를 수정한 뒤 품질·보안 관점에서 리뷰할 때 사용. 변경 사항 검토 요청 시 적극적으로 사용.
tools: Read, Grep, Glob
model: sonnet
color: red
---
너는 시니어 코드 리뷰어다. 파일은 절대 수정하지 않는다.

리뷰 순서:
1. 버그 — 널 처리, 예외 처리, 트랜잭션 경계, 경계값
2. 보안 — SQL 인젝션, 하드코딩된 비밀번호·키, 권한 검사 누락
3. 가독성 — 이름, 중복, 너무 긴 메서드

출력 형식:
- 항목마다 [상/중/하] 심각도, 파일:줄, 문제, 고치는 방법 제안
- 마지막에 "머지해도 되는지" 한 줄 결론

② 테스트 작성자

파일: .claude/agents/test-writer.md

---
name: test-writer
description: 새 기능이나 수정한 코드에 단위 테스트를 작성하고 실행할 때 사용.
tools: Read, Grep, Glob, Edit, Write, Bash
model: sonnet
color: green
---
너는 테스트 전문 개발자다.

작업 순서:
1. 대상 코드와 기존 테스트 스타일(프레임워크, 폴더 구조, 이름 규칙)을 먼저 확인한다
2. 정상 케이스, 경계값, 예외 케이스를 나눠 테스트를 작성한다
3. 테스트를 실행하고, 실패하면 원인을 분석한다
4. 운영 코드는 고치지 않는다. 버그로 보이면 보고만 한다

보고: 추가한 테스트 목록, 실행 결과(통과/실패 수), 발견한 의심 버그

③ 문서 작성자

파일: .claude/agents/doc-writer.md

---
name: doc-writer
description: README, API 설명, 변경 이력 등 문서를 작성하거나 코드와 문서가 맞는지 점검할 때 사용.
tools: Read, Grep, Glob, Edit, Write
model: sonnet
color: blue
---
너는 기술 문서 작성자다. 독자는 이 프로젝트를 처음 보는 신입 개발자다.

원칙:
- 코드를 직접 읽고 확인한 사실만 쓴다. 추측은 "확인 필요"로 표시한다
- 짧은 문장, 예시 코드 포함, 한국어 존댓말
- 코드 파일은 수정하지 않는다. 문서 파일(.md)만 작성·수정한다

보고: 수정한 문서 목록과 각 문서에서 바뀐 부분 요약

5 팀원 부르는 3가지 방법

@agent-code-reviewer 이번 브랜치에서 바뀐 Java 파일을 리뷰해 줘.
특히 MyBatis 매퍼의 SQL 인젝션 가능성을 중점적으로 봐 줘.

6 ★ 따라해 보기 — 여러 팀원에게 동시에 조사 맡기기

서브에이전트의 진짜 힘은 병렬입니다. 서로 관계없는 조사를 여러 명에게 동시에 맡기면 시간도 줄고, 메인 대화에는 요약만 남습니다.

서브에이전트 3개를 병렬로 써서 이 프로젝트를 조사해 줘.
각 에이전트는 파일을 수정하지 말고 읽기만 해.

1) controller 폴더: 어떤 API(URL)가 있는지 목록으로
2) service 폴더: 핵심 비즈니스 로직과 트랜잭션 처리 방식
3) resources 폴더: DB 연결 설정, SQL 매퍼 파일 구조

각자 결과를 10줄 이내로 요약해서 보고하고,
마지막에 네가 세 보고를 합쳐 "이 프로젝트 한 장 요약"을 만들어 줘.

# 블로그 글 버전
서브에이전트 2개를 병렬로 써 줘.
1) Claude Code 공식 문서에서 "서브에이전트" 관련 최신 변경 사항 조사
2) 내 초안(advanced-09.html)의 명령어·설정 항목 목록 뽑기
두 결과를 비교해서 초안에서 고쳐야 할 부분만 알려줘.

7 나눌 때와 나누지 않을 때

팀원이 많다고 일이 잘 되는 건 아닙니다. 회의만 늘어나는 팀도 있죠. 기준은 "독립적인가, 얽혀 있는가"입니다.

8 비용 — 팀원이 많을수록 토큰도 늘어납니다

팀원 한 명 한 명이 각자 파일을 읽고 생각합니다. 3명을 병렬로 쓰면 대략 3명분의 사용량이 나간다고 생각하세요.

가벼운 조사 전용 팀원 예 — .claude/agents/file-scout.md

---
name: file-scout
description: 특정 키워드·클래스가 어느 파일에 있는지 빠르게 찾을 때 사용
tools: Read, Grep, Glob
model: haiku
---
요청받은 대상을 찾아 "파일 경로:줄 번호 — 한 줄 설명" 형식으로만 보고한다.

9 정리 & 체크리스트

서브에이전트 = 자기 책상(컨텍스트)에서 따로 일하고 요약만 보고하는 팀원. 아래를 모두 해봤다면 9단계 완료입니다.

1 명령어 vs 훅 — "부탁"과 "규칙"

둘 다 "자동화"처럼 보이지만 성격이 완전히 다릅니다.

회사로 비유하면, 명령어는 "김 대리, 주간보고 양식대로 정리해 줘"라고 내가 부를 때만 움직이는 부탁입니다. 훅은 "퇴근 전에는 반드시 문단속" 같은 사내 규칙입니다. 누가 부르지 않아도, 그 순간이 오면 무조건 실행됩니다.

2 커스텀 명령어 만들기 — 이제는 스킬로

예전에는 .claude/commands/ 폴더에 md 파일을 두는 방식이었습니다. 지금은 명령어가 스킬로 통합되었습니다.

따라해 보기: /pr-summary 명령어 만들기

---
name: pr-summary
description: 현재 브랜치의 변경 사항으로 PR 설명 초안을 만든다
argument-hint: [관련 이슈 번호]
disable-model-invocation: true
---
## 현재 변경 사항
!`git diff HEAD`

## 할 일
위 변경 사항을 보고 PR 설명을 한국어로 작성해 줘.
- 제목 한 줄
- 변경 요약 (3~5줄 불릿)
- 테스트 방법
- 관련 이슈: $ARGUMENTS

여기 쓰인 문법 정리

3 훅의 기본 개념 — 어떤 "순간"에 걸 수 있나

훅은 이벤트(순간) + 조건(matcher) + 실행할 명령 세 가지로 이루어집니다. 자주 쓰는 이벤트는 아래와 같습니다(이 밖에도 더 있습니다).

// 훅 설정의 기본 뼈대
{
  "hooks": {
    "PreToolUse": [                       // ① 이벤트
      {
        "matcher": "Bash",                // ② 어떤 도구일 때? (Bash, Edit|Write, * ...)
        "hooks": [
          { "type": "command",            // ③ 실행할 것
            "command": "실행할 셸 명령",
            "timeout": 600 }
        ]
      }
    ]
  }
}

위 뼈대의 // 뒷부분은 이해를 돕기 위한 설명입니다. JSON 파일에는 주석을 넣을 수 없으니 실제 설정에는 빼고 쓰세요.

4 설정 파일은 어디에? — 위치와 우선순위

훅은 별도 파일이 아니라 settings.json 안의 "hooks" 항목에 적습니다. 어느 파일에 적느냐에 따라 적용 범위가 달라집니다.

5 실습 ① 파일을 고치면 자동 포맷 PostToolUse

Claude가 파일을 수정(Edit)하거나 새로 쓸(Write) 때마다 포매터가 자동으로 돌게 합니다. 프론트엔드 프로젝트라면 prettier를 예로 들 수 있습니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

전체 폴더를 포맷하는 npx prettier --write . 보다, 위처럼 stdin JSON에서 방금 고친 파일 경로만 꺼내(jq) 그 파일만 포맷하면 훨씬 빠릅니다. jq 가 없다면 먼저 설치하세요.

6 ★ 실습 ② 위험한 명령 차단 PreToolUse

Claude가 셸 명령을 실행하기 직전에 검사해서, 위험한 명령이면 막습니다. Oracle 같은 DB를 다루는 분이라면 특히 추천합니다.

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')
if echo "$COMMAND" | grep -q "drop table"; then
  echo "Blocked: dropping tables is not allowed" >&2
  exit 2
fi
exit 0

chmod +x .claude/hooks/block.sh

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block.sh"
          }
        ]
      }
    ]
  }
}

테스트용이야. 셸에서 echo "drop table users" 를 실행해 봐.
막히면 어떤 메시지를 받았는지 알려줘.

종료 코드(exit code)의 의미

7 실습 ③ 작업이 끝나면 알림 받기 Notification · Stop

긴 작업을 맡기고 다른 창에서 일하다 보면, Claude가 승인을 기다리는지 모를 때가 많습니다. 알림 훅을 걸어 둡니다. 개인 취향이니 user 설정(~/.claude/settings.json)에 넣는 것을 추천합니다.

예시 (Linux) — notify-send 사용

{
  "hooks": {
    "Notification": [
      { "matcher": "",
        "hooks": [ { "type": "command",
          "command": "notify-send 'Claude Code' 'Claude가 확인을 기다리고 있어요'" } ] }
    ],
    "Stop": [
      { "hooks": [ { "type": "command",
          "command": "notify-send 'Claude Code' '작업이 끝났어요'" } ] }
    ]
  }
}

# 예시 (macOS) — command 부분만 바꿔 넣기
osascript -e 'display notification "작업이 끝났어요" with title "Claude Code"'

8 확인하기와 주의사항

꼭 기억할 3가지

9 정리 & 체크리스트

명령어는 "부를 때", 훅은 "그 순간 무조건". 아래를 모두 해봤다면 8단계 완료입니다.