1. CLAUDE.md, 책상 위 안내판부터

폴더 이름은 글쓰기실습/로 하겠습니다. 폴더 루트에 CLAUDE.md라는 파일을 만듭니다. 이 파일은 새로 출근한 신입에게 회사 안내문을 한 장 쥐여주는 것과 같습니다. Claude Code는 매번 작업을 시작할 때 이 파일을 자동으로 먼저 읽습니다.

# IT 책 글쓰기 프로젝트

이 폴더는 우리 출판사의 IT 책 한 절을 쓰는 작업을 돕는 작은 하네스다.

## 톤과 독자

- 톤: 친근하고 차분한 설명체. 비유와 예시를 많이 쓴다.
- 독자: 비전공 개발자 입문자 또는 바이브 코더.
- 분량 기본값: 한 절 약 200줄 (코드 블록 포함).

## 자연어 라우팅

사용자가 "한 절 써줘", "이 주제로 본문 작성", "글감 받아서 초안 만들어줘"
같은 요청을 하면 `harness` 스킬을 먼저 사용한다.

## 주요 위치

- 작업 매뉴얼: `.claude/skills/harness/SKILL.md`
- 사수 카드: `.claude/agents/outliner.md`, `.claude/agents/writer.md`
- 산출물: `artifacts/outline.md`, `artifacts/draft.md`

## 사람 승인 지점

- 얇게: 목차 초안, 본문 초안 — AI가 만들고 저자가 검토
- 두껍게: 외부 출판·게시·공개 — AI는 진행하지 않는다. 저자·편집자가 결정.

이 안내문이 하는 일은 "이 프로젝트가 무엇인지, 어떤 요청이 오면 무엇을 먼저 봐야 하는지, 어디까지 자동이고 어디서부터 사람 손이 필요한지"를 한 번에 알려주는 것입니다. 새 세션을 시작해도 이 내용이 매번 자동으로 들어옵니다. 채팅창에 매번 다시 적지 않아도 된다는 뜻입니다.

2. SKILL.md, 일하는 방법 매뉴얼

다음으로 .claude/skills/harness/ 폴더를 만들고 그 안에 SKILL.md를 둡니다. 폴더 이름이 곧 스킬 이름이 됩니다. 우리는 harness라는 이름으로 두겠습니다. 이렇게 하면 나중에 /harness라고만 입력해도 이 스킬이 자동으로 실행됩니다.

이 파일 안에 들어가는 글은 "이런 요청이 오면 어떤 순서로 일해라"를 적은 매뉴얼입니다.

---
name: harness
description: IT 책 한 절의 목차와 본문 초안을 만드는 흐름을 묶는 스킬.
  "한 절 써줘", "이 주제로 본문 작성", "글감 받아서 초안 만들어줘"
  같은 요청에서 사용한다.
---

# Harness

## 역할
IT 책 한 절을 쓰는 일을 목차 작성 → 본문 작성 두 단계로 나눠 진행한다.
결과는 모두 `artifacts/`에 파일로 남는다.

## 작업 순서

1. 사용자에게 글감을 묻는다 (주제, 분량, 독자 수준, 포함할 예시·표 여부).
2. `outliner`에게 목차를 짜게 한다 → `artifacts/outline.md`로 저장.
3. 사용자에게 목차를 보여주고 수정 필요 여부를 확인한다.
4. `writer`에게 목차를 바탕으로 본문을 쓰게 한다 → `artifacts/draft.md`로 저장.
5. 두 파일이 모두 만들어지면 사용자에게 위치를 알려준다.

## 사람 승인 지점
- 목차에서 한 번, 본문 초안에서 한 번 — 사용자 검토 자리를 둔다.
- 외부 공개·출판은 AI가 진행하지 않는다.

## 품질 기준
- 한 절 분량이 기본값(약 200줄) ±20% 범위 안.
- 본문 안에 예시 코드 또는 비교표가 최소 1개.
- 첫 문단에 "이 절이 무엇을 다루는지" 한 줄 요약.
- 마지막 문단에 "다음에 무엇이 오는지" 한 줄 안내.

스킬의 description은 단순한 소개문이 아닙니다. 언제 이 스킬을 써야 하는지를 알려주는 자동 검색 키워드입니다. 사용자가 채팅창에 "본문 작성"이라고만 적어도, Claude Code는 이 description을 읽고 이 스킬이 맞는지 판단합니다. 그래서 description에는 "어떤 단어가 들어오면 나를 써라"가 분명히 적혀 있어야 합니다.

3. 두 명의 사수 카드

이번에는 .claude/agents/ 폴더에 두 명의 사수 카드를 둡니다. 각 카드는 한 명의 책임과 입출력을 적은 짧은 문서입니다.

3.1 outliner.md, 목차 잡는 사람

---
name: outliner
description: IT 책 한 절의 목차(아웃라인)를 짜는 사수
---

# Outliner

## 책임
- 사용자가 준 글감(주제, 분량, 독자 수준)을 받아 절의 목차를 짠다
- 한 절은 보통 3~5개의 큰 묶음(섹션)으로 나눈다
- 각 섹션 아래 어떤 예시·코드·표가 들어갈지 한두 줄로 적는다

## 출력
- `artifacts/outline.md`
  - 섹션: 글감 요약 / 절 구성 / 각 섹션별 핵심 메시지·예시 메모

## 하지 말아야 할 일
- 본문 자체를 쓰는 일 (그건 writer의 책임)
- 글감 정보가 부족한데 임의로 채우는 일 (모자라면 사용자에게 묻는다)

3.2 writer.md, 본문 쓰는 사람

---
name: writer
description: outliner가 만든 목차를 받아 한 절의 본문 초안을 쓰는 사수
---

# Writer

## 책임
- `artifacts/outline.md`를 읽고 그 구조에 맞춰 본문을 쓴다
- `CLAUDE.md`의 톤·독자 규칙을 따른다
- 첫 문단에 한 줄 요약, 마지막 문단에 다음 절 예고를 둔다
- 필요한 자리에 예시 코드와 표를 채워 넣는다

## 출력
- `artifacts/draft.md`

## 하지 말아야 할 일
- outline에 없는 새 섹션을 임의로 추가
- 톤 규칙(친근하고 차분한 설명체)에서 벗어나는 표현
- 검증되지 않은 사실을 단정적으로 표현 (모르면 "확인 필요"로 둔다)

두 사수의 책임이 분리되어 있다는 점이 핵심입니다. 목차를 짠 사람과 본문을 쓴 사람이 같으면 자기 목차의 빈틈을 잘 못 보는 건 사람이나 AI나 같습니다. 두 명으로 나누면 목차 단계에서 한 번, 본문 단계에서 한 번, 우리(저자)가 검토할 자리가 자연스럽게 두 군데 생깁니다.

4. artifacts/, 결과를 모아두는 서랍

마지막으로 artifacts/ 폴더를 만듭니다. 이 폴더는 실행이 끝난 뒤 산출물이 쌓이는 곳입니다. 처음에는 비어 있지만, 한 번 돌리고 나면 outline.md와 draft.md가 자동으로 생깁니다.

폴더를 미리 만들어두는 이유는 "결과가 어디에 남을지"를 미리 정해두는 일 자체가 하네스의 중요한 약속이기 때문입니다. 채팅창에서 결과를 받으면 다음번에 찾기 어렵지만, 폴더 위치를 정해두면 다음번에도 같은 자리에서 찾습니다. 두 번째 절을 쓸 때는 이전 산출물을 한 폴더 더 만들어 artifacts/01-var-let-const/ 식으로 보관할 수도 있습니다.

5. 다 만든 폴더 모습

여기까지 만들고 나면 폴더는 다음과 같은 모습이 됩니다.

글쓰기실습/
├── CLAUDE.md
├── .claude/
│   ├── skills/
│   │   └── harness/
│   │       └── SKILL.md
│   └── agents/
│       ├── outliner.md
│       └── writer.md
└── artifacts/             (아직 비어 있음)

파일 다섯 개. 글로는 길어 보였지만, 막상 만들어 놓으면 단순한 폴더 하나입니다. 이어서 이 폴더를 실제로 한 번 돌려보고, 산출물을 받아본 뒤, 어디를 작게 고치면 좋을지 살펴보겠습니다.