■ 구현 가이드

implementation guidance — 인터페이스 · 프롬프트/스킬 위치 · 도구 계약 · 런북6.4 본편

표시가 없는 문장은 공식 문서에서 확인한 내용이에요. 다른 표시는 읽는 법

왜 배우나 — 시험이 요구하는 것

시험 목표 6.4 구조 문서화 · D6 사람·문서 14%
Document architectures and provide implementation guidance

이 개념으로 푸는 판단 (할 수 있어야 하는 것)

6.4② 아키텍트 없이 팀이 짓고 고칠 수 있어야 한다 — 구현 가이드에 무엇을 넣나? (빈 목표) — 구현 가이드 구성 (인터페이스 · 프롬프트/스킬 위치 · 도구 계약 · 런북)

한눈에

구현 가이드는 아키텍트 없이 팀이 짓고 고치게 하는 문서다. 합격 기준은 "아키텍트 없이 빌드·복구할 수 있는가" 다 업계 일반

공식 문서에서 가장 가까운 원칙은 자기완결형 명세(self-contained spec)다. 이 명세는 세 가지를 한다 (Claude Code 코딩 명세 기준이다. 구현 가이드로 옮긴 것은 추론이다)

관련 파일·인터페이스를 짚는다
범위 밖을 적는다
되는지 증명하는 end-to-end(처음부터 끝까지) 검증으로 끝낸다

비유 OpenAPI 스펙(인터페이스·계약), 설정이 어느 레포 어느 경로에 있는지, 온콜 런북을 묶은 것과 같다. 기준은 "새벽 온콜이 설계자 없이 복구하나?" 다. "코드가 문서다" 가 속이는 습관이다

구현 가이드는 인터페이스·프롬프트와 스킬 위치·도구 계약·런북으로 이루어지고, 합격 기준은 아키텍트 없이 팀이 빌드하고 복구할 수 있는가이다. — 그림으로 보기 (AI 생성 · Codex · 누르면 크게)

ELI5

새로 온 요리사가 주방장 없이도 같은 요리를 내게 하는 조리 카드예요.

재료가 어디 있는지(위치), 무엇을 넣고 무엇이 나오는지(입출력)를 적어요.
칼·오븐 쓰는 법은 "언제 쓰고 언제 안 쓰는지"까지 적어요.
불이 나면 무엇부터 볼지 적은 비상 카드도 붙여요.
"절대 가스 틀어 두지 말 것"은 카드 대신 자동 차단기를 달아요.

개념 설명

영상 — 두는 곳이 부르는 세션을 정한다 (약 43초 · 소리 없음 · 자막). 밤 자동 실행 4번과 칸 결과(✗✗✗✓)는 그림용 가정 · 실측 아님 — 개인 폴더는 그 기계만 · 새 클라우드 세션은 개인 폴더를 안 읽음 · 레포 커밋이면 팀이 받음은 카드·설명 값(Claude Code skills 문서). 이름 겹침 우선순위 · 계정 쪽 켜기 · 플러그인 배포는 다루지 않음 작은 화면에서는 전체화면(⛶)으로 보세요.

원리

합격 기준

합격 기준은 "아키텍트 없이 빌드·복구할 수 있는가" 다 (업계 일반).
공식 문서에서 가장 가까운 기준은 자기완결형 명세다. 이 명세는 관련 파일·인터페이스를 짚고, 범위 밖을 적고, 되는지 증명하는 end-to-end(처음부터 끝까지) 검증으로 끝낸다. Claude Code 코딩 명세 기준이라 구현 가이드로 옮긴 것은 추론이다.

네 칸

인터페이스 : 컴포넌트마다 입력·출력을 적는다.
프롬프트·스킬 위치 : 두는 곳이 어느 세션이 불러오는지를 정한다.
- 개인 ~/.claude/skills/ 는 이 기계의 내 프로젝트만 불러온다.
- 프로젝트 .claude/skills/ 는 커밋하면 팀이 받는다.
- 조직 전체는 관리 설정·플러그인으로 배포한다.
- 이름이 겹치면 기업 > 개인 > 프로젝트 순으로 이긴다.
도구 계약 : 세 가지를 적는다.
- 받는 것 : input_schema 를 적고, 복잡하면 input_examples 를 더한다.
- 돌려주는 것 : 설명에 "못 돌려주는 것"까지 적는다.
- 보장하는 것 : strict: true 면 입력이 스키마와 맞는다.
설명이 도구 성능의 가장 큰 요인이다. 도구당 최소 3~4문장을 쓴다.
런북 : 자주 나는 장애마다 알아보는 법 · 확인할 것 · 복구 방법을 적는다. 공식 문서에 런북이 없다. 그래서 업계 일반이다.

문서만으론 안 전해지는 것 둘

기대 동작 : 같은 명세도 두 엔지니어가 엣지 케이스를 다르게 읽는다. 평가셋이 이 모호함을 없앤다. 평가가 있으면 기준선·regression(회귀) 테스트가 딸려 온다.
꼭 지킬 규칙 : CLAUDE.md 지시는 권고다. hook 은 결정적(deterministic)이다. "절대 X" 를 문서에 크게 적는 것으로는 못 막는다. 그래서 강제 장치를 쓴다.

문서 쪽 규칙 쓰는 법 (Claude 가 읽는 문서 기준)

짧게 쓴다. 길면 규칙이 묻힌다. 강조는 몇 줄에만 쓴다.
구체적이고 검사 가능하게 쓴다. 금지만 말고 대신 할 것을 적는다 (Skilljar).
코드로 못 읽는 것 위주로 쓴다. 흔한 함정 · 환경 특이점(필요한 환경 변수) · 구조 결정이 그것이다.

규칙과 판단

팀이 함께 쓸 스킬은 개인 폴더가 아니라 레포의 .claude/skills/ 에 커밋하고, 어기면 큰일인 규칙은 문서가 아니라 hook 으로 강제한다. — 그림으로 보기 (AI 생성 · Codex · 누르면 크게)

갈림길

①③⑤ 무엇을 적나 [6.4②]

팀이 무엇을 하려나?

구현 (컴포넌트 잇기)

인터페이스를 적는다

관련 파일·인터페이스, 범위 밖, end-to-end 검증을 적는다 (코딩 명세 기준이다. 옮긴 것은 추론이다)

도구 붙이기·고치기

도구 계약을 적는다

받는 것 · 돌려주는 것 · 보장하는 것을 적는다. 설명이 도구 성능의 가장 큰 요인이다

장애 복구

런북을 적는다

알아보는 법 · 확인할 것 · 복구 방법을 적는다 업계 일반

② 어디에 두나 [6.4②]

누가 써야 하나?

나만 (내 모든 프로젝트)

개인 ~/.claude/skills/

이 컴퓨터에서만 불린다. 클라우드 세션·routine 에서는 "not found" 가 난다

이 레포에서 일하는 팀

프로젝트 .claude/skills/

커밋하면 팀이 받는다

조직 전체

기업 · 플러그인

관리 설정 디렉터리 또는 플러그인으로 배포한다

④⑥ 규칙을 어떻게 [6.4②]

어기면 큰일인가?main push · 삭제

예

강제 장치를 쓴다

CLAUDE.md 지시는 권고다. hook 은 결정적(deterministic)이고 반드시 실행된다

아니오 (관례)

한 줄로 검사되나?

예

짧게 문서에 적는다

구체적이고 검사 가능하게 쓴다. 금지만 말고 대신 할 것을 적는다 (Skilljar)

아니오 (엣지 케이스 해석이 갈린다)

평가셋을 넘긴다

평가셋(eval suite)이 모호함을 없앤다

규칙 원문 ①②③④⑤⑥ (갈림길로 그린 규칙)

인터페이스 : 컴포넌트마다 입력·출력을 적는다. 자기완결형 명세는 관련 파일·인터페이스, 범위 밖, end-to-end 검증을 담는다 (옮긴 것은 추론이다) [6.4②]

명세를 정확히 쓰는 시간이 구현을 지켜보는 시간보다 더 쓸 만하다

프롬프트·스킬 위치 : 두는 곳이 어느 세션이 불러오는지를 정한다 [6.4②]

위치	경로	불러오는 곳
기업	관리 설정 디렉터리의 `.claude/skills/`	조직이 배포한 기계의 모든 사용자
개인	`~/.claude/skills/`	이 기계의 내 모든 프로젝트다. Cowork·클라우드 세션은 아니다
프로젝트	`.claude/skills/`	이 레포 세션이다. 커밋하면 팀이 받는다

조직 전체에는 관리 설정 디렉터리 또는 플러그인으로 배포한다

이름이 겹치면 기업 > 개인 > 프로젝트 순으로 이긴다

개인 폴더에만 둔 스킬은 routine 이 부르면 "not found" 가 난다

그래서 팀에 넘길 것은 레포에 둔다

CLAUDE.md 도 같다. 프로젝트 파일은 소스 관리로 팀이 공유한다. 구조 결정과 빌드·테스트 명령을 담는다

스킬 동작·API 쪽 공유 범위(claude.ai 와 API 는 따로 올린다)는 ■ Agent Skills progressive disclosure 에 있다. API 앱 프롬프트도 옛 대화 속이 아니라 버전 관리되는 곳에 둔다 업계 일반

③
도구 계약 : 받는 것 · 돌려주는 것 · 보장하는 것을 적는다 [6.4②]

받는 것 : input_schema(JSON Schema)를 적는다. 입력이 복잡하면 input_examples 를 더한다

설명이 도구 성능의 가장 큰 요인이다. 설명에는 아래를 적는다. 도구당 최소 3~4문장을 쓴다
- 무엇을 하나
- 언제 쓰고 언제 안 쓰나
- 파라미터 뜻
- 못 돌려주는 것
새 팀원에게 설명하듯 쓴다. 쿼리 형식·용어 뜻·자원 관계 같은 암묵 지식을 드러낸다

보장하는 것 : strict: true 를 걸면 도구 입력이 스키마와 맞는다고 보장된다. 없으면 "2"(문자) 대 2(숫자) 같은 어긋남이나 필수 필드 누락이 생길 수 있다

strict 도구는 요청당 20개까지다

도구 모양·응답 설계 세부는 ■ 도구 설계 에 있다
기대 동작은 평가셋으로 : 같은 명세도 두 엔지니어가 엣지 케이스를 다르게 읽는다. 평가셋(eval suite)이 이 모호함을 없앤다 [6.4②]

평가가 있으면 기준선·regression(회귀) 테스트가 딸려 온다 (지연(latency)·토큰·과제당 비용·오류율)

그래서 end-to-end 검증은 평가셋을 돌리는 것으로 본다 (연결은 추론). 자세한 것은 ■ 검증 층 에 있다
런북 : 자주 나는 장애마다 알아보는 법 · 확인할 것 · 복구 방법을 적는다 업계 일반 공식 문서에 런북 없음 [6.4②]

무엇부터 볼지는 ■ observability 세 신호 에 있다
꼭 지킬 규칙은 강제 장치로 : CLAUDE.md 지시는 권고다. hook 은 결정적이고 반드시 실행된다 [6.4②]

"never push to main" 은 CLAUDE.md 가 아니라 pre-tool-use hook 으로 막는다 (Skilljar)

문서 쪽 규칙은 짧게 쓴다. 길면 규칙이 묻힌다

구체적이고 검사 가능하게 쓴다. 금지만 말고 대신 할 것을 적는다 (Skilljar)

강조는 몇 줄에만 쓴다. 여러 줄을 강조하면 아무것도 눈에 안 띈다

(Claude 가 읽는 문서 기준이다. 사람 팀 문서로 넓힌 것은 추론이다)

더 깊이 : 판단 규칙 · 상황 변수 (설명)

판단 규칙

조건	답	등급	근거
구현 가이드의 명세 모양을 정한다	관련 파일·인터페이스, 범위 밖, end-to-end 검증을 담는다	(코딩 명세 기준)	best-practices "The most useful specs are self-contained…"
도구를 넘길 때 무엇을 적나?	무엇을 하나 · 언제 쓰고 안 쓰나 · 파라미터 뜻 · 못 돌려주는 것을 3~4문장 이상 적는다		define-tools
입력 모양이 복잡하다	`input_examples` 를 추가한다		define-tools
입력이 스키마와 꼭 맞아야 한다	`strict: true` 를 건다 (요청당 20개까지)		strict-tool-use · structured-outputs
팀이 같이 쓸 스킬이다	프로젝트 `.claude/skills/` 에 커밋한다		Claude Code skills
조직 전체에 배포한다	관리 설정 디렉터리나 플러그인을 쓴다		Claude Code skills
기대 동작의 엣지 케이스가 있다	평가셋을 같이 넘긴다		demystifying-evals
어기면 큰일인 규칙이다	hook 같은 강제 장치를 쓴다		best-practices · Skilljar 486929
장애에 대응한다	런북(알아보는 법·확인할 것·복구 방법)을 쓴다	업계 일반	목록 6.4②. 공식 문서에 runbook·playbook 은 0건이다

상황 변수

변수	값	답 쪽	등급	근거
스킬 쓰는 사람	나만 쓴다	개인 `~/.claude/skills/` 에 둔다		skills
스킬 쓰는 사람	이 레포의 팀이 쓴다	프로젝트 `.claude/skills/` 에 두고 커밋한다		skills
실행 환경	routine · 클라우드 세션이다	개인 폴더 스킬은 "not found" 가 난다. 레포에 커밋한다		skills
같은 이름 스킬	개인·프로젝트 둘 다 있다	개인 것이 이긴다 (기업 > 개인 > 프로젝트)		skills
도구 입력	중첩 객체이고 형식에 민감하다	`input_examples` 를 더한다		define-tools
strict 걸 도구 수	20개를 넘는다	스키마가 깨지면 곤란한 도구만 strict 를 건다		structured-outputs
규칙 무게	관례다(코드 스타일)	문서에 짧고 검사 가능하게 적는다	(Skilljar)	Skilljar 486929
규칙 무게	어기면 사고가 난다(main push)	hook 을 쓴다		best-practices
도구 수	30~50개를 넘는다	설명 보강만으로는 부족하다. tool search 쪽으로 간다		■ 도구 설계 · 규칙 ⑤ tool-search-tool

연습 문제

아키텍트가 고객지원 Agent 의 티켓 요약 스킬을 자기 ~/.claude/skills/ 에만개인 폴더 둔 채 인계했다. 새 팀이 이 레포에서 함께 쓰며 매일 밤 routine 으로 돌리려 하자팀 · routine "not found" 가 난다. 스킬을 어디에 둬야 할까?

시험 대비

함정

"코드와 프롬프트가 곧 문서" 는 함정이다. 코드에서 못 읽는 것(흔한 함정 · 환경 특이점 · 구조 결정)이 빠진다. CLAUDE.md 에 넣을 것이 바로 그것들이다
"도구 설명은 짧게, 세부는 구현자가 코드에서 읽는다" 는 함정이다. 설명이 도구 성능의 가장 큰 요인이다
"스킬·프롬프트를 내 ~/.claude/skills/ 에 두고 인계" 는 함정이다. 팀·클라우드 세션에는 안 보인다. 레포 .claude/skills/ 에 커밋한다
"스키마만 적어 두면 도구 입력이 늘 맞음" 은 함정이다. 보장은 strict: true 일 때만 있다
"가이드에 '절대 X 하지 말 것' 을 크게 적으면 끝" 은 함정이다. 문서는 권고일 뿐이다. 막아야 하면 hook 같은 강제 장치를 쓴다. 강조를 남발하면 아무것도 눈에 안 띈다
"명세 문서만 넘기면 기대 동작이 전해짐" 은 함정이다. 엣지 케이스는 사람마다 다르게 읽는다. 평가셋을 같이 넘긴다
"런북 = 아키텍트 연락처" 는 함정이다. 기준은 아키텍트 없이 복구하는 것이다 업계 일반

신호

"Provide extremely detailed descriptions. This is by far the most important factor in tool performance."

"Aim for at least 3–4 sentences for each tool description, more if the tool is complex."

"When writing tool descriptions and specs, think of how you would describe your tool to a new hire on your team."

"Setting strict: true on a tool definition guarantees Claude's tool inputs match your JSON Schema"

"Where you save a skill decides which sessions load it."

"Save it under your home directory to get it in every project, commit it to a repository to share it with everyone who works there, or distribute it through a plugin or managed settings to reach a whole team."

"The most useful specs are self-contained: they name the files and interfaces involved, state what is out of scope, and end with an end-to-end verification step that proves the feature works."

"Two engineers reading the same initial spec could come away with different interpretations on how the AI should handle edge cases. An eval suite resolves this ambiguity."

"Unlike CLAUDE.md instructions which are advisory, hooks are deterministic and guarantee the action happens."

보통은 도구 설명을 자세히 쓰고 스킬은 레포에 두지만, 혼자 쓰는 스킬은 개인 폴더, 도구가 너무 많으면 합치기·tool search, strict 는 민감한 도구부터 건다. — 그림으로 보기 (AI 생성 · Codex · 누르면 크게) — 자세한 조건은 아래 '더 깊이'에 있어요

더 깊이 : 뒤집히는 때 · 오답 재료 (설명)

뒤집히는 때

1. 개인 폴더가 맞는 때 — 그리고 안 맞게 되는 때

조건 : 혼자 쓰는 요약 스킬이면 개인 ~/.claude/skills/ 가 맞다(내 모든 프로젝트).
뒤집힘 : 같은 스킬을 매일 밤 routine 으로 돌리기로 했다. routine 은 새 클라우드 세션이라 개인 폴더를 안 읽는다. 그래서 "not found" 가 난다. 레포 .claude/skills/ 에 커밋하거나 claude.ai 계정 쪽에 켠다.
근거 : skills

2. 도구 설명을 늘려도 안 풀리는 때

조건 : 도구가 60개다. 비슷한 도구를 번갈아 잘못 부른다. 가이드에는 도구마다 3~4문장 설명이 이미 있다.
판단 : 설명이 가장 큰 요인인 것은 맞다. 그러나 30~50개를 넘으면 고르기 정확도 자체가 떨어진다. 먼저 도구를 합치고 네임스페이스를 둔다. 그래도 많으면 tool search 를 쓴다. 가이드의 "도구 계약"은 개수 판단까지 대신하지 못한다.
근거 : define-tools ■ 도구 설계 · 규칙 ⑤(tool-search-tool)

3. strict 를 다 걸 수 없는 때

조건 : 도구 35개 전부 "입력 보장"을 가이드에 약속하고 싶다.
계산 : strict 도구는 요청당 20개까지다. 그래서 35개 전부는 한 요청에 못 건다. 스키마가 깨지면 곤란한 도구(결제·삭제처럼 뒤쪽 함수가 타입에 민감한 것)부터 strict 를 건다. 고르는 기준은 업계 일반이다.
등급 : 계산 (상한은 확인)
근거 : structured-outputs · strict-tool-use

4. 문서 한 줄로 충분한 때

조건 : "새 API 경로는 src/api/handlers 에 한 파일씩" 같은 관례다.
판단 : 어겨도 리뷰에서 잡히고 되돌리기 쉽다. 그래서 hook 까지 갈 필요가 없다. 구체적이고 검사 가능하게 적으면 된다. hook 은 "어기면 큰일"인 것에만 쓴다.
등급 : (Skilljar 기준)
근거 : Skilljar 486929

오답 재료

오답	왜 끌리나	왜 틀리나	등급	근거
"코드와 프롬프트가 곧 문서"	코드는 늘 최신이다	코드로 못 읽는 것(함정·환경 특이점·구조 결정)이 빠진다	(Claude 문서 기준)	best-practices
"도구 설명은 짧게, 세부는 구현자가 코드에서 읽는다"	설명이 중복 같다	설명이 도구 성능의 가장 큰 요인이다. 최소 3~4문장을 쓴다		define-tools
"스킬·프롬프트를 내 홈 폴더에 두고 경로만 알려 준다"	이미 잘 돌아간다	팀·클라우드 세션에는 안 보인다. 레포에 커밋한다		skills
"스키마만 정의하면 도구 입력이 늘 맞다"	JSON Schema 가 있으니 맞을 것 같다	보장은 `strict: true` 일 때만 있다. 없으면 `"2"` 대 `2` 같은 어긋남이나 필수 필드 누락이 생길 수 있다		strict-tool-use
"가이드에 '절대 main 에 push 금지' 를 굵게 적는다"	강조하면 지킬 것 같다	CLAUDE.md 는 권고다. 막으려면 hook 을 쓴다. 강조를 남발하면 아무것도 눈에 안 띈다		best-practices · Skilljar 486929
"명세 문서만 꼼꼼히 쓰면 기대 동작이 전해진다"	문서가 자세하면 될 것 같다	두 엔지니어가 엣지 케이스를 다르게 읽는다. 평가셋을 같이 넘긴다		demystifying-evals
"`@path` 로 쪼개면 읽는 양이 줄어 규칙을 더 잘 지킨다"	파일이 작아 보인다	import 는 시작 때 다 불러온다. 정리만 된다		memory · Skilljar 486929 (imports 절)
"런북 = 아키텍트 연락처 + 에스컬레이션 경로"	확실한 안전망(safety net) 같다	기준은 아키텍트 없이 복구하는 것이다	업계 일반	목록 6.4②

참고

더 깊이 : 출처 · 상태 · 미해결 (참고)

출처

상태

업계 일반 (합격 기준 문장 · 런북 · API 프롬프트 위치)
추론 2곳(코딩 명세 → 구현 가이드 · end-to-end 검증 = 평가셋)

미해결

런북은 공식 문서가 없다 (grep "runbook|playbook" 결과 ccarp/raw/official-docs 0건 · 제외 = 받지 않은 공식 페이지). 구성(알아보는 법·확인할 것·복구 방법)은 목록 6.4② 를 업계 일반으로 옮겼다.
코딩 명세 기준(self-contained spec)을 구현 가이드에 옮긴 것과 "end-to-end 검증 = 평가셋 돌리기" 는 추론 연결이다. 공식은 구현 가이드라는 문서를 따로 정의하지 않는다.
API 앱(Claude Code 밖)의 프롬프트 저장 위치는 공식 권고 문장을 못 찾았다. 그래서 카드에는 업계 일반으로만 적었다.
목록 6.4② 영어 신호 3개는 모두 원문에서 찾았다. 공식은 목록보다 세 가지를 더 말한다. 이 셋을 카드에 더했다.
- 개인 스킬은 Cowork·클라우드 세션에서 안 불린다.
- 이름 겹침 우선순위
- 플러그인 배포 경로
스킬 위치 표의 Nested·Additional directory(--add-dir) 칸은 판단을 가르지 않아 카드에서 뺐다 (skills).