3회차 · 9교시
더 오래 맡기기:
사람이 누르던 승인과 ‘계속’을 기계가 대신하게 되면서, 몇 시간짜리 일을 맡길 수 있게 된 과정을 봅니다.
2026-03 자동 승인 2025-07 Ralph 루프 2026-05 /goal 2026-03 1M 컨텍스트
오늘은 에이전트에게 얼마나 오래 맡길 수 있는가를 다룹니다. 지난 시간까지는 에이전트가 딴길로 새지 않게 하는 장치를 봤습니다. 오늘은 반대로, 사람이 계속 붙어 있어야 하는 이유를 하나씩 없애 나간 과정입니다. 승인을 누르는 일, 계속이라고 입력하는 일, 창이 차서 압축하는 일, 이 세 가지를 차례로 봅니다. 아래 네 장은 모두 실제 공식 화면입니다.
8교시 → 9교시
스펙과 테스트를 갖춰도, 사람이 남는 세 곳
8교시 하네스 v1 스펙 · Task 목록 테스트 = 완료 기준 진행 파일 그래도 사람이 남는 곳 도구 호출마다 승인 턴이 끝날 때마다 ‘계속’ 창이 차면 압축 9교시의 답 자동 승인 (auto mode) /goal · 루프 1M 컨텍스트 딴길 막음
지난 시간까지의 하네스가 무엇을 할지 를 붙잡았다면, 오늘은 누가 승인하고, 누가 계속하고, 어디에 담는지 를 바꿉니다.
8교시 실습에서 여러분은 스펙과 테스트를 완료 기준으로 세워 봤습니다. 에이전트는 이제 딴길로 덜 샙니다. 그런데 자리를 비우면 어떻게 될까요. 도구를 부를 때마다 승인 창이 뜨고, 턴이 끝나면 에이전트가 멈춰서 사람이 계속을 입력해야 하고, 일이 길어지면 창이 차서 압축이 일어납니다. 오늘 세 블록이 이 세 곳에 하나씩 대응합니다. 자동 승인, 계속의 자동화, 그리고 1M 컨텍스트입니다.
2026-03-25
수동 승인은 93%가 그냥 승인돼, 안전장치 구실을 못 한다
수동 승인 샌드박스 --dangerously-skip-permissions auto mode 안전 승인 93% 그냥 누름 안전 기능마다 설정, 네트워크 필요하면 깨짐 보호 없음 관리 비용 0 분류기가 판단 프롬프트 줄고 위험 행동은 차단
수동 승인 요청 중 사용자가 93% 를 그냥 승인합니다(Anthropic 집계). 확인하지 않고 누르는 승인은 안전장치가 아닙니다. → 3교시에서 본 내용
1회차에서 본 승인 피로의 해법을 다시 짚어 봅니다. Anthropic 엔지니어링 글은 사용자에게 두 가지 길이 있었다고 설명합니다. 도구를 격리하는 샌드박스와, 모든 승인을 끄는 건너뛰기 플래그입니다. 샌드박스는 안전하지만 기능마다 설정해야 하고, 네트워크나 호스트 접근이 필요하면 격리가 깨집니다. 건너뛰기 플래그는 관리가 필요 없지만 보호도 없습니다. 수동 승인은 가운데인데, 사용자가 그 93%를 그냥 승인한다고 합니다. 이 빈자리에 들어온 것이 auto mode입니다.
2026-03-24
자동 승인(auto mode): 사람의 승인을 분류기 모델이 대신한다
claude.com/blog/auto-mode
공식 발표 화면 캡처 · 2026-03-24
Claude 공식 발표 글 첫 화면(2026-03-24). 제목은 ‘Claude Code용 auto mode’, 부제는 --dangerously-skip-permissions(승인 전부 끄기)의 더 안전한 장시간 대안 .
행동 직전 별도 분류기 모델 이 범위 밖 행동·낯선 인프라·글에 홀린 행동을 막아, 승인 클릭 없이 긴 작업이 이어진다.
공식 문서가 밝히듯 안전을 보장하지는 않고 프롬프트를 줄여 줄 뿐이다. 켜는 법: Shift+Tab 또는 --permission-mode auto.
승인을 없앤 것이 아니라 승인하는 주체를 사람에서 모델로 바꾼 기능. 9교시 첫 블록의 출발점.
→ 다음 장: 분류기 구조
auto mode는 승인을 없애는 것이 아니라 승인하는 주체를 바꾼 기능입니다. 사람이 누르던 허락을 별도의 분류기 모델이 도구 호출마다 검토합니다. 공식 문서는 요청을 넘어서는 행동, 처음 보는 인프라를 건드리는 행동, 에이전트가 읽은 글에 이끌려 나온 행동을 막는다고 설명합니다. 문서에는 auto mode가 프롬프트를 줄여 줄 뿐 안전을 보장하지는 않는다는 경고도 있습니다. 지금은 최신 Claude Code의 인터랙티브 세션이 별도 설정이 없으면 auto mode로 시작합니다. 다만 설정 파일의 defaultMode가 있으면 그것이 우선합니다. 묶어 보면 장점은 분류기가 대신 막아 줘서 긴 작업이 끊기지 않는다는 것이고, 단점은 안전을 보장하지 않고 프롬프트를 줄여 줄 뿐이라는 것입니다. 의미는 승인의 주체가 사람에서 모델로 옮겨 갔다는 점입니다.
2026-03-25
분류기는 두 겹: 들어오는 글과 나가는 행동
anthropic.com/engineering/claude-code-auto-mode
Anthropic Engineering 화면 캡처 · 2026-10-28 확인
엔지니어링 글의 Figure 2 ‘System architecture’. 도구 호출은 Transcript classifier 가 허용·거부하고, 도구 결과는 Prompt-injection probe 가 훑는다.
입력층 (숨은 프롬프트 주입 탐지)과 출력층 (실행 직전 행동 분류) 두 겹으로 막는다.
서브에이전트가 돌려주는 결과는 경고만 하고 차단하지 못한다 . 놓치는 위험도 있다(다음 장 17%).
분류기는 사용자 메시지와 도구 호출만 보고 에이전트 설명·도구 결과는 뺀다 . 설득당하지 않으려는 설계.
구조는 두 겹입니다. 입력 쪽에서는 파일, 웹, 셸 출력 같은 도구 결과가 에이전트에게 들어가기 전에 프롬프트 주입 탐지기가 훑고, 의심스러우면 경고를 붙입니다. 출력 쪽에서는 별도 분류기가 실행 직전 행동을 검사합니다. 발표 당시 분류기는 Sonnet 4.6이었고, 지금 공식 문서는 기본을 Sonnet 5라고 적습니다. 흥미로운 설계는 분류기가 에이전트의 설명과 도구 결과를 보지 못한다는 점입니다. 에이전트가 그럴듯하게 설명하거나 악성 파일이 분류기를 설득하는 일을 막으려는 것입니다. 묶어 보면 장점은 입력과 출력 두 겹으로 막는다는 것이고, 단점은 서브에이전트 반환 단계에서는 경고만 할 뿐 막지 못하고 일부 위험을 놓친다는 것입니다. 의미는 분류기가 에이전트의 설명에 설득당하지 않도록 일부러 못 보게 했다는 설계 원칙입니다.
공식 문서 + Engineering 글
호출은 세 단계로 걸러진다
1단 · 규칙 읽기 전용 2단 · 프로젝트 안 편집 3단 · 분류기 빠른 검사 → 추론 실행 3회 연속·20회 누적 → 사람에게 묻기 차단 → 사유를 Claude에게 아니면 아니면 통과 차단
읽기와 프로젝트 안 편집은 분류기 없이 통과합니다. 셸 명령, 웹 요청, 서브에이전트 같은 나머지가 분류기로 갑니다.
도식은 Engineering 글과 권한 모드 문서를 합친 것입니다. 먼저 허용·거부 규칙과 읽기 전용 도구는 바로 결정됩니다. 프로젝트 디렉터리 안의 파일 편집도 분류기를 건너뜁니다. 그 밖의 셸 명령, 웹 요청, 외부 도구, 서브에이전트가 분류기로 갑니다. 분류기는 두 단계입니다. 먼저 빠른 예/아니오 필터가 의심스러우면 막는 쪽으로 기울고, 의심된 것만 추론 단계가 다시 봅니다. 차단되면 사유가 Claude에게 돌아가서 다른 방법을 찾게 합니다. 연속 3번 또는 누적 20번 차단되면 사람에게 다시 묻습니다.
2026-03-25
분류기는 위험한 과잉 행동의 17%를 놓친다
anthropic.com/engineering/claude-code-auto-mode
Anthropic Engineering 화면 캡처 · 2026-10-28 확인
결과 표(Table 1). FPR(False Positive Rate, 오탐률)은 정상 행동을 잘못 막은 비율, FNR(False Negative Rate, 놓침률)은 위험 행동을 놓친 비율. 전체 파이프라인은 FPR 0.4%, FNR 17% .
0.4%
정상 행동을 잘못 막은 비율(오탐) · 실제 트래픽 1만 건 중
17%
위험한 과잉 행동을 통과시킨 비율(미탐) · 실제 사례 52건 중
→ 결론: ‘안전하다’가 아니라 ‘프롬프트 열 번을 줄이는 대신 일부 위험을 받아들인다’입니다.
Anthropic은 이 글에서 정직한 숫자라는 표현과 함께 한계를 공개했습니다. 실제 트래픽 1만 건에서 정상 행동을 잘못 막은 비율은 전체 파이프라인 기준 0.4%입니다. 반면 실제로 있었던 과잉 행동 사례 52건 중 17%는 통과시켰습니다. 글에 따르면 놓친 경우의 상당수는 위험을 못 알아본 것이 아니라 사용자의 승인이 그 행동의 파급 범위까지 덮는지를 잘못 판단한 것입니다. 표본이 52건으로 작다는 점도 함께 봐 주세요. 그래서 auto mode는 격리된 브랜치나 샌드박스와 함께 쓰는 것이 안전합니다.
2026-10-28 확인
auto mode는 배포·강제 푸시 같은 위험은 막고, 작업 폴더 안 일은 허용한다
code.claude.com/docs/en/permission-modes
공식 문서 화면 캡처 · 2026-10-28 확인
Claude Code 권한 모드 표. 모드마다 묻지 않고 실행하는 범위 가 다르다. auto는 ‘백그라운드 안전 검사와 함께 전부’, 긴 작업에 적합.
막음 : curl | bash, 운영 배포, 강제 푸시, 보안 테스트 삭제, 자격증명 출력허용 : 작업 폴더 안 파일 작업, lock 파일에 있는 의존성 설치, 읽기 전용 요청사람이 “푸시하지 마”라고 하면 그 경계도 지켜진다
공식 문서의 기본 규칙입니다. 막는 쪽에는 내려받아 바로 실행하기, 운영 배포와 마이그레이션, 강제 푸시와 하드 리셋, 보안 관련 테스트를 지우거나 주석 처리하기, 자격증명을 대화에 출력하기 같은 행동이 있습니다. 허용하는 쪽에는 작업 폴더 안의 파일 작업, lock 파일에 이미 적힌 의존성 설치, 읽기 전용 HTTP(HyperText Transfer Protocol, 웹 통신 규약) 요청이 있습니다. 대화에서 푸시하지 말라고 말하면 그 경계도 분류기가 따릅니다. 전체 규칙은 claude auto-mode defaults 명령으로 볼 수 있으니 관심이 있으면 직접 열어 보셔도 좋습니다.
2025-04-16 → 2026-10-28 확인
Codex는 샌드박스 안은 자동, 밖으로 나갈 때만 승인으로 푼다
developers.openai.com/codex/agent-approvals-security
공식 문서 화면 캡처 · 2026-10-28 확인
OpenAI Codex 문서 ‘Agent approvals & security’. 기본은 네트워크 끔 + OS 샌드박스 이고, 승인 정책이 언제 멈추고 물을지 정한다.
OS 샌드박스(격리 공간) 안은 자동 , 밖으로 나갈 때만 승인. 기본은 네트워크 끔·작업 폴더 안에서만 쓰기.
auto-review는 승인이 필요한 행동만 모델이 검토한다. 승인과 샌드박스를 모두 끄는 위험 옵션은 문서가 권장하지 않는다.
Claude Code는 분류기가 행동마다 , Codex는 격리 공간이 경계 를 긋는다. 모델 판단 층과 OS가 막는 층을 함께 쓰는 것이 안전.
같은 문제를 Codex는 다른 방식으로 풉니다. 기본은 OS가 강제하는 샌드박스 안에서 작업 폴더만 쓰고 네트워크는 끄는 것입니다. 샌드박스 안의 작업은 승인 없이 돌고, 밖으로 나가려 할 때 승인을 요청합니다. 설정에서 auto_review를 켜면 승인이 필요한 행동만 모델이 먼저 검토합니다. 샌드박스 밖의 행동만 본다는 점이 Claude Code의 분류기와 다릅니다. 문서에는 승인과 샌드박스를 모두 끄는 위험 옵션도 있고 권장하지 않는다고 적혀 있습니다. 어느 도구든 모델이 판단하는 층과 운영체제가 막는 층을 함께 쓰는 것이 안전합니다. 2025년 4월 처음 나온 suggest, auto-edit, full-auto 이름은 이 문서 화면에서는 확인되지 않아 다루지 않습니다. 묶어 보면 장점은 격리된 공간 안에서는 승인 없이 돈다는 것이고, 단점은 샌드박스 밖의 행동만 모델이 본다는 점과 위험 옵션이 있다는 점입니다. 의미는 두 도구가 같은 문제를 다른 경계로 푼다는 것입니다.
축 2 · ‘계속’
에이전트가 “다 했습니다”라고 멈추는 문제
작업 ‘다 했습니다’ 예전엔 사람이, 지금은 장치가 ‘계속’ 실제 상태 테스트 3개 실패 확인 계속
채팅 IDE에서는 사람이 ‘계속’ 을 입력했습니다. 터미널 에이전트는 스스로 멈추는데, 멈추는 시점이 이르다 는 새 문제가 생겼습니다.
승인이 자동화돼도 문제는 남습니다. 에이전트가 턴을 끝냈다고 일이 끝난 것은 아닙니다. 채팅 IDE(Integrated Development Environment, 통합 개발 환경) 시절에는 사람이 답을 붙여넣고, 실행하고, 오류를 다시 넣고, 계속이라고 입력했습니다. 터미널 에이전트는 이 루프를 스스로 돌지만, 도구를 더 부르지 않으면 멈춥니다. 테스트가 아직 실패하는데도 다 했다고 보고하는 일이 흔합니다. 그래서 계속할지를 에이전트의 기분이 아니라 검사 가능한 기준으로 정하는 장치가 필요해졌습니다. 이제 그 역사를 따라갑니다.
2025-07-14
반복 실행 루프의 대표 기법 Ralph: 같은 프롬프트를 셸 루프로 계속 넣는다
ghuntley.com/ralph
원문 블로그 화면 캡처 · 2025-07-14
Geoffrey Huntley의 2025-07-14 블로그 글 ‘소프트웨어 엔지니어 Ralph Wiggum’. 심슨 캐릭터 이름을 딴 반복 실행 기법 을 소개.
$ while :; do cat PROMPT.md | claude-code ; done
한 줄 루프로 누구나 재현 한다. 계속할지를 모델이 아닌 바깥 루프가 정하고, 테스트·타입 검사가 나쁜 코드를 걸러낸다.
새 프로젝트를 뼈대부터 만들 때 맞고 숙련자의 지도가 필요 하다고 글도 말한다. while 루프라 멈춤 조건이 따로 없다.
‘계속’의 결정이 사람에서 바깥 루프 로 옮겨 간 출발점. 이후 공식 플러그인·/goal로 이어진다.
같은 프롬프트를 되풀이해 넣는 반복 실행 루프로 알려진 대표 기법이 Ralph입니다. 가장 단순한 형태는 한 줄짜리 셸 루프입니다. 프롬프트 파일을 에이전트에 넣고, 끝나면 다시 넣습니다. 원문에서 Huntley가 강조하는 것은 한 루프에 한 가지 일, 매번 같은 스펙과 계획을 맥락에 넣기, 빠른 테스트와 타입 검사로 잘못된 코드를 즉시 걸러내기입니다. 글의 원문 명령은 claude-code라고 되어 있습니다. 중요한 것은 계속할지를 모델이 아니라 바깥 루프가 정한다는 구조입니다. 새 프로젝트를 뼈대부터 만들 때 잘 맞고, 숙련된 사람의 지도가 필요하다고 글도 말합니다. 묶어 보면 장점은 단순해서 누구나 따라 할 수 있다는 것이고, 단점은 숙련된 사람의 지도가 필요하고 멈춤 조건이 없다는 것입니다. 의미는 계속할지의 판단을 바깥 루프가 맡는 구조의 출발점이라는 점입니다.
2025-11-16
공식 플러그인: 바깥 루프를 세션 안의 훅으로
github.com/anthropics/claude-plugins-official/tree/main/plugins/ralph-loop
공식 저장소 화면 캡처 · 2026-10-28 확인 (현재 위치)
Anthropic 공식 플러그인 저장소의 ralph-loop README. ‘Ralph는 Bash 루프’라는 설명과 Stop 훅이 종료 시도를 가로챈다 는 핵심 개념.
Stop 훅(응답이 끝날 때 실행되는 장치)이 종료를 가로채 같은 프롬프트를 다시 넣어, 세션 안에서 완료 문구까지 반복한다.
완료 문구는 정확한 문자열 일치 라 여러 조건을 표현할 수 없다. 최대 반복 횟수를 안전망으로 두라고 안내한다.
커뮤니티 꼼수가 공식 기능(훅) 이 된 사례. 다음 장에서 Stop 훅이 ‘계속’의 자리임을 확인한다.
/ralph-loop "…" --completion-promise "DONE" --max-iterations 50
2025년 11월 Anthropic이 Ralph를 공식 플러그인으로 만들었습니다. 바깥 셸 루프 대신 Stop 훅을 씁니다. Claude가 끝내려고 하면 훅이 종료를 막고 같은 프롬프트를 다시 줍니다. 이전 작업은 파일과 git 기록에 남아 있으니 다음 반복이 그것을 보고 이어 갑니다. 옵션은 두 개입니다. 완료 문구를 정하는 옵션과 최대 반복 횟수입니다. 저장소 안내는 완료 문구가 정확한 문자열 일치라서 여러 조건을 표현할 수 없으니, 최대 반복을 항상 안전망으로 두라고 합니다. 이 플러그인은 현재 공식 플러그인 저장소로 옮겨져 이름이 ralph-loop이고, 중단 명령은 cancel-ralph입니다. 묶어 보면 장점은 바깥 셸 없이 세션 안에서 반복된다는 것이고, 단점은 완료 문구가 문자열 일치뿐이라 복잡한 조건을 못 쓴다는 것입니다. 의미는 커뮤니티의 꼼수가 공식 기능으로 올라왔다는 점입니다.
질문 시간 · 약 5분
여기까지,
지금까지 다룬 것: 분류기 구조 · 3단 판단 흐름 · 한계 수치 · 기본 차단과 허용 · Codex 승인 모드 · 너무 일찍 멈춘다 · Ralph 루프 · 공식 ralph-loop 플러그인
여기서 잠시 멈추고 질문을 받겠습니다. 지금까지 본 내용 가운데 이해가 안 된 곳, 자기 도구에서는 어떻게 되는지 궁금한 곳, 동의하지 않는 곳 무엇이든 좋습니다. 질문이 바로 나오지 않으면 화면 아래의 화면들 가운데 다시 보고 싶은 장을 말해 달라고 합니다.
2025-06-30 → 2025-11-16
‘계속’의 자리는 턴이 끝나는 순간의 훅
작업 · 도구 호출 응답 끝, 멈추려 함 완료 조건 확인 Stop 훅이 종료 가로채기 종료 매 턴 끝 미충족 충족
Stop 훅은 매 턴이 끝날 때 실행됩니다. 여기서 스크립트나 프롬프트가 끝낼지 이어갈지 를 정합니다.
공식 Hooks는 2025년 6월 30일 버전에 들어왔습니다. 그중 Stop 훅은 Claude가 응답을 끝낼 때마다 불립니다. 여기에서 결과를 되돌려 주면 Claude는 멈추지 않고 이어 갑니다. Ralph 플러그인은 이 자리에 같은 프롬프트를 넣고, 뒤에 나올 /goal은 이 자리에 평가자 모델을 둡니다. 묶어 보면 계속할지의 판단이 사람의 입력에서 훅이라는 자동화 지점으로 옮겨 간 것입니다. 훅이 항상 같은 일을 하게 만들면 무한 루프가 될 수 있어서, 횟수 상한이 반드시 필요합니다.
2026-03-06
/loop: 정해진 간격으로 되풀이한다
code.claude.com/docs/en/scheduled-tasks
공식 문서 화면 캡처 · 2026-10-28 확인
Claude Code 문서의 예약 방식 비교표(Cloud·Desktop·/loop). /loop은 내 컴퓨터에서, 세션이 열려 있어야 하며 최소 간격 1분 .
> /loop 5m check if the deployment finished
시간 간격 (1분부터)으로 되풀이해 배포 확인·CI(Continuous Integration, 지속적 통합) 지켜보기에 맞다. 간격을 생략하면 Claude가 1분~1시간 안에서 정한다.
세션이 열려 있어야 돈다. 반복 작업은 7일 뒤 자동 만료되고, 목표 달성까지 도는 기능은 아니다.
‘계속’을 시간 기준 으로 자동화한 것. 목표 기준은 다음 장의 /goal이다.
/loop는 이름과 달리 목표가 끝날 때까지 도는 기능이 아닙니다. 프롬프트를 정해진 간격으로 다시 실행합니다. 배포가 끝났는지 5분마다 확인하거나, 열어 둔 PR(Pull Request, 변경 병합 요청)의 CI(Continuous Integration, 지속적 통합)를 지켜보는 일에 맞습니다. 간격을 쓰지 않으면 Claude가 한 번 돌 때마다 다음 대기 시간을 1분에서 1시간 사이로 정합니다. 세션이 열려 있을 때만 동작하고, 반복 작업은 7일 뒤 스스로 만료되도록 설계돼 있어 잊어버린 루프가 영원히 도는 일을 막습니다. 세션과 상관없이 돌려야 하면 문서가 권하듯 클라우드 예약 작업이나 데스크톱 예약 작업을 씁니다. 묶어 보면 장점은 주기적인 확인 작업을 맡길 수 있다는 것이고, 단점은 세션이 열려 있어야 하고 7일 뒤 만료되며 목표 달성 기준이 아니라는 것입니다. 의미는 계속의 기준이 시간이라는 점입니다.
2026-04-30
Codex가 먼저: 목표를 주면 끝났다고 판단할 때까지
github.com/openai/codex/releases/tag/rust-v0.128.0
공식 릴리스 노트 화면 캡처 · 2026-10-28 확인
OpenAI Codex 0.128.0(2026-04-30) 릴리스 노트. 새 기능 첫 줄에 /goal 워크플로 추가 가 적혀 있다.
“Added persisted /goal workflows … TUI controls for create, pause, resume, and clear.”지속되는 /goal 워크플로를 추가했다 … 만들기·일시정지·재개·삭제를 위한 TUI(Terminal User Interface, 터미널 화면) 조작. openai/codex · rust-v0.128.0
목표를 저장해 턴이 끝나도 이어 가고 , 일시정지·재개·삭제를 화면에서 제어한다.
릴리스 노트에는 기능 추가가 한 줄뿐이다. Simon Willison은 토큰 예산을 다 쓸 때까지 도는 구조라 설명한다.
목표 기준의 ‘계속’은 Codex가 먼저 (4월 30일) 넣었고, 한 달 안에 Claude Code가 따라왔다.
/loop는 시간으로 반복하는 것이고, 목표 달성까지 계속하는 기능은 4월 30일 Codex CLI(Command-Line Interface, 명령줄 도구) 0.128.0이 먼저 넣었습니다. 릴리스 노트에는 지속되는 goal 워크플로가 있고, 화면에서 만들고 멈추고 다시 시작하고 지울 수 있다고 적혀 있습니다. Simon Willison은 이것을 OpenAI판 Ralph 루프라고 소개했고, 목표를 달성했다고 평가할 때까지 또는 설정한 토큰 예산을 다 쓸 때까지 계속 도는 구조라고 설명했습니다. 이 발상이 한 달 안에 Claude Code에도 들어옵니다. 묶어 보면 장점은 목표가 저장돼 이어 간다는 것이고, 단점은 릴리스 노트만으로는 세부 동작을 알 수 없고 예산이 소진될 때까지 돌 수 있다는 것입니다. 의미는 목표 기준의 계속이 Codex에서 먼저 나왔다는 점입니다.
2026-05-11
Claude Code /goal: 완료 조건을 주면 해제될 때까지 계속
code.claude.com/docs/en/goal
공식 문서 화면 캡처 · 2026-10-28 확인
Claude Code 문서 ‘Keep Claude working toward a goal’(목표를 향해 계속 일하게 하기). 완료 조건이 충족될 때까지 턴마다 멈추지 않는다 는 설명.
> /goal all tests in test/auth pass and the lint step is clean
완결된 목표 를 주면 별도 평가자가 매 턴 판정해, 몇 시간 단위의 일을 사람 없이 맡길 수 있다.
평가자는 대화에 드러난 것만 본다. 파일을 읽거나 명령을 돌리지 못하니 ‘잘 만들어’ 같은 모호한 조건은 판정할 수 없다.
‘계속’ 입력이 검사 가능한 완료 조건 으로 바뀌었다. 8교시에서 쓴 테스트가 그대로 조건이 된다.
Claude Code는 5월 11일 버전에 /goal을 넣었습니다. 완료 조건을 문장으로 주면 Claude가 매 턴 뒤에 멈추지 않고 이어 갑니다. 여기서 핵심은 판정 주체입니다. 일하는 모델이 다 했다고 말하는 것이 아니라, 매 턴이 끝날 때 별도의 작은 모델이 조건이 충족됐는지 확인합니다. 아직이면 Claude가 다음 턴을 시작합니다. 앞에서 본 계속이라는 입력이 완결된 목표라는 기준으로 바뀐 순간이고, 그 덕분에 몇 시간, 하루 단위의 일을 맡길 수 있게 됩니다. 이 장의 화면은 공식 문서이고 조건 예시도 문서 그대로입니다. 묶어 보면 장점은 별도 평가자가 판정하므로 오래 맡길 수 있다는 것이고, 단점은 평가자가 대화에 나온 것만 보기 때문에 조건을 증명 가능하게 써야 한다는 것입니다. 의미는 계속 입력이 완료 조건으로 대체됐다는 점입니다.
공식 문서 · How evaluation works
/goal의 한 바퀴: 일하고, 평가하고, 이어 간다
/goal 조건 최대 4,000자 Claude가 한 턴 수행 평가자 (작은 모델) 대화만 읽음 충족 → 해제 불가능 → 해제 턴 끝 미충족
평가자는 도구를 부르지 않고 대화에 드러난 것만 봅니다. 그래서 조건은 Claude의 출력으로 증명할 수 있어야 합니다.
문서에 따르면 /goal은 세션 범위의 프롬프트 기반 Stop 훅을 감싼 것입니다. 턴이 끝나면 조건과 지금까지의 대화를 작은 빠른 모델에 보냅니다. 평가 결과는 세 가지입니다. 아직이면 이유를 다음 턴의 지침으로 삼아 이어 가고, 충족이면 목표를 해제합니다. 불가능하다고 판단하면 실패로 기록하고 해제합니다. 평가자는 파일을 읽거나 명령을 돌리지 못하므로, 테스트가 통과했다는 증거가 대화에 나타나야 합니다. 평가 비용은 작은 모델이라 보통 본작업에 비해 미미하다고 문서가 말합니다.
공식 문서 · Compare ways to keep a session running
/goal, /loop, Stop 훅: 다음 턴을 시작하는 쪽이 다르다
code.claude.com/docs/en/goal
공식 문서 화면 캡처 · 2026-10-28 확인
같은 문서의 ‘세션을 계속 돌리는 방법 비교’ 표(Approach / Next turn starts when / Stops when). 다음 턴이 언제 시작되고 언제 멈추는가 로 세 방식을 나눈다.
/goal : 턴이 끝나면, 조건 충족·불가능 판정까지/loop : 시간이 되면, 사용자가 멈추거나 Claude가 끝났다고 판단할 때까지Stop 훅 : 턴이 끝나면, 내가 쓴 스크립트·프롬프트가 결정
auto mode는 도구마다 승인, /goal은 턴마다 승인을 없앱니다.
셋의 차이는 다음 턴을 무엇이 시작하느냐입니다. /goal과 Stop 훅은 턴이 끝날 때마다 검사합니다. 그래서 목표가 끝날 때까지 이어 가는 용도에 맞습니다. /loop는 시간이 되면 시작하므로 배포 확인이나 PR 지켜보기 같은 주기적 일에 맞습니다. 직접 짠 검사가 필요하면 Stop 훅에 스크립트를 넣을 수 있습니다. 문서는 auto mode와 /goal을 서로 보완하는 관계로 설명합니다. auto mode는 도구 호출마다 뜨는 승인을, /goal은 턴마다 사람을 부르는 일을 없앱니다. 둘을 함께 켜야 자리를 비울 수 있습니다.
공식 문서 · Write an effective condition
좋은 완료 조건은 네 조각으로 이루어진다
나쁜 조건 좋은 조건 = 네 조각 로그인 기능 잘 만들어 테스트 좀 고쳐 리팩터링 끝날 때까지 ① 끝 상태 하나: 테스트 통과 ② 확인 방법: npm test 종료 코드 0 ③ 건드리면 안 되는 것: 테스트 파일 수정 금지 ④ 상한: 20턴이면 멈춤 측정 가능하게
조건에서 가장 중요한 것은 Claude가 스스로 증명할 수 있는 끝 상태 입니다. 8교시의 테스트가 그대로 완료 조건이 됩니다.
공식 문서가 권하는 조건의 구성은 세 가지입니다. 측정 가능한 끝 상태 하나, 그것을 증명하는 방법, 그리고 지나가는 길에 바뀌면 안 되는 제약입니다. 여기에 문서는 턴 수나 시간 제한을 조건 안에 넣을 수 있다고 알려 줍니다. 예를 들어 20턴 뒤에는 멈춘다는 식입니다. 로그인 기능을 잘 만들라는 문장에는 평가자가 판단할 근거가 없습니다. 반면 npm test가 종료 코드 0이고 다른 테스트 파일은 바뀌지 않았다는 조건은 대화 속 출력으로 바로 확인됩니다. 8교시에서 스펙을 테스트로 바꾼 이유가 여기서 이어집니다. 조건은 최대 4,000자까지 쓸 수 있습니다.
공식 문서 형식 + 예시 문장
조건 문장 예: 끝 상태, 확인, 제약, 상한
code.claude.com/docs/en/goal
공식 문서 화면 캡처 · 2026-10-28 확인
같은 문서의 ‘Write an effective condition’ 절. 좋은 조건은 측정 가능한 끝 상태 하나, 확인 방법, 지켜야 할 제약 을 담고 최대 4,000자까지 쓸 수 있다.
> /goal npm test 통과(종료 코드 0) , 린트(코드 검사) 경고 없음,
기존 테스트 파일은 수정 금지 ,
20턴이 지나면 멈추고 현황 보고
비대화형: claude -p "/goal …" 은 끝날 때까지 한 번에 실행
화면의 문서는 좋은 조건의 세 요소와 4,000자 한도, 턴 수 상한 조항을 설명합니다. 문서 앞쪽이 예로 드는 조건은 모듈을 새 API(Application Programming Interface, 프로그램 연동 규약)로 옮기고 모든 호출부가 컴파일되며 테스트가 통과할 때까지, 설계 문서의 인수 조건이 모두 성립할 때까지, 파일을 각각 크기 한도 아래로 쪼갤 때까지, 라벨이 붙은 이슈 목록이 빌 때까지 같은 것들입니다. 오른쪽은 이 형식에 맞춰 만든 예시 문장입니다. 테스트를 고쳐서 통과시키는 꼼수를 막으려고 기존 테스트 파일은 수정하지 못하게 제약을 넣습니다. 마지막 줄의 상한은 폭주를 막는 안전망이고 평가자가 대화에서 판단합니다. 비대화형 실행은 모든 반복이 끝날 때까지 출력이 안 보일 수 있으니 stream-json 옵션을 함께 씁니다.
공식 문서 종합
오래 맡길수록 상한이 먼저다
오래 맡긴 루프 폭주를 막는 장치 자동 승인 /goal · Ralph 횟수 상한: --max-iterations, ‘20턴’ 조항 시간 상한: /loop 7일 만료 분류기 차단: 연속 3회·누적 20회에서 멈춤 테스트 파일 보호 · 격리 브랜치/워크트리 비용 확인: /goal 상태의 토큰 소비 항상 같이
상한은 횟수 · 시간 · 차단 · 테스트 보호 · 비용 확인 다섯 겹입니다. 한 겹이 뚫려도 다음 겹이 멈춥니다.
자동 승인과 자동 계속을 합치면 사람 없이 오래 돌 수 있어서 상한이 필수입니다. Ralph 플러그인은 최대 반복 횟수를 안전망으로 권합니다. /goal은 조건 안에 턴 수 조항을 넣고, 진행 중 상태 화면에서 경과 시간, 평가한 턴 수, 누적 토큰 소비를 볼 수 있습니다. /loop는 7일 뒤 만료됩니다. auto mode는 연속 3번, 누적 20번 차단되면 멈추고 사람에게 묻습니다. 여기에 8교시에서 본 테스트 파일 보호와 격리된 워크트리를 더합니다. 비용은 평가자보다 본작업이 지배하므로, 시작할 때 몇 턴까지 허용할지를 정해 두면 덜 막힙니다.
2023-05 → 2026-03
100K에서 1M까지, 3년 만에 열 배
2023-05 2025-04 2025-08 2026-02 2026-03-13 Claude 100K GPT-4.1 1M Sonnet 4 1M 베타 Opus 4.6 1M 베타 Claude 1M 정식 할증 없음
1M 정식 이후에는 최신 Claude 모델이 Claude Code에서 기본으로 1M을 씁니다. OpenAI의 최신 API(Application Programming Interface, 프로그램 연동 규약) 모델 문서도 1.05M입니다. → 5교시 압축의 한계
5교시에서 압축의 한계를 이야기했습니다. 창이 작아서 자주 압축하고, 압축할 때마다 정보가 빠졌습니다. 그 해법 하나가 창 자체를 키우는 것이었습니다. 2023년 5월 Claude 100K, 2025년 4월 GPT-4.1의 1M, 2025년 8월 Sonnet 4의 1M 베타, 2026년 2월 Opus 4.6의 1M 베타를 거쳐 2026년 3월 13일 Claude의 1M이 정식 출시됐습니다. 지금 Claude Code 문서는 Sonnet 5 이상 같은 최신 모델이 1M을 기본으로 쓴다고 적고, 200K를 유지하려면 환경 변수로 끄라고 안내합니다. Codex의 창 크기는 모델과 설정에 따라 달라 이 장에서는 숫자를 단정하지 않습니다. OpenAI API 모델 문서의 최신 모델은 1.05M으로 표시됩니다.
2026-03-13
1M 정식 출시: 할증 없이, 기본 한도 그대로
claude.com/blog/1m-context-ga
공식 발표 화면 캡처 · 2026-03-13
Claude 공식 발표 ‘Opus 4.6·Sonnet 4.6에서 1M 컨텍스트 정식 출시’. 1M 전 구간에 표준 요금 , 이미지·PDF는 600장까지.
할증 없이 9K 요청과 900K 요청의 토큰 단가가 같고, 이미지·PDF는 요청당 100쪽에서 600쪽 으로 늘었다.
78.3%는 Opus 4.6의 MRCR(Multi-Round Co-reference Resolution, 다회차 지시어 해소) v2 점수 (긴 글 속 정보 찾기, 공식 수치). 후기의 ‘압축 15% 감소’는 한 고객의 사례다.
‘창이 작아 자주 압축’하던 문제를 창 자체를 키워 푼 해법. 단 다음 장처럼 채울수록 정확도가 떨어질 수 있다.
3월 13일 발표의 요점은 세 가지입니다. 200K를 넘는 요청도 같은 토큰 단가로 계산하는 할증 폐지, 한 요청의 이미지와 PDF 한도를 100에서 600으로 늘린 것, 베타 헤더 없이 쓸 수 있게 한 것입니다. Opus 4.6이 긴 문맥 검색 벤치마크인 MRCR(Multi-Round Co-reference Resolution, 다회차 지시어 해소) v2에서 78.3%를 기록했다고 발표했습니다. 글에는 고객 후기로 압축 이벤트가 15% 줄었다는 한마디도 있지만 이는 한 고객의 사례라 일반화하기 어렵습니다. 정확한 가격과 포함 여부는 모델과 요금제마다 다르니 문서에서 확인하는 편이 좋습니다. 묶어 보면 장점은 할증 없이 긴 요청을 쓴다는 것이고, 단점은 점수가 공식 발표 수치이고 후기는 한 고객 사례라 일반화할 수 없다는 것입니다. 의미는 압축 문제를 창을 키워서 푼 해법이라는 점입니다.
2025-07-14 · 2026-10-28 확인
창이 커도 채울수록 정확도는 떨어질 수 있다
research.trychroma.com/context-rot
Chroma 기술 보고서 화면 캡처
Chroma 기술 보고서 ‘Context Rot’(2025-07-14). 입력 토큰이 늘수록 LLM(Large Language Model, 대규모 언어 모델) 성능이 달라진다며 18개 모델 을 평가했다고 소개.
입력이 길어질수록 성능이 달라지는 현상을 18개 모델 로 측정해, 큰 창의 한계를 숫자로 보여 준다.
창이 커져도 압축은 사라지지 않고 늦어질 뿐 이다. 시점은 CLAUDE_CODE_AUTO_COMPACT_WINDOW로 조절한다.
1M이어도 중요한 결정은 파일에 적어 둔다 (8교시 진행 파일·스펙).
창이 커졌다고 문제가 다 풀린 것은 아닙니다. Chroma의 보고서는 입력이 길어질수록 모델 성능이 불균등하게 떨어진다는 것을 측정했습니다. 그래서 1M이어도 오래 일하면 압축은 일어납니다. 다만 일어나는 시점이 늦어지고 횟수가 줄 뿐입니다. Claude Code 문서는 자동 압축을 시작하는 창 크기를 환경 변수로 조절할 수 있게 하고, 허용 범위를 10만에서 100만 토큰으로 안내합니다. 그래서 8교시에서 만든 진행 파일과 스펙처럼 중요한 결정은 대화가 아니라 파일에 적어 두는 습관은 1M 시대에도 그대로 유효합니다. 묶어 보면 장점은 큰 창의 한계를 측정으로 보여 준다는 것이고, 단점은 창이 커져도 압축이 늦어질 뿐 사라지지 않는다는 것입니다. 의미는 1M 시대에도 중요한 결정은 파일에 남겨야 한다는 점입니다.
정리
승인·계속·창, 세 병목을 기계가 맡았다
사람이 하던 것 기계가 맡은 방식 그래도 사람 몫 도구마다 승인 턴마다 ‘계속’ 창 관리·압축 분류기 (auto mode) 평가자 (/goal) 큰 창 (1M) 완료 조건 쓰기 상한·테스트 보호 결과 판정
남는 사람의 일은 완료 조건 쓰기, 상한 정하기, 결과 판정 입니다. → 10교시: 이 모든 장치를 묶는 말, 하네스와 MCP(Model Context Protocol, 모델 컨텍스트 프로토콜)
오늘 세 가지가 바뀌었습니다. 승인은 분류기가, 계속은 평가자가, 창은 1M이 맡았습니다. 하지만 사람이 없어도 되는 것은 아닙니다. 완료 조건을 검증 가능하게 쓰는 일, 상한과 테스트 보호를 정하는 일, 마지막 결과를 판정하는 일이 남습니다. 다음 시간에는 지금까지 본 장치들, 즉 지침 파일과 권한과 훅과 루프를 한꺼번에 가리키는 하네스라는 말과, 에이전트에 도구를 붙이는 표준인 MCP(Model Context Protocol, 모델 컨텍스트 프로토콜)를 다룹니다.
3회차 · 10교시
하네스와 MCP
에이전트를 둘러싼 장치에 이름이 붙은 과정, 그 장치 가운데 바깥 세계와 잇는 MCP(Model Context Protocol, 모델 컨텍스트 프로토콜), 그리고 실제로 많이 쓰는 MCP 도구를 하나씩 봅니다.
하네스 2025-11-26 MCP 구조·보안 Serena 심볼 탐색 Playwright 브라우저 자동화
오늘 10교시는 세 덩어리입니다. 먼저 지금까지 쌓은 장치들을 통틀어 하네스라고 부르는 이유를 봅니다. 다음으로 그 가운데 에이전트를 바깥 세계와 연결하는 MCP(Model Context Protocol, 모델 컨텍스트 프로토콜)의 구조와 보안을 봅니다. 마지막으로 제가 실제로 쓰거나 많이 쓰이는 MCP 도구를 한 장에 하나씩 소개하고, 도구가 많아질수록 창을 잡아먹는 문제와 토큰 절약 방법으로 마무리합니다. 아래 화면은 모두 오늘 확인한 실제 공식 문서입니다.
9교시 → 10교시
오래 돌려 보니 남는 세 가지 문제
9교시 · 오래 맡기기 그래도 남는 문제 10교시 자동 승인 /goal · 루프 1M 컨텍스트 세션이 끊기면 기억이 사라진다 저장소 밖 세계를 볼 수 없다 도구가 늘수록 창이 찬다 하네스 MCP 구조·보안 주로 쓰는 MCP 토큰 절약 오래 돌려 보니 답
9교시에서 승인, 계속, 창 크기를 풀었습니다. 기록, 연결, 비용 은 하네스와 MCP의 몫입니다. → 9교시
9교시에서는 사람이 하던 승인과 계속을 자동화하고, 컨텍스트 창을 1M까지 키우는 이야기를 했습니다. 그런데 몇 시간씩 돌려 보면 새 문제가 나옵니다. 세션이 끊기면 에이전트는 앞의 일을 기억하지 못합니다. 저장소 밖에 있는 브라우저, 이슈, 데이터베이스는 보지 못합니다. 그리고 연결하는 도구가 늘수록 그 설명만으로 창이 찹니다. 오늘은 이 세 문제에 대한 답을 차례로 소개합니다.
2025-02-24 → 2026-02-11
‘하네스’는 Claude Code 출시 7개월 뒤에야 공식 글에 등장했다
2025-02-24 Claude Code 리서치 프리뷰 (‘하네스’라는 말 없음) 2025-09-29 Anthropic Agent SDK 글 공식 글의 첫 사용 2025-11-26 Anthropic 장기 실행 하네스 2026-02-11 OpenAI Harness engineering
Claude Code 출시 때는 없던 말입니다. 하네스는 모델을 둘러싼 장치 전부를 뜻합니다. 공식 글 가운데 첫 사용은 2025-09-29 입니다. → 다음 3장
Claude Code가 2025년 2월에 나왔을 때는 하네스라는 말을 쓰지 않았습니다. 제가 확인한 공식 글에서 처음 나온 것은 2025년 9월 29일 Anthropic의 Agent SDK(Software Development Kit, 소프트웨어 개발 키트) 글입니다. 그 두 달 뒤 Anthropic이 장기 실행 에이전트를 위한 하네스 글을 냈고, 2026년 2월에는 OpenAI가 하네스 엔지니어링이라는 글로 같은 말을 썼습니다. 말이 퍼졌다는 것은 모델만큼 모델 주변 장치가 중요하다는 합의가 생겼다는 뜻입니다. 이 시기와 방식은 공식 글에서 확인한 범위이고, 블로그나 커뮤니티에서는 더 일찍 쓰였을 수 있습니다.
2025-09-29
첫 공식 사용: Claude Code를 움직이는 하네스
claude.com/blog/building-agents-with-the-claude-agent-sdk
공식 블로그 화면 캡처 · 2026-10-28 확인
Anthropic 블로그 ‘Claude Agent SDK로 에이전트 만들기’(2025-09-29). SDK는 Claude Code 위에서 에이전트를 만드는 도구 모음 이라고 소개.
“the agent harness that powers Claude Code”Claude Code를 움직이는 에이전트 하네스 Anthropic · 2025-09-29
Claude Code의 루프(맥락 모으기→행동→확인) 를 다른 에이전트에도 쓰도록 SDK로 열었다.
공식 글에서 ‘하네스’는 본문에 딱 한 번 나온다. SDK 이름은 이후 Agent SDK로 바뀌었다.
Claude Code를 모델이 아니라 하네스 로 보는 관점이 공식화된 첫 글.
이 글에서 하네스는 본문에 딱 한 번 나옵니다. Claude Code를 움직이는 에이전트 하네스가 다른 종류의 에이전트도 움직일 수 있다는 문장입니다. 즉 Claude Code는 모델 하나가 아니라, 모델에 도구와 루프를 붙인 하네스라는 관점이 여기서 공식화됩니다. 글은 에이전트의 일을 맥락 모으기, 행동하기, 결과 확인하기의 반복으로 설명합니다. 이 과정에서 만들 여러분의 하네스도 같은 모양의 루프를 갖게 됩니다. 묶어 보면 장점은 Claude Code의 루프를 다른 에이전트에도 쓸 수 있다는 것이고, 단점은 하네스라는 말이 본문에 한 번만 나와 정의가 빈약하다는 것입니다. 의미는 Claude Code를 하네스로 보는 관점의 공식화입니다.
2025-11-26
장기 실행 하네스: 세션이 끊겨도 이어 가게
anthropic.com/engineering/effective-harnesses-for-long-running-agents
Anthropic Engineering 화면 캡처 · 2025-11-26
Anthropic Engineering 글 ‘장기 실행 에이전트를 위한 하네스’(2025-11-26). 여러 창에 걸친 긴 일은 초기화 에이전트 + 코딩 에이전트 로 나눠 푼다.
세션이 끊겨도 진행 기록·기능 목록·git 로그 로 이어 가, 한 창에 안 끝나는 큰 일을 맡긴다.
새 세션은 앞의 일을 기억하지 못해 파일 기록이 곧 기억 이다. 초기화·코딩 에이전트는 첫 프롬프트만 다르다.
2교시 진행 파일의 확장판. 12교시 누적 과제 하네스에 가져올 구조 .
글의 문제의식은 단순합니다. 컨텍스트 창은 한정돼 있고, 큰 프로젝트는 한 창에 끝나지 않으며, 새 세션은 앞의 기억 없이 시작합니다. 교대 근무하는 엔지니어가 인수인계 없이 출근하는 것과 같다고 비유합니다. Anthropic은 첫 세션에서 환경을 준비하는 초기화 에이전트와, 이후 세션마다 조금씩 진전시키는 코딩 에이전트로 나눴습니다. 둘은 이름만 다르고 첫 사용자 프롬프트만 다릅니다. 다음 장에서 이 구조를 그림으로 봅니다. 묶어 보면 장점은 세션이 끊겨도 파일과 git으로 이어 간다는 것이고, 단점은 기록이 곧 기억이라 기록이 빠지면 이어 가지 못한다는 것입니다. 의미는 2교시 진행 파일의 확장판이라는 점입니다.
2025-11-26
세션 사이를 건너는 것은 파일과 git
첫 세션 · 초기화 에이전트 세션 사이에 남는 것 init.sh · claude-progress.txt feature_list.json · git 커밋 코딩 에이전트 진행·git 로그 읽기 테스트 후 passes 갱신·커밋 기능 하나만 구현 만든다 읽는다 갱신
기능 목록은 마크다운이 아니라 JSON(JavaScript Object Notation, 자바스크립트 객체 표기법) . 모델이 함부로 고치지 않도록 passes 항목만 바꾸게 했습니다. → 8교시 진행 파일
초기화 에이전트는 개발 서버를 띄우는 init.sh, 진행 기록 파일, 기능 목록 JSON(JavaScript Object Notation, 자바스크립트 객체 표기법), 첫 git 커밋을 만듭니다. 이후 세션의 코딩 에이전트는 이 진행 기록과 git 로그를 읽고 상황을 파악한 다음, 기능 하나만 구현하고 테스트하고 기록을 갱신합니다. 글은 기능 목록에 JSON을 쓴 이유로, 모델이 마크다운보다 JSON을 덜 함부로 고친다는 점을 듭니다. 2교시 과제 2에서 만든 진행 파일이 바로 이 생각의 작은 버전입니다. 여러분 하네스에 이 구조를 가져와도 좋습니다.
2026-02-11
OpenAI의 하네스 엔지니어링: 저장소가 기록 체계
“Humans steer. Agents execute.”사람은 방향을 잡고, 에이전트가 실행한다. OpenAI · 2026-02-11
저장소 안 문서 만 에이전트에게 존재한다는 원칙으로, 사람 코드 0줄에 약 5개월 만에 약 100만 줄(내부 베타 제품).
AGENTS.md에 다 적으면 맥락을 밀어내고 금방 낡아 약 100줄 목차로 줄였다. 한 작은 팀의 사례다.
구글 문서·슬랙·머릿속 지식은 Codex에게 없는 것과 같다. 14교시 ADR(Architecture Decision Record, 아키텍처 결정 기록) 로 이어진다.
openai.com/index/harness-engineering
OpenAI 원문 그림 · 2026-02-11
OpenAI 원문 그림. 구글 문서·슬랙 메시지·머릿속 지식은 Codex에게 없는 것과 같으니 마크다운으로 저장소에 넣으라 는 뜻.
OpenAI가 2026년 2월 11일에 낸 글입니다. 작은 팀이 Codex로 약 5개월 동안 코드를 한 줄도 직접 쓰지 않고 약 100만 줄짜리 내부 베타 제품을 만들었다고 합니다. 사람은 방향을 정하고 결과를 검증하고, 에이전트가 쓰고 리뷰합니다. 흥미로운 것은 지침 파일입니다. AGENTS.md 하나에 다 적었더니 맥락을 밀어내고 금방 낡아서, 약 100줄 목차로 줄이고 깊은 내용은 docs 디렉터리에 두었다고 합니다. 저장소 밖에 있는 지식은 에이전트에게는 없는 것이라는 주장이, 14교시 ADR(Architecture Decision Record, 아키텍처 결정 기록) 이야기와 이어집니다. 오른쪽 그림이 원문의 그림입니다. 구글 문서, 슬랙 메시지, 머릿속 지식처럼 저장소 밖에 있는 것은 Codex가 볼 수 없으니, 마크다운으로 저장소에 넣으라는 뜻입니다. 묶어 보면 장점은 저장소를 기록 체계로 삼아 사람 코드 없이 큰 제품을 만들었다는 것이고, 단점은 한 작은 팀의 사례이며 지침 파일이 금방 낡는다는 것입니다. 의미는 저장소 밖 지식은 에이전트에게 없다는 점입니다.
개념 · 하네스 지도
에이전트 = 모델 + 하네스
모델 하네스 = 모델을 둘러싼 장치 전부 지침 파일 CLAUDE.md · AGENTS.md 권한 허용·거부 규칙 도구 파일·셸·검색 MCP 바깥 세계 연결 훅 정해진 때 실행 스킬 필요할 때 읽는 지침 서브에이전트 창을 나눠 씀 루프 · /goal ‘계속’의 자동화 메모리 · 진행 파일 세션을 건너는 기록 에이전트 = 모델 + 하네스
같은 모델도 하네스에 따라 결과가 달라집니다. 이 과정의 누적 과제가 나만의 하네스 만들기 입니다.
지금까지 본 것을 한 장으로 모으면 이렇습니다. 지침 파일, 권한, 도구, MCP, 훅, 스킬, 서브에이전트, 루프, 그리고 세션을 건너는 기록입니다. 모델은 같아도 이 장치들을 어떻게 구성하느냐에 따라 실패율과 비용이 크게 달라집니다. 강조한 MCP가 오늘의 주제이고, 스킬은 11교시, 나머지는 앞 교시에서 이미 다뤘습니다. 도구마다 다르게 부르지만 구성요소는 거의 같다는 점이 중요합니다. Claude Code, Codex, Cursor 어느 도구를 쓰든 같은 지도로 읽을 수 있습니다.
2024-11-25
MCP: AI와 도구를 잇는 하나의 표준
anthropic.com/news/model-context-protocol
Anthropic 공식 발표 화면 캡처 · 2026-10-28 확인
Anthropic의 MCP 공개 글(2024-11-25). 데이터 소스마다 따로 만들던 연결을 하나의 프로토콜로 대체 한다고 설명.
연결마다 따로 만들던 구현을 하나의 프로토콜 로 통일해, 한 번 만든 서버를 여러 AI 앱이 쓴다.
도구 정의가 창을 차지하고, 서버가 권한을 요구 해 보안 문제도 따라온다(뒤의 세 장).
오늘 볼 도구들이 Cursor·Codex·VS Code 에서도 같은 방식으로 연결되는 이유.
MCP, Model Context Protocol은 2024년 11월 25일에 Anthropic이 오픈소스로 공개했습니다. 그 전에는 AI 앱마다 데이터 소스마다 연결 코드를 따로 만들어야 했습니다. MCP는 이 연결을 하나의 프로토콜로 통일합니다. 발표 때 Google Drive, Slack, GitHub, Git, Postgres, Puppeteer용 서버를 함께 냈습니다. 이후 다른 회사들도 받아들여서, 오늘 볼 도구들은 대부분 Claude Code가 아니어도 Cursor, Codex, VS Code에서 같은 방식으로 연결됩니다. 묶어 보면 장점은 연결 구현의 통일이고, 단점은 창 점유와 보안 문제가 따라온다는 것입니다. 의미는 오늘 볼 도구들이 여러 앱에서 같은 방식으로 붙는 이유입니다.
MCP 아키텍처
호스트, 클라이언트, 서버
MCP 호스트 서버마다 클라이언트 1개 Claude Code · Cursor 로컬 서버 Playwright · Serena 원격 서버 GitHub · Sentry 원격 서버 Supabase · Figma 서버가 내놓는 것 tools 실행할 수 있는 함수 resources 읽을 수 있는 데이터 prompts 재사용 템플릿 stdio HTTP HTTP
호스트는 서버마다 클라이언트를 하나씩 만듭니다. 로컬은 stdio (표준 입출력), 원격은 Streamable HTTP (HyperText Transfer Protocol, 웹 통신)입니다. → 12교시 MCP 연결
MCP의 참여자는 셋입니다. Claude Code나 VS Code 같은 AI 앱이 호스트이고, 호스트는 서버 하나당 클라이언트 하나를 만들어 전용 연결을 유지합니다. 서버는 컨텍스트를 제공하는 프로그램입니다. 내 컴퓨터에서 도는 로컬 서버는 표준 입출력, 즉 stdio로 통신하고, GitHub나 Sentry처럼 서비스가 호스팅하는 원격 서버는 Streamable HTTP(HyperText Transfer Protocol, 웹 통신 규약)를 씁니다. 서버가 내놓는 것은 세 가지입니다. 실행할 수 있는 도구, 읽을 수 있는 리소스, 재사용 프롬프트입니다. 이 가운데 에이전트가 가장 많이 쓰는 것이 도구입니다. 2026년 7월판 명세는 요청마다 필요한 정보를 담는 무상태 방식으로 바뀌었다는 점도 참고로만 짚어 둡니다.
Claude Code
claude mcp add 한 줄로 MCP 서버를 연결한다
code.claude.com/docs/en/mcp
공식 문서 화면 캡처
Claude Code 문서 ‘MCP로 도구에 연결하기’. 이슈 트래커 기능 구현, 모니터링 분석, DB(데이터베이스) 질의 같은 MCP로 할 수 있는 일 이 첫 절에 나온다.
$ claude mcp add --transport http notion \
https://mcp.notion.com/mcp
$ claude mcp add --transport stdio airtable \
-- npx -y airtable-mcp-server
$ claude mcp add --scope project ...
✓ project 범위는 .mcp.json 에 저장
범위: local(기본) · project(팀 공유) · user
project 서버는 처음 쓸 때 승인을 묻는다
연결은 claude mcp add 한 줄입니다. 원격 서버는 transport를 http로 주고 주소를 적고, 내 컴퓨터에서 실행하는 서버는 stdio로 두고 대시 두 개 뒤에 실행 명령을 적습니다. 공식 문서는 원격에는 HTTP를 권하고, SSE(Server-Sent Events, 서버 전송 이벤트) 방식은 더 이상 권하지 않는다고 합니다. 저장 범위는 local, project, user 세 가지입니다. project로 두면 저장소 루트의 .mcp.json에 들어가서 팀이 함께 쓸 수 있고, 보안을 위해 처음 쓸 때 승인을 묻습니다. 12교시 실습에서 여러분이 MCP 서버 하나를 직접 연결해 봅니다.
2025-04-01
보안 ①: 도구 설명에 숨긴 명령이 모델을 조종한다
invariantlabs.ai/blog/mcp-security-notification-tool-poisoning-attacks
보안 연구 글 화면 캡처 · 2026-10-28 확인
Invariant Labs 보안 공지(2025-04-01) ‘도구 오염 공격’. MCP의 심각한 취약점을 발견했고 Anthropic·OpenAI·Cursor 등이 영향권 이라고 적었다.
도구 설명이 프롬프트에 그대로 들어가는 구조를 짚어, MCP 클라이언트의 검증 공백 을 구체적 시연으로 보여 준다.
시연은 도구 설명을 검증·표시하지 않는 클라이언트 가 대상이다. 확인창에는 단순한 도구 이름만 보였다.
도구 설명도 신뢰 경계 밖의 입력 이다. 출처를 모르는 MCP 서버는 연결하지 않는다.
MCP 서버가 주는 도구 설명은 모델의 프롬프트에 그대로 들어갑니다. 2025년 4월 Invariant Labs는 이것을 악용한 도구 오염 공격을 공개했습니다. 겉보기에는 두 수를 더하는 도구인데, 설명 안에 숨은 지시가 있어서 모델이 사용자의 SSH(Secure Shell, 원격 접속 프로토콜) 키와 MCP 설정 파일을 읽어 도구 인자로 넘기게 만들었습니다. 사용자는 확인창에서 단순한 도구 이름만 봤습니다. 글은 도구 설명을 제대로 검증하거나 보여 주지 않는 모든 MCP 클라이언트에서 재현될 수 있다고 말합니다. 그래서 출처를 모르는 서버는 연결하지 않는 편이 낫습니다. 묶어 보면 장점은 위험을 구체적으로 시연했다는 것이고, 단점은 도구 설명을 검증하지 않는 클라이언트에 한정된 시연이라는 것입니다. 의미는 출처를 모르는 서버는 연결하지 않는 편이 낫다는 점입니다.
명세 2026-07-28판 · Supabase·Vercel 문서
보안 ②: 도구는 임의 코드 실행과 같다
modelcontextprotocol.io/specification/latest
MCP 명세 화면 캡처 · 보안 절은 3장
MCP 명세(2026-07-28판) 첫 화면. 오른쪽 목차의 ‘3. Security and Trust & Safety(보안·신뢰·안전)’ 절이 도구 보안 원칙을 다룬다.
명세: 도구는 임의 코드 실행, 호출 전 사용자 동의
신뢰한 서버만, 최소 권한: 읽기 전용, 프로젝트 한정
승인 단계를 끄지 않는다. 운영 데이터엔 연결 금지
→ 결론: MCP 도구는 자동 승인에서 빼고 최소 권한으로 연결한다
MCP 명세의 보안 절은 도구를 임의 코드 실행으로 취급하라고 말합니다. 도구가 하는 일을 설명하는 주석 같은 것도 신뢰할 수 있는 서버에서 받은 것이 아니면 믿지 말고, 도구를 부르기 전에 사용자의 명시적 동의를 받으라고 합니다. 서비스 쪽 문서도 같은 이야기를 합니다. Supabase는 읽기 전용 옵션과 프로젝트 한정 옵션을 쓰고 운영 데이터에는 연결하지 말라고 하고, Vercel은 연결하면 내 계정과 같은 권한을 AI에 주는 것이니 사람 확인을 켜 두라고 합니다. 9교시의 자동 승인과 연결해서, MCP 도구는 자동 승인 대상에서 신중하게 다루는 편이 낫습니다.
MCP 토큰 비용
도구가 많으면 일하기 전에 창이 찬다
모두 미리 싣는 방식 도구 검색 (지연 로딩) 서버 5개 · 도구 수십 개 도구 이름 + 설명 + 입력 스키마 전부 세션 시작에 창으로 쓰지 않아도 창을 차지 시작 시: 도구 이름과 서버 지침만 로드 필요할 때 ToolSearch로 해당 도구 정의만 로드 창은 일에 쓴다 기본값
MCP 도구는 이름·설명·입력 스키마 (받는 입력의 형식)가 모델에게 전달됩니다. 서버를 많이 붙일수록 쓰지도 않는 도구 가 창을 차지합니다. → 다음 장
MCP 서버를 연결하면 그 서버의 모든 도구 정의가 모델의 컨텍스트에 들어가야 합니다. 도구 이름, 설명, 입력 스키마가 도구마다 있으니, 서버를 여럿 붙이면 아직 일을 시작하기도 전에 창이 상당히 차 있게 됩니다. 이것은 9교시에서 본 컨텍스트 로트와 압축 문제를 더 빨리 만나게 합니다. 그래서 요즘 도구들은 도구 정의를 미리 다 싣지 않고, 필요할 때 찾아서 싣는 방식을 씁니다. 다음 장에서 Claude Code 공식 문서의 설명을 봅니다.
질문 시간 · 약 5분
여기까지,
지금까지 다룬 것: OpenAI 하네스 엔지니어링 · 하네스 구성요소 지도 · MCP의 등장 · MCP 구조 · MCP 연결하기 · MCP 보안: 도구 설명 주입 · MCP 보안: 원칙과 방어 · MCP의 토큰 비용
여기서 잠시 멈추고 질문을 받겠습니다. 지금까지 본 내용 가운데 이해가 안 된 곳, 자기 도구에서는 어떻게 되는지 궁금한 곳, 동의하지 않는 곳 무엇이든 좋습니다. 질문이 바로 나오지 않으면 화면 아래의 화면들 가운데 다시 보고 싶은 장을 말해 달라고 합니다.
Claude Code · MCP tool search
도구 검색: 이름만 싣고, 필요할 때 불러온다
code.claude.com/docs/en/mcp#scale-with-mcp-tool-search
공식 문서 화면 캡처
Claude Code 문서 ‘MCP 도구 검색으로 확장하기’. 도구 정의를 필요할 때까지 미뤄 세션 시작에는 도구 이름과 서버 지침만 싣는다.
시작에는 도구 이름·서버 지침만 싣고 필요할 때 정의를 불러와, 서버를 더 붙여도 창이 덜 찬다.
Claude Code 기준 기능 이라 다른 도구는 방식이 다를 수 있다. 서버 지침이 부실하면 검색에서 잘 안 찾힌다.
앞 장의 창 낭비 문제 에 대한 답. 도구 출력도 1만 토큰 초과 시 경고, 기본 상한 2.5만 토큰.
Claude Code 공식 문서에 따르면 도구 검색은 지금 기본값입니다. 세션을 시작할 때는 도구 이름과 서버 지침만 로드하고, 도구 정의는 클로드가 필요하다고 판단할 때 불러옵니다. 그래서 서버를 더 붙여도 창에 미치는 영향이 작다고 설명합니다. 환경 변수 ENABLE_TOOL_SEARCH로 끄거나, auto 뒤에 퍼센트를 붙여 도구 정의가 창의 그 비율을 넘을 때만 켜게 할 수도 있습니다. 도구가 돌려주는 출력도 별도로 제한합니다. 1만 토큰을 넘으면 경고하고 기본 상한은 2만 5천 토큰입니다. 서버를 만드는 쪽은 서버 지침을 잘 써야 검색에서 잘 찾힌다는 안내도 있습니다. 이 기능은 Claude Code 기준이고, 다른 도구는 방식이 다를 수 있습니다. 묶어 보면 장점은 서버를 늘려도 창이 덜 찬다는 것이고, 단점은 Claude Code 기준 기능이고 서버 지침이 부실하면 검색이 어렵다는 것입니다. 의미는 앞 장의 창 낭비 문제에 대한 답이라는 점입니다.
개념 · 도구 지도
무엇을 하게 해 주는가로 고른다
코드를 이해한다 브라우저를 본다 일하는 곳과 잇는다 배포·데이터 문서 조회 · Context7 최신 라이브러리 문서 브라우저 자동화 · Playwright MCP 접근성 트리로 조작 GitHub MCP 이슈 · PR · Actions Supabase MCP DB · 마이그레이션 언어 서버 · Serena 심볼 단위 탐색·편집 브라우저 진단 · Chrome DevTools MCP 콘솔·네트워크·성능 Figma MCP 디자인 → 코드 Vercel MCP 배포 · 로그 Sentry MCP 오류 · 이슈 분석
이 목록은 예시 입니다. 필요한 일이 생길 때 하나씩 붙이고, 안 쓰면 뺍니다.
이 아홉 개를 하는 일로 나눠 봅니다. 코드를 이해하는 쪽은 개념이 두 가지로 갈립니다. 최신 라이브러리 문서를 찾아 주는 문서 조회의 대표 도구가 Context7이고, LSP(Language Server Protocol, 언어 서버 프로토콜)로 심볼 단위로 코드를 찾고 고치는 대표 도구가 Serena입니다. 브라우저를 보는 쪽은 브라우저 자동화의 Playwright MCP와 브라우저 진단의 Chrome DevTools MCP로, 앞서 스모크 테스트 이야기에서 나온 도구입니다. 일하는 곳과 잇는 쪽은 GitHub, Figma, Sentry이고, 배포와 데이터는 Vercel과 Supabase입니다. 도구는 많이 붙일수록 좋은 것이 아니라 필요한 만큼만 붙이는 것이 좋습니다. 다음 장에서 개념 두 가지를 먼저 짚고, 이어서 도구를 하나씩 소개하겠습니다.
개념 먼저
코드를 아는 길은 언어 서버(LSP), 최신 API를 아는 길은 문서 조회다
에이전트 ‘이 함수 어디서 쓰여?’ 언어 서버 (LSP) 정의·참조·진단 내 코드 그 심볼과 참조만 에이전트 ‘이 API 최신 사용법?’ 문서 조회 서버 라이브러리·버전 검색 공식 문서·예제 필요한 부분만 LSP MCP
언어 서버 프로토콜(LSP) 2016년 마이크로소프트가 낸 편집기 ↔ 언어 분석기 표준 규약. 정의로 이동, 참조 찾기, 이름 바꾸기, 오류 진단을 언어마다 같은 방식으로 묻는다. 대표 도구 Serena . Claude Code도 2025-12-19(2.0.74)에 LSP 도구 를 넣었다(언어별 플러그인).
문서 조회 라이브러리 이름과 버전으로 공식 문서·예제 를 검색해 필요한 부분만 창에 넣는다. 모델 지식의 날짜 한계를 메운다. 대표 도구 Context7 . LSP가 아니라 문서 검색이다.
도구 이름보다 개념을 먼저 잡겠습니다. 에이전트가 코드를 이해하는 길은 두 가지입니다. 하나는 언어 서버 프로토콜, LSP입니다. 2016년 마이크로소프트가 VS Code와 함께 공개한 규약으로, 편집기가 언어별 분석기인 언어 서버에게 이 함수의 정의가 어디인지, 어디서 쓰이는지, 오류가 있는지를 같은 형식으로 묻습니다. 에이전트가 이것을 쓰면 문자열 검색 대신 심볼 단위로 정확히 찾고, 파일 전체를 읽지 않아 창을 아낍니다. 대표 도구가 Serena이고, Claude Code도 2025년 12월 19일 2.0.74 버전에서 LSP 도구를 넣어 언어별 플러그인으로 씁니다. 다른 하나는 문서 조회입니다. 모델의 지식은 날짜에서 멈춰 있으니, 라이브러리와 버전에 맞는 공식 문서를 찾아 필요한 부분만 넣어 줍니다. 대표 도구가 Context7입니다. 둘을 같은 종류로 묶어 말하면 안 됩니다. Context7은 LSP가 아니라 문서 검색입니다.
2025-03-29 첫 커밋
문서 조회의 대표 도구 Context7: 버전에 맞는 문서만 가져온다
context7.com
공식 사이트 화면 캡처
Context7 첫 화면 ‘AI 에이전트를 위한 최신 문서’. 15만 3천 개 넘는 라이브러리 문서를 검색해 Claude·Codex·Cursor에 넣어 준다.
언제: 최신 프레임워크 API(Application Programming Interface, 프로그램 연동 규약)가 헷갈릴 때. 버전에 맞는 문서·예제만 가져온다. 연결: 원격 mcp.context7.com, 프롬프트에 use context7.
비용·위험: 무료 API 키(호출 한도 상향용). 라이브러리 문서는 커뮤니티 등록이라 README가 정확성·안전을 보장하지 않는다 고 밝힌다.
모델 지식의 날짜 한계 를 문서 조회로 메운다. MCP 외에 CLI(Command-Line Interface, 명령줄 도구)·스킬 방식도 있어 토큰 면에서 비교해 볼 만하다.
모델의 지식에는 날짜가 있어서, 최근에 바뀐 라이브러리 API(Application Programming Interface, 프로그램 연동 규약)를 옛 버전 기준으로 알려 주기도 합니다. Context7은 라이브러리 이름과 질문을 주면 해당 버전의 공식 문서와 예제를 찾아 그 부분만 가져옵니다. 도구는 두 개입니다. 라이브러리 이름을 식별자로 바꾸는 도구와, 그 식별자로 문서를 질의하는 도구입니다. 프롬프트 끝에 use context7을 적으면 쓰도록 유도할 수 있습니다. README는 MCP 방식과 별도로 CLI(Command-Line Interface, 명령줄 도구)와 스킬 방식도 지원한다고 설명합니다. 저장소의 첫 커밋은 2025년 3월 29일입니다. 묶어 보면 장점은 버전에 맞는 문서를 가져온다는 것이고, 비용·위험은 무료 API 키와 문서 정확성 비보장입니다. 의미는 모델 지식의 날짜 한계를 메운다는 점입니다.
2025-03-23 첫 커밋
LSP의 대표 도구 Serena: 함수·클래스(심볼) 단위로 찾고 고친다
github.com/oraios/serena
GitHub 저장소 화면 캡처
Serena GitHub 저장소. 소개문은 ‘의미 기반 검색·편집을 주는 코딩용 MCP 도구, 에이전트를 위한 IDE’ (Integrated Development Environment, 통합 개발 환경). 별 3만 개 이상.
언제: 큰 코드베이스·리팩터링. 필요한 심볼만 읽어 창을 아낀다. 연결: MCP 서버, 언어 서버(LSP) 기반 40개 넘는 언어.
비용·위험: 오픈소스지만 GPL-3.0 이라 회사 프로젝트는 라이선스 확인이 필요하다.
LSP를 MCP로 감싼 형태. 지금은 에이전트 자체 LSP 도구 (Claude Code 2.0.74~)도 있어 둘 중 하나면 된다.
Serena는 코딩 에이전트에게 IDE(Integrated Development Environment, 통합 개발 환경) 같은 능력을 주는 MCP 서버입니다. README 설명으로는 줄 번호나 단순 문자열 검색 대신 심볼 단위의 의미 검색, 편집, 리팩터링 도구를 제공합니다. 내부에서는 언어 서버 프로토콜을 쓰며 40개가 넘는 언어를 지원합니다. 코드베이스가 크면 파일 전체를 읽는 것보다 필요한 함수와 그 참조만 찾는 쪽이 창을 아낍니다. 첫 커밋은 2025년 3월 23일입니다. 라이선스가 GPL이라 회사 프로젝트에 쓸 때는 확인이 필요합니다. 묶어 보면 장점은 필요한 심볼만 읽어 창을 아낀다는 것이고, 위험은 GPL 라이선스입니다. 의미는 창 절약 원칙을 코드 탐색에 적용했다는 점입니다.
2025-03-21 첫 커밋
브라우저 자동화의 대표 도구 Playwright MCP: 접근성 트리 스냅샷으로 조작
playwright.dev/docs/getting-started-mcp
공식 문서 화면 캡처 · 2026-10-28 확인
Playwright MCP 공식 문서 첫 화면. LLM(Large Language Model, 대규모 언어 모델)이 구조화된 접근성 스냅샷 으로 웹 페이지를 다루며 비전 모델이 필요 없다고 소개.
언제: 구현한 화면의 스모크 테스트. 스크린샷 대신 구조화된 스냅샷 이라 비전 모델이 필요 없다. 연결: npx 한 줄, 기본은 화면이 보이는 브라우저.
비용·위험: 도구 정의와 긴 스냅샷이 토큰을 먹어, README도 코딩 에이전트에는 CLI+스킬이 더 효율적 이라 안내한다.
조작은 Playwright, 진단은 다음 장 DevTools. 지속 상태가 필요한 탐색 엔 MCP, 단순 점검엔 CLI를 재서 고른다.
Playwright MCP는 Microsoft가 만든 브라우저 자동화 서버입니다. 화면을 이미지로 보는 것이 아니라 접근성 트리, 즉 요소와 역할과 텍스트를 구조화한 스냅샷으로 페이지를 읽고, 요소 참조 번호로 클릭하거나 입력합니다. 그래서 비전 모델이 필요 없다고 문서는 설명합니다. 저장소의 첫 커밋은 2025년 3월 21일입니다. 한 가지 주의할 점이 있습니다. 저장소 README는 코딩 에이전트에는 CLI와 스킬 조합이 도구 정의와 긴 스냅샷을 싣지 않아 토큰 효율이 더 낫다고 스스로 안내합니다. 지속적인 브라우저 상태가 필요한 탐색형 작업에는 MCP가 맞습니다. 묶어 보면 장점은 비전 모델 없이 브라우저를 다룬다는 것이고, 단점은 토큰이 많이 들어 CLI와 스킬 조합이 더 효율적일 수 있다는 것입니다. 의미는 직접 재서 고르라는 점입니다.
2025-09-23
브라우저 진단 도구 Chrome DevTools MCP: 콘솔과 성능까지 본다
developer.chrome.com/blog/chrome-devtools-mcp
Chrome 공식 블로그 화면 캡처 · 2026-10-28 확인
Chrome 개발자 블로그(2025-09-23). 코딩 에이전트는 자기 코드의 브라우저 동작을 못 봐 ‘눈가리개를 하고 코딩하는 셈’ 이라는 문제의식.
언제: 화면이 깨졌는데 원인을 모를 때. 콘솔 오류·네트워크·성능 트레이스를 본다. 연결: Chrome 팀의 MCP 서버(공개 프리뷰로 출발).
비용·위험: 사용 통계 수집이 기본 켜짐 (끄는 옵션 있음). 브라우저 내용이 MCP 클라이언트에 노출되니 민감 정보 주의.
Playwright가 조작 , 이쪽은 진단 . ‘눈가리개 코딩’에서 벗어나는 대신 노출 범위를 감안한다.
Chrome 팀이 2025년 9월 23일 공개 프리뷰로 낸 서버입니다. 발표 글의 문제의식은 코딩 에이전트가 자기가 만든 코드가 브라우저에서 실제로 어떻게 동작하는지 보지 못한다는 것입니다. 이 서버를 붙이면 에이전트가 콘솔 오류와 네트워크 요청을 읽고, 레이아웃을 점검하고, 성능 트레이스를 기록할 수 있습니다. Playwright MCP가 조작 쪽이라면 이쪽은 진단 쪽입니다. 저장소 README는 사용 통계 수집이 기본으로 켜져 있고 옵션으로 끌 수 있다고 안내하며, 브라우저 내용이 MCP 클라이언트에 노출되므로 민감한 정보를 주의하라고 경고합니다. 묶어 보면 장점은 콘솔과 성능까지 진단한다는 것이고, 위험은 통계 수집 기본값과 민감 정보 노출입니다. 의미는 Playwright가 조작이라면 이쪽은 진단이라는 점입니다.
2025-03-10 첫 커밋
GitHub MCP 서버: 이슈, PR, Actions를 에이전트가
docs.github.com · GitHub MCP 서버 설정
GitHub 공식 문서 화면 캡처 · 2026-10-28 확인
github/github-mcp-server 저장소 화면. 소개문은 ‘GitHub 공식 MCP 서버’ , 별 3만 4천 개, 최신 릴리스 2.0.3.
언제: 이슈·PR(Pull Request, 변경 병합 요청)·Actions를 에이전트가 읽고 쓸 때. 연결: 원격, 인증은 OAuth(Open Authorization, 개방형 인증)·PAT(Personal Access Token, 개인용 접근 토큰) 또는 Docker 로컬 서버, toolsets로 필요한 기능만 켠다.
비용·위험: 토큰은 필요한 권한만 (최소 스코프) 주고 쓰기를 막으려면 --read-only. 같은 일이 gh CLI 로도 된다.
14교시 이슈 원장 을 에이전트가 읽고 쓰는 길. MCP와 gh CLI 중 편한 쪽을 고른다.
GitHub가 직접 만든 MCP 서버입니다. 이슈와 풀 리퀘스트, 코드 검색, Actions 상태를 에이전트가 도구로 다룰 수 있습니다. GitHub가 호스팅하는 원격 서버가 가장 쉽고, 원격을 지원하지 않는 호스트에는 로컬 서버를 씁니다. README는 toolsets 옵션으로 필요한 기능 묶음만 켜면 모델의 도구 선택에 도움이 되고 컨텍스트 크기도 줄어든다고 설명합니다. 14교시에서 이슈 원장 이야기를 할 때, 에이전트가 이슈와 PR(Pull Request, 변경 병합 요청)을 읽고 쓰게 하는 길이 바로 이것입니다. 다만 gh CLI로도 같은 일이 되니 둘 중 편한 쪽을 고르면 됩니다. 묶어 보면 장점은 이슈와 PR을 도구로 다룬다는 것이고, 위험은 토큰 권한이며 gh CLI로도 같은 일이 된다는 점입니다. 의미는 이슈 원장을 에이전트가 읽고 쓰는 길이라는 것입니다.
공식 문서
Figma MCP: 디자인을 코드의 맥락으로
developers.figma.com/docs/figma-mcp-server
Figma 공식 문서 화면 캡처 · 2026-10-28 확인
Figma 개발자 문서의 MCP 서버 소개. Figma를 AI 작업에 연결해 디자인 맥락으로 코드를 생성 하고 캔버스에 직접 쓰는 기능도 소개.
언제: 디자인 시안을 화면으로 옮길 때. 변수·컴포넌트·레이아웃을 읽고 Code Connect로 내 컴포넌트를 재사용. 연결: 원격 mcp.figma.com/mcp(권장).
비용·위험: 캔버스 쓰기는 베타 이고 원격 서버와 유료 좌석 이 필요하다. 플랜 조건은 바뀔 수 있다.
디자인이 그림이 아니라 구조화된 맥락 으로 코드 생성에 들어온다. 실습 전 문서를 다시 확인.
Figma MCP 서버는 선택한 프레임의 변수, 컴포넌트, 레이아웃 정보를 에이전트에게 주어 코드를 만들게 합니다. Code Connect를 쓰면 생성 코드가 우리 코드베이스의 실제 컴포넌트를 재사용합니다. 공식 문서는 Figma가 호스팅하는 원격 서버를 권장하고, 데스크톱 앱을 통하는 서버는 조직 요구용으로 따로 둔다고 설명합니다. 캔버스에 쓰는 기능은 베타이고 쓰려면 원격 서버와 유료 좌석이 필요하다고 합니다. 플랜이나 좌석 조건은 바뀔 수 있으니 실습 전에 문서를 다시 확인해 두면 좋습니다. 묶어 보면 장점은 디자인 맥락으로 코드를 만든다는 것이고, 단점은 캔버스 쓰기가 베타이고 유료 좌석이 필요하다는 것입니다. 의미는 디자인이 구조화된 맥락으로 들어온다는 점입니다.
supabase-community 첫 커밋 2024-12-20
Supabase MCP: DB를 다루게 하되 가둔다
supabase.com/docs/guides/getting-started/mcp
Supabase 공식 문서 화면 캡처 · 2026-10-28 확인
Supabase MCP 문서. 위쪽에 ‘LLM 연결은 보안 위험이 있다’는 경고, 아래에 Read-only(읽기 전용) 토글과 기능 그룹 선택이 보인다.
언제: 스키마 변경과 개발 DB 점검. 테이블 조회·마이그레이션·SQL(Structured Query Language, 데이터베이스 질의 언어)·타입 생성. 연결: 원격 mcp.supabase.com/mcp.
비용·위험: 사용자 입력 속 프롬프트 주입 으로 위험한 쿼리가 실행될 수 있다고 문서가 경고. 개발자 권한이라 고객에게 주지 말 것.
가장 좋은 보안 설정 예시 : read_only=true, project_ref로 한 프로젝트 한정, 승인은 켜 둔다.
Supabase MCP는 테이블 목록, 마이그레이션 적용, SQL(Structured Query Language, 데이터베이스 질의 언어) 실행, 로그 조회, 타입 생성 같은 일을 에이전트가 하게 합니다. 이 도구는 보안 설정 이야기를 하기에 가장 좋은 예입니다. 공식 문서는 LLM(Large Language Model, 대규모 언어 모델) 고유의 공격 경로로 프롬프트 주입을 꼽고, 지원 티켓 같은 사용자 입력 안의 명령이 위험한 쿼리를 실행시킬 수 있다고 경고합니다. 권장 설정은 읽기 전용 모드, 한 프로젝트로 한정하는 project_ref, 필요한 기능 그룹만 여는 features입니다. 개발자 권한으로 돌아가므로 고객에게 주지 말라는 말도 있습니다. 도구 승인은 켜 두는 편이 안전합니다. 묶어 보면 장점은 DB(데이터베이스) 작업을 맡길 수 있다는 것이고, 위험은 프롬프트 주입과 개발자 권한입니다. 의미는 읽기 전용과 프로젝트 한정으로 가두는 보안 설정의 좋은 예라는 점입니다.
getsentry/sentry-mcp 첫 커밋 2025-03-29
Sentry MCP: 운영 오류를 에이전트가 읽는다
mcp.sentry.dev
Sentry 공식 문서 화면 캡처 · 2026-10-28 확인
Sentry(오류 수집 서비스) MCP 소개 화면(베타). Sentry 데이터를 LLM에 연결해 운영 오류 디버깅 을 돕고, 왼쪽은 이슈 주소를 붙여 고치는 시연.
언제: 운영 오류를 고칠 때. 스택 트레이스를 읽고 원인 코드·수정 PR까지. 연결: 원격 mcp.sentry.dev/mcp, OAuth.
비용·위험: 소개 화면에 베타 표기. 오류 안의 사용자 입력 문자열이 프롬프트 주입 경로 가 될 수 있어 조직·프로젝트로 범위를 좁힌다.
오류 메시지를 복사해 붙이던 일 을 에이전트가 직접 조회하는 흐름으로 바꾼다.
Sentry에 쌓인 오류를 에이전트가 직접 찾아 읽게 하는 서버입니다. 문서에 따르면 오류 검색, 성능 분석, 이슈 분류, 문서 읽기, 프로젝트 관리를 지원합니다. 연결은 OAuth(Open Authorization, 개방형 인증)이고, 주소 끝에 조직과 프로젝트 이름을 붙이면 그 범위로 도구가 한정됩니다. 문서는 가능하면 프로젝트까지 한정하라고 권합니다. 오류 메시지를 복사해 붙이던 일을 에이전트가 스택 트레이스를 읽고 코드에서 원인을 찾는 흐름으로 바꿉니다. 운영 오류 안에는 사용자가 입력한 문자열이 들어 있으니, 앞에서 본 프롬프트 주입 관점으로 도구 승인을 켜 두는 편이 안전합니다. 묶어 보면 장점은 스택 트레이스에서 원인 코드까지 이어진다는 것이고, 위험은 베타 표기와 사용자 입력 문자열입니다. 의미는 복사해 붙이던 일이 직접 조회로 바뀐다는 점입니다.
공식 문서 · 2026-09-15 갱신본
Vercel MCP: 배포 상태와 로그를 묻는다
vercel.com/docs/agent-resources/vercel-mcp
Vercel 공식 문서 화면 캡처 · 2026-10-28 확인
Vercel(웹 배포 서비스) 문서 ‘Vercel MCP 서버 쓰기’. 문서 검색, 프로젝트·배포 관리, 로그 분석이 가능한 공식 원격 서버(OAuth) .
언제: 배포 실패 원인을 찾을 때. 문서 검색·프로젝트·배포 관리·로그 분석. 연결: 원격 mcp.vercel.com, OAuth.
비용·위험: 연결하면 내 계정과 같은 권한 을 AI가 갖는다. Vercel이 승인한 클라이언트만 연결되고 사람 확인을 켜 둔다.
승인 클라이언트 제한은 보안의 좋은 예. 9교시 자동 승인과 달리 MCP 도구는 사람 확인을 유지 한다.
Vercel MCP는 Vercel이 호스팅하는 공식 원격 서버입니다. 문서 검색, 프로젝트와 배포 관리, 배포 로그 분석, 웹 분석 조회를 지원합니다. 보안 쪽이 인상적입니다. Vercel이 검토해 승인한 클라이언트만 연결할 수 있고, 클라이언트마다 사용자가 명시적으로 동의해야 합니다. 문서는 연결하는 순간 AI가 내 계정과 같은 권한을 갖는다고 분명히 적고, 신뢰할 수 없는 도구가 있으면 로그를 외부로 빼돌리는 명령도 가능하다고 경고합니다. 항상 사람 확인을 켜 두라는 권고는 이 교시 내내 반복되는 이야기입니다. 묶어 보면 장점은 배포 상태와 로그를 바로 묻는다는 것이고, 위험은 내 계정과 같은 권한을 준다는 것입니다. 의미는 승인된 클라이언트만 연결되는 보안 모범 사례라는 점입니다.
2026-01-22 첫 커밋
셸 출력 압축의 대표 도구 rtk: 명령 출력을 줄여서 에이전트에게 준다
www.rtk-ai.app
공식 사이트 화면 캡처 · 2026-10-28 확인
rtk 공식 사이트 첫 화면. 문구는 ‘AI 에이전트가 잡음에 빠져 있다. RTK가 정리해 준다’ . GitHub 별 8만 4천 개.
$ git status
✓ 훅이 rtk git status 로 바꿔 실행
테스트는 실패만 , git log는 요약만 남겨 셸 출력의 잡음을 줄인다.
훅이 Bash 호출에만 걸려 Read·Grep은 지나가지 않는다. 줄어든 출력이 곧 줄어든 청구서는 아니다.
MCP가 아닌 CLI 프록시. 효과는 내 작업에서 직접 재서 확인한다.
셸 출력을 압축해 주는 도구의 대표가 rtk입니다. MCP 서버가 아니라 CLI 프록시입니다. 훅으로 에이전트가 부르는 셸 명령을 가로채서, 출력의 잡음을 지우고 비슷한 항목을 묶고 길이를 자른 뒤 에이전트에게 돌려줍니다. 예를 들어 테스트는 실패한 것만, git log는 해시와 제목만 보여 줍니다. 첫 커밋은 2026년 1월 22일입니다. README는 정직한 단서를 붙입니다. 줄어드는 것은 셸 출력일 뿐이고, 입력 토큰의 일부이며 청구서의 일부이므로 같은 비율로 비용이 줄지는 않는다는 것입니다. 또 훅은 Bash 도구 호출에만 걸려서, 내장 Read와 Grep 도구는 지나가지 않는다고 합니다. 효과는 직접 재 보면 됩니다. 묶어 보면 장점은 셸 출력의 잡음을 줄인다는 것이고, 단점은 Bash 호출에만 적용되고 청구서가 같은 비율로 줄지 않는다는 것입니다. 의미는 효과를 직접 재서 확인하라는 점입니다.
2016-02-27 첫 커밋
정규식 재귀 검색 도구 ripgrep: 검색 결과를 걸러 주는 grep
code.claude.com/docs/en/troubleshooting
Claude Code 공식 문서 화면 캡처 · 2026-10-28 확인
Claude Code 문제 해결 문서. 오른쪽 목차의 ‘Search and discovery issues(검색 문제)’ 절에 ripgrep 안내가 있다.
.gitignore를 따르고 숨김·바이너리를 건너뛰어, node_modules 같은 잡음이 창에 못 들어온다 .
Claude Code는 내장 ripgrep을 쓰지만, 시스템에서 안 돌면 별도 ripgrep 이 필요하다.
검색 결과가 걸러질수록 창에 들어오는 양도 준다 . 가장 기본적인 토큰 절약.
$ rg "TODO" src/
ripgrep, rg는 정규식으로 디렉터리를 재귀 검색하는 도구입니다. README에 따르면 기본으로 gitignore 규칙을 따르고 숨김 파일과 바이너리 파일은 건너뜁니다. 에이전트에게 중요한 이유는 의미 없는 결과, 즉 node_modules나 빌드 산출물이 섞여 들어와 창을 낭비하는 것을 자연스럽게 막기 때문입니다. Claude Code 공식 문서는 검색과 파일 탐색에 내장 ripgrep을 쓰고, 이 바이너리가 시스템에서 안 돌면 시스템용 ripgrep을 따로 쓰라고 안내합니다. 설치는 각자 하시면 됩니다. 다른 도구가 grep을 rg로 바꿨는지는 1차 출처를 찾지 못해 말하지 않겠습니다. 묶어 보면 장점은 잡음 파일을 걸러 창을 아낀다는 것이고, 단점은 내장 바이너리가 안 돌면 별도 ripgrep이 필요하다는 것입니다. 의미는 검색 단계에서 이미 토큰 절약이 시작된다는 점입니다.
정리 · 토큰 절약
창에 들어오는 것을 줄인다
창에 들어가는 것 줄이는 방법 남는 것 CLI 출력 검색 결과 MCP 도구 정의 라이브러리 문서 셸 출력 압축 · rtk 출력을 압축해서 전달 재귀 검색 · ripgrep 빠르고 필터된 검색 도구 검색 쓸 때만 정의 로드 문서 조회 · 심볼 탐색 (Context7 · Serena) 필요한 부분만 가져옴 일에 쓸 창 더 긴 세션
도구는 필요한 만큼만 . 서버 수, 도구 수, 출력 길이를 직접 재고 줄이는 것이 순서입니다.
오늘 본 것을 창에 들어오는 것 기준으로 다시 묶으면 네 갈래입니다. 셸 출력은 압축 도구 rtk가 줄이고, 검색 결과는 ripgrep이 걸러 줍니다. MCP 도구 정의는 도구 검색이 필요할 때만 싣고, 문서는 문서 조회(Context7)가, 코드는 심볼 탐색(Serena)이 필요한 부분만 가져옵니다. 한 가지 더 짚을 점이 있습니다. Playwright와 Context7 모두 MCP 말고 CLI와 스킬 방식도 내놓고 있고, 토큰 효율이 이유로 거론됩니다. 정답은 도구마다 다르니, 내 작업에서 직접 재 보고 정하는 편이 맞습니다.
정리
하네스는 장치의 총합, MCP는 그중 연결
anthropic.com/engineering/effective-harnesses-for-long-running-agents
Anthropic Engineering · 2025-11-26
다시 보는 화면: Anthropic 장기 실행 하네스 글(2025-11-26).
하네스 = 모델을 둘러싼 장치 전부. 파일과 git으로 세션을 잇는다
MCP = 호스트·클라이언트·서버. 연결하면 권한도 준다
도구는 필요한 만큼. 정의·출력·검색을 줄인다
→ 11교시: 스킬, Superpowers에서 Ponytail까지
오늘 본 것을 묶으면, 하네스는 모델을 둘러싼 장치의 총합이고, 장기 작업에서는 파일과 git이 세션 사이를 잇습니다. MCP는 에이전트를 바깥 세계와 잇는 표준이고, 연결하는 순간 그 서버에 내 권한의 일부를 준다는 점을 함께 짚어 둡니다. 도구는 필요한 만큼만 붙이고, 정의와 출력과 검색 결과를 줄이는 방법을 함께 씁니다. 다음 11교시에서는 하네스의 또 다른 구성요소인 스킬을 봅니다. 스킬은 필요할 때만 읽히는 지침 폴더이고, 도구 검색과 비슷한 점진적 공개 원리로 움직입니다.
3회차 · 11교시
스킬:
반복해서 설명하던 작업 방식을 폴더 하나로 묶고, 에이전트가 필요할 때만 꺼내 쓰게 하는 방법을 봅니다.
2025-10-16 Agent Skills 2025-10-09 Superpowers 공식 skill-creator 2026-06-12 Ponytail
오늘은 스킬을 봅니다. 앞 교시에서 에이전트를 오래 돌리는 장치를 쌓았다면, 이번에는 그 위에서 반복하는 작업 방식을 포장하는 문제입니다. 아래 네 장은 모두 실제 화면입니다. Anthropic의 Agent Skills 발표 글, Superpowers를 소개한 블로그, 공식 skill-creator의 SKILL.md 원문, Ponytail의 사다리 그림입니다. 구조를 먼저 본 뒤 자주 쓰는 스킬을 하나씩 보고, 마지막에 제 스킬 지도와 직접 만드는 방법까지 갑니다.
문제 제기
CLAUDE.md는 늘 읽히고, 스킬 본문은 쓸 때만 읽힌다
code.claude.com/docs/en/skills
공식 문서 화면 캡처 · 2026-10-28 확인
Claude Code 공식 문서의 스킬 설명 페이지. 눈여겨볼 문장은 스킬 본문은 쓸 때만 불러온다 는 것으로, 늘 읽히는 CLAUDE.md와 대비된다.
“A skill’s body loads only when it’s used.”스킬의 본문은 사용될 때에만 불러옵니다. Claude Code Docs · Extend Claude with skills
CLAUDE.md(프로젝트 상시 지침 파일)는 매 세션 항상 읽힌다. 절차가 길수록 낭비
스킬은 이름과 설명만 올려 두고, 본문은 쓸 때만
같은 지침을 세 번 붙여 넣었다면 스킬 후보
하네스를 키우다 보면 CLAUDE.md가 점점 길어집니다. 규칙은 사실이 아니라 절차가 되고, 그 절차는 모든 세션의 컨텍스트 창을 차지합니다. 공식 문서가 권하는 기준은 단순합니다. 같은 지침이나 체크리스트를 대화에 계속 붙여 넣고 있다면 스킬로 만들라는 것입니다. 스킬은 본문이 사용될 때만 불러와지므로, 참고 자료가 길어도 필요하기 전까지는 비용이 거의 들지 않습니다. 오늘 내용을 한 줄로 줄이면 이 문장입니다.
스킬의 구조
스킬은 SKILL.md가 든 폴더 하나다
agentskills.io
오픈 표준 문서 화면 캡처 · 2026-10-28 확인
Agent Skills 오픈 표준의 개요 화면. 스킬이 SKILL.md가 든 폴더 이고 스크립트·참고 문서·템플릿을 함께 둔다는 구조를 보여 준다.
SKILL.md 필수: 메타데이터와 지침scripts/ 실행 코드, references/ 참고 문서, assets/ 템플릿코드도 문서도 폴더에 같이 든다. 복사하면 곧 배포
스킬의 정의는 짧습니다. SKILL.md 파일이 들어 있는 폴더입니다. 이 파일에 이름과 설명, 그리고 에이전트가 따라 할 지침이 들어갑니다. 필요하면 스크립트, 참고 문서, 템플릿을 같은 폴더에 둡니다. 그래서 스킬은 복사해서 옮기거나 저장소에 올려 팀과 나눌 수 있습니다. 화면은 오픈 표준을 정리한 Agent Skills 개요 페이지입니다.
SKILL.md
SKILL.md: 위는 이름표, 아래는 지침
raw.githubusercontent.com/anthropics/skills/main/skills/frontend-design/SKILL.md
저장소 원문 화면 캡처 · 2026-10-28 확인
Anthropic 공식 frontend-design 스킬의 SKILL.md 원문. 맨 위가 이름·설명 블록 , 그 아래가 에이전트가 따를 지침이다.
name : 스킬 이름. 폴더 이름과 같은 영소문자·숫자·하이픈description : 무엇을 하고 언제 쓰는지본문 : 단계, 예시, 주의점
name은 64자, description은 1,024자까지 쓸 수 있습니다. 필수는 이 두 필드뿐입니다.
실제 SKILL.md를 보겠습니다. 위쪽 세 줄은 YAML(YAML Ain't Markup Language, 설정 기록용 서식) frontmatter이고 이름, 설명, 라이선스가 있습니다. 아래부터가 본문 지침입니다. 명세에서 필수인 것은 name과 description 두 개뿐입니다. name은 폴더 이름과 같아야 하고, description은 1,024자까지 쓸 수 있습니다. 나머지는 모두 선택입니다. 이 구조 하나만 알면 오늘 소개할 스킬을 전부 읽을 수 있습니다.
2025-10-16
스킬은 필요한 만큼만 읽혀 컨텍스트를 아낀다
1단계 · 시작할 때 2단계 · 스킬을 고른 뒤 3단계 · 필요할 때만 name + description 스킬당 약 100토큰 모든 스킬이 항상 목록에 있음 SKILL.md 본문 5,000토큰 안팎 권장 지침 전체가 대화에 들어옴 scripts · references 크기 제한 없음 읽거나 실행한 만큼만 컨텍스트에 쓰임 맞으면 가리키면
Claude Code에서는 설명은 1,536자 까지만 목록에 오르고(넘으면 잘림), 대화가 압축된 뒤에는 스킬당 앞 5,000토큰 만 다시 붙습니다.
스킬의 핵심 설계 원리는 점진적 공개입니다. Anthropic의 엔지니어링 글은 이것을 스킬이 유연하고 확장 가능한 이유라고 설명합니다. 시작할 때는 모든 스킬의 이름과 설명만 올라갑니다. 설명이 작업과 맞으면 SKILL.md 본문을 읽고, 본문이 가리키는 스크립트나 참고 문서는 필요한 순간에만 읽습니다. 그래서 스킬을 수십 개 설치해도 컨텍스트 창이 부담을 받지 않습니다. Claude Code 문서에는 설명 목록 1,536자 상한과, 자동 압축 뒤 스킬당 앞 5,000토큰, 전체 25,000토큰 예산이 적혀 있습니다. 본문은 500줄 안으로 유지하라는 권고도 같이 봐 두면 좋습니다.
명세 · Claude Code 문서
스킬은 세 곳에 두고, 사람도 Claude도 부를 수 있다
agentskills.io/specification
오픈 표준 명세 화면 캡처 · 2026-10-28 확인
Agent Skills 명세의 점진적 공개 절. 메타데이터 약 100토큰, 본문 5,000토큰 미만, 500줄 이내 를 권장한다.
~/.claude/skills/<이름>/SKILL.md 개인
.claude/skills/<이름>/SKILL.md 프로젝트
<플러그인>/skills/<이름>/SKILL.md /플러그인:이름
✓ Claude가 설명을 보고 부르거나
✓ 사람이 /이름 으로 직접 호출
! disable-model-invocation: true
→ 사람만 호출 (배포처럼 부작용 있는 절차)
왼쪽은 명세의 점진적 공개 절입니다. 메타데이터는 약 100토큰, SKILL.md 본문은 5,000토큰 미만을 권장하고 500줄 안으로 유지하며, 나머지는 별도 파일로 뺍니다. 오른쪽은 Claude Code가 스킬을 찾는 위치입니다. 개인 폴더, 프로젝트 폴더, 플러그인 안의 폴더이고, 충돌하면 기업 설정이 개인보다, 개인이 프로젝트보다 우선합니다. 스킬은 두 방식으로 불립니다. 설명을 보고 Claude가 알아서 부르거나 슬래시와 이름으로 사람이 부릅니다. frontmatter의 disable-model-invocation을 true로 두면 사람이 부를 때만 실행되며, 뒤에 나올 grill-me가 이 설정입니다. 예전 .claude/commands의 커스텀 명령도 스킬로 합쳐졌다고 문서에 나옵니다.
2025-10-16 · 2025-12-18
스킬은 Claude 기능에서 여러 에이전트가 읽는 표준이 됐다
claude.com/blog/skills
2025-10-16 · Agent Skills 발표
2025-10-16 발표 글 “Introducing Agent Skills”. Claude 앱·Claude Code·API(Application Programming Interface, 프로그램 연동 규약)에서 쓰는 Agent Skills 를 소개한다.
anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
2025-12-18 · “오픈 표준으로 공개” 업데이트
2025-12-18 업데이트. Agent Skills를 오픈 표준 으로 공개했다는 내용이다.
스킬은 Claude 앱·Claude Code·API에서 쓰고, 표준이 된 뒤에는 다른 에이전트도 같은 폴더 를 읽습니다.
Anthropic은 2025년 10월 16일에 Agent Skills를 발표했습니다. Claude 앱, Claude Code, API(Application Programming Interface, 프로그램 연동 규약)에서 쓸 수 있고, 스킬이 서로 쌓여서 함께 쓰인다는 점을 강조했습니다. 두 달 뒤인 12월 18일에 같은 글에 업데이트가 붙었습니다. 조직 단위 관리, 파트너 스킬 디렉터리, 그리고 Agent Skills를 교차 플랫폼 이식을 위한 오픈 표준으로 공개했다는 내용입니다. 오른쪽 화면이 그 업데이트입니다. 그래서 오늘 쓰는 스킬은 Claude Code뿐 아니라 표준을 지원하는 다른 에이전트에서도 같은 형식으로 읽힙니다.
2025-10-09
플러그인은 스킬·명령·훅을 한 묶음으로 나눠 준다
raw.githubusercontent.com/anthropics/skills/main/README.md
저장소 README 화면 캡처 · 2026-10-28 확인
Anthropic 공식 skills 저장소 README의 첫머리. 스킬을 지침·스크립트·자료가 든 폴더 로 정의하고, 이 저장소가 예제 모음임을 밝힌다.
# 공식 저장소의 두 묶음
document-skills 문서(docx·pdf·pptx·xlsx)
example-skills 만들기·화면·테스트 예제
✓ 마켓플레이스 = 플러그인 목록을 가진 저장소
✓ 플러그인 = 명령·서브에이전트·MCP(Model Context Protocol, 모델 컨텍스트 프로토콜)·훅·스킬 묶음
! 남이 만든 스킬은 지침이자 코드. 먼저 읽는다
스킬 하나하나를 폴더로 복사하는 대신, 플러그인으로 묶어 설치할 수 있습니다. Claude Code 플러그인은 2025년 10월 9일에 공개 베타로 나왔고, 슬래시 명령, 서브에이전트, MCP(Model Context Protocol, 모델 컨텍스트 프로토콜) 서버, 훅을 한 묶음으로 공유합니다. 마켓플레이스는 플러그인 목록을 가진 저장소입니다. 설치 방법은 각자 쓰는 도구 문서대로 하면 됩니다. 화면은 Anthropic 공식 스킬 저장소의 안내이며, document-skills와 example-skills 두 묶음이 있습니다. 한 가지 주의할 점이 있습니다. 스킬은 에이전트가 따르는 지침이고 스크립트까지 들어 있으므로, 출처를 모르는 스킬은 쓰기 전에 읽어 보는 편이 안전합니다.
2025-10-09
개발 방법론 전체를 스킬 묶음으로: 대표 사례 Superpowers(스킬 15개)
blog.fsck.com/2025/10/09/superpowers
제작자 블로그 화면 캡처 · 2025-10-09
Jesse Vincent의 2025-10-09 글 “Superpowers”. 지난 몇 주간 자기 작업 방식을 도구 묶음으로 체계화 했다고 소개한다.
설계부터 리뷰까지 스킬 15개 가 한 흐름으로 이어지고, Claude Code뿐 아니라 Codex·Cursor·Gemini CLI(Command-Line Interface, 명령줄 도구)에서도 쓴다.
모든 일에 전 과정을 강제하면 작은 수정에는 무겁다 . 그래서 필요한 스킬만 골라 쓴다(23장).
개별 지침이 아니라 방법론 전체를 폴더로 포장 한 첫 완성형. 1교시의 SDD(Spec-Driven Development, 스펙 주도 개발)·TDD(Test-Driven Development, 테스트 주도 개발)를 한 흐름으로 묶었다.
Superpowers는 개별 지침이 아니라 개발 방법론 전체를 스킬로 포장한 첫 완성형입니다. 제작자 Jesse Vincent의 글은 2025년 10월 9일자이고, 글 안에서 바로 그날 아침 Anthropic이 플러그인 시스템을 공개했다고 언급합니다. Agent Skills 발표보다 일주일 앞섰다는 점은 기억해 둘 만합니다. 저장소 README는 스킬 15개를 협업, 테스트, 디버깅, 메타 범주로 나눠 소개하고, Claude Code뿐 아니라 Codex, Cursor, Gemini CLI(Command-Line Interface, 명령줄 도구) 등 여러 에이전트에서 쓰는 법을 안내합니다. 이 방법론 자체는 1교시에서 본 SDD(Spec-Driven Development, 스펙 주도 개발)와 TDD(Test-Driven Development, 테스트 주도 개발)를 하나의 흐름으로 묶은 것입니다. 장점은 설계부터 리뷰까지 한 흐름으로 이어진다는 점입니다. 단점은 모든 일에 전 과정을 강제하면 작은 수정에는 무겁다는 점이라 필요한 스킬만 골라 씁니다. 의미는 방법론 전체를 폴더로 옮길 수 있다는 것입니다.
Superpowers 기본 워크플로
Superpowers는 설계를 승인받은 뒤 Task마다 새 에이전트가 구현한다
test-driven- development 실패 테스트 먼저 brainstorming 질문으로 설계 확정 using-git-worktrees 격리된 작업 공간 writing-plans 2~5분짜리 Task로 쪼갬 subagent-driven- development Task마다 새 에이전트 finishing-a- development-branch 머지·PR·정리 requesting- code-review Task마다 리뷰 구현마다
사람은 설계를 승인 하고, 구현은 Task마다 새 서브에이전트가 테스트 먼저로 진행합니다.
Superpowers의 기본 순서입니다. 먼저 brainstorming 스킬이 구현 전에 질문으로 설계를 확정합니다. 승인되면 using-git-worktrees로 격리된 작업 공간을 만들고, writing-plans가 일을 2분에서 5분짜리 Task로 쪼갭니다. 그 뒤 subagent-driven-development가 Task마다 새 서브에이전트를 띄워 구현하고, 구현마다 test-driven-development가 실패하는 테스트를 먼저 요구하며, 중간 리뷰를 거쳐, 마지막에 머지나 PR(Pull Request, 변경 병합 요청)로 마무리합니다. 사람의 판단은 앞쪽 설계 승인에 몰려 있다는 점이 눈에 띕니다.
Superpowers · brainstorming
brainstorming은 만들기 전에 설계를 묻고 승인받게 한다
raw.githubusercontent.com/obra/superpowers/main/skills/brainstorming/SKILL.md
저장소 원문 화면 캡처 · 2026-10-28 확인
brainstorming 스킬의 SKILL.md 원문. 구현 전에 코드와 맥락을 먼저 읽고 읽어서 알 수 없는 빈틈만 질문하라고 한다.
“Never ask what the project or their context already answers.”프로젝트나 맥락이 이미 답해 주는 것은 묻지 마라. obra/superpowers · brainstorming/SKILL.md
읽어서 알 수 있는 건 묻지 않고 접근법을 사람이 고르게 해, 방향이 어긋나기 전에 잡는다.
설계 승인이 끝나야 계획으로 넘어가 시작이 느리다 . “MUST use” 같은 강한 설명이라 사소한 일에도 불릴 수 있다.
강사 운영 방식의 SDD 앞단 과 같은 역할. 만들기 전에 사람이 결정하게 한다.
description이 “You MUST use this before any creative work”로 시작합니다. 새 기능이나 동작 변경을 하기 전에는 이 스킬을 먼저 부르라는 강한 문장이고, 이런 문장이 호출을 좌우합니다. 본문은 에이전트가 사용자가 원하는 것을 생각보다 얇게 안다고 가정합니다. 그래서 코드와 맥락을 먼저 읽고, 읽어서 알 수 있는 것은 묻지 않고, 중요한 빈틈만 질문합니다. 접근법을 별도 메시지로 펼쳐 사람이 고르게 하고, 설계 문서의 승인을 받은 뒤에야 계획 단계로 넘어갑니다. 제 운영 방식의 SDD 앞단과 같은 역할입니다. 장점은 읽어서 알 수 있는 것을 묻지 않고 방향을 사람이 고르게 한다는 점입니다. 단점은 설계 승인이 끝나야 넘어가서 시작이 느리다는 점입니다. 의미는 만들기 전에 결정하는 단계를 스킬이 맡는다는 것입니다.
Superpowers
계획은 잘게 쪼개고, 실행은 Task마다 새 에이전트가 한다
obra/superpowers · skills/writing-plans/SKILL.md
writing-plans · 저장소 원문 화면 캡처
writing-plans 원문. 스펙을 보고 잘게 쪼갠 Task 계획 을 쓰는 절차(README는 Task당 2~5분).
obra/superpowers · skills/subagent-driven-development/SKILL.md
subagent-driven-development · 저장소 원문 화면 캡처
subagent-driven-development 원문. Task마다 새 서브에이전트 가 구현하고 리뷰받는 절차.
Task마다 새 서브에이전트 가 구현해 메인 맥락이 오염되지 않고, 스펙 준수와 코드 품질을 Task마다 리뷰한다.
Task와 리뷰마다 에이전트를 부르므로 호출 수가 늘어난다 . 계획이 부실하면 쪼갠 Task도 어긋난다.
7교시 서브에이전트의 맥락 분리 가 방법론 안에 들어온 모습. → 7교시 서브에이전트
writing-plans는 스펙을 받아 아주 작은 Task로 나눕니다. README에 따르면 각 Task는 2분에서 5분 분량이고 정확한 파일 경로와 검증 단계를 담습니다. 실행은 subagent-driven-development가 맡습니다. Task 하나마다 새 서브에이전트에게 필요한 맥락만 만들어 주고, 구현이 끝나면 스펙 준수와 코드 품질을 리뷰하며, 마지막에 브랜치 전체를 한 번 더 봅니다. 서브에이전트가 메인 세션의 이력을 물려받지 않으므로 컨텍스트가 오염되지 않고, 메인은 조율에 쓰입니다. 7교시에서 본 서브에이전트의 맥락 분리가 방법론 안에 들어와 있습니다. 장점은 Task마다 새 에이전트라 맥락이 깨끗하다는 점입니다. 단점은 Task와 리뷰마다 에이전트를 부르니 호출 수가 늘어난다는 점입니다. 의미는 7교시의 맥락 분리가 방법론 안에 들어와 있다는 것입니다.
Superpowers · test-driven-development
TDD(테스트 먼저 쓰기) 스킬은 어긴 코드를 지우고 다시 쓰게 한다
raw.githubusercontent.com/obra/superpowers/main/skills/test-driven-development/SKILL.md
저장소 원문 화면 캡처 · 2026-10-28 확인
test-driven-development 스킬 원문. 첫머리가 테스트 먼저, 실패 확인, 최소 코드 순서를 못 박는다. 아래 인용은 ‘철칙’ 절.
“NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST”실패하는 테스트가 먼저 없으면 프로덕션 코드도 없다. test-driven-development/SKILL.md · The Iron Law
실패하는 테스트를 직접 봐야 그 테스트를 믿게 되고, “이번만 건너뛰자”는 합리화를 막는다.
테스트보다 먼저 쓴 코드는 참고용으로도 못 남기고 지운다. 규칙이 엄격해 빠른 시도에는 걸림돌이다.
6교시 TDD 강제가 스킬로 상시 규칙 이 된 예. → 6교시 TDD 강제
6교시에서 본 TDD 강제가 그대로 스킬이 됐습니다. 본문 첫 줄이 테스트를 먼저 쓰고, 실패하는 것을 확인하고, 통과할 최소 코드를 쓰라는 것입니다. 철칙이라는 이름의 절에는 실패하는 테스트 없이는 프로덕션 코드를 쓰지 않는다고 적혀 있고, 테스트 전에 코드를 썼다면 지우고 다시 시작하라고 합니다. 참고용으로 남겨 두는 것도 허용하지 않습니다. 에이전트가 이럴 때는 이번만 건너뛰자고 합리화하기 쉽기 때문에, 그 합리화를 막는 문장이 스킬 안에 들어 있습니다. 스킬이 하네스의 규칙이 되는 좋은 예입니다. 장점은 합리화를 막는 문장이 스킬 안에 들어 있다는 점입니다. 단점은 규칙이 엄격해서 빠른 시도에는 걸림돌이라는 점입니다. 의미는 6교시의 TDD 강제가 스킬로 상시 규칙이 된다는 것입니다.
Anthropic 공식 스킬
skill-creator는 스킬을 쓰고 시험하고 고치는 일을 돕는다
raw.githubusercontent.com/anthropics/skills/main/skills/skill-creator/SKILL.md
저장소 원문 화면 캡처 · 2026-10-28 확인
공식 skill-creator 스킬 원문. 스킬을 쓰고, 시험 프롬프트로 돌려 보고, 평가해 고치는 진행 순서가 담겨 있다.
초안, 시험 프롬프트, 평가, 수정의 반복 순서 를 안내하고 description 최적화 스크립트까지 있다. 초안이 있으면 평가부터 시작한다.
시험 프롬프트를 돌리고 평가하는 수고가 든다 . 번거로우면 가볍게 해 보자는 요청도 받아 준다.
스킬은 한 번에 완성하지 않고 시험하며 고친다 . 12교시 실습에서 직접 쓴다.
가장 먼저 써 볼 만한 공식 스킬입니다. 스킬을 새로 만들고, 기존 스킬을 고치고, 성능을 측정하는 일을 돕습니다. 본문의 진행 방식은 이렇습니다. 하고 싶은 일을 정하고, 초안을 쓰고, 시험 프롬프트를 몇 개 만들어 스킬을 붙인 에이전트로 실행하고, 결과를 정성과 정량으로 평가하고, 고쳐서 반복합니다. 마지막에는 호출 정확도를 높이도록 description을 최적화하는 별도 스크립트도 있습니다. 사용자가 이미 초안이 있다면 평가 단계부터 들어가도 되고, 평가가 번거로우면 같이 분위기로 해 보자는 요청도 받아 줍니다. 12교시 실습에서 이 스킬을 직접 써 봅니다. 장점은 쓰고 시험하고 고치는 순서가 갖춰져 있다는 점입니다. 단점은 시험과 평가에 수고가 든다는 점입니다. 의미는 스킬을 시험하며 고친다는 것입니다.
질문 시간 · 약 5분
여기까지,
지금까지 다룬 것: 발표와 오픈 표준 · 플러그인과 마켓플레이스 · Superpowers · Superpowers 흐름 · brainstorming · 계획과 서브에이전트 실행 · TDD 강제 · skill-creator
여기서 잠시 멈추고 질문을 받겠습니다. 지금까지 본 내용 가운데 이해가 안 된 곳, 자기 도구에서는 어떻게 되는지 궁금한 곳, 동의하지 않는 곳 무엇이든 좋습니다. 질문이 바로 나오지 않으면 화면 아래의 화면들 가운데 다시 보고 싶은 장을 말해 달라고 합니다.
Anthropic 공식 스킬
frontend-design은 뻔한 화면을 피하라고 지침으로 눌러 둔다
raw.githubusercontent.com/anthropics/skills/main/skills/frontend-design/SKILL.md
저장소 원문 화면 캡처 · 2026-10-28 확인
공식 frontend-design 스킬 원문. 미적 방향·타이포그래피 를 주제에 맞춰 고르고 템플릿 같은 기본값은 피하라고 한다.
팔레트·타이포·레이아웃을 주제에 맞춰 고르게 해 템플릿 같은 뻔한 화면을 피한다.
본문이 거의 지침 문장뿐 이라 결과는 여전히 모델의 판단에 달렸다. 주제가 없으면 먼저 정해 확인받는다.
구조를 읽기에 가장 단순한 스킬 . 모델의 ‘평균적인 화면’ 버릇을 지침으로 눌러 둔다.
화면을 만들게 하면 에이전트는 무난하지만 어디서 본 듯한 디자인을 내놓는 경향이 있습니다. frontend-design은 그 평균값을 피하라는 지침입니다. 설명에 나오듯 미적 방향, 타이포그래피, 템플릿 같은 기본값을 피하는 선택을 돕습니다. 본문은 디자인 스튜디오의 리드가 되어 이 의뢰인만의 시각 정체성을 만들라고 주문하고, 주제와 대상, 주된 용도를 먼저 파악하라고 합니다. 본문이 거의 지침 문장이라, 구조를 읽어 보기에 좋은 단순한 스킬입니다. 장점은 뻔한 화면을 피하게 한다는 점입니다. 단점은 지침 문장뿐이라 결과가 모델의 판단에 달렸다는 점입니다. 의미는 모델의 버릇을 지침으로 누를 수 있다는 것입니다.
Anthropic 공식 스킬
문서 스킬 네 개가 Word · PDF · PPT · Excel 작업을 맡는다
raw.githubusercontent.com/anthropics/skills/main/skills/docx/SKILL.md
저장소 원문 화면 캡처 · 2026-10-28 확인 · 위는 docx
docx 스킬 원문. 설명에 ‘.docx’, ‘Word 문서’ 같은 호출 단서 와 쓰지 말아야 할 경우까지 적혀 있다.
description에 호출 단서와 쓰지 말 경우 까지 적어, Word·PDF·PPT·Excel 요청에 정확히 불린다.
예제 스킬과 달리 오픈소스가 아니라 소스 공개 . 사용 조건은 LICENSE를 확인해야 한다.
설명 문장이 호출을 좌우한다는 실제 사례 . 복잡한 실서비스 스킬의 참고용.
문서 스킬은 docx, pdf, pptx, xlsx 네 개입니다. 저장소 README는 이 스킬들이 Claude의 문서 생성과 편집 기능을 뒷받침하며, 복잡한 실서비스 스킬의 참고용으로 공개했다고 설명합니다. 저장소의 많은 예제 스킬은 Apache 2.0이지만 이 네 개는 오픈소스가 아니라 소스 공개라는 점을 정확히 말씀드립니다. docx의 description을 보면 트리거가 얼마나 구체적인지 알 수 있습니다. Word 문서, .docx, 목차, 쪽 번호 같은 말이 나오면 쓰고, PDF나 구글 문서에는 쓰지 말라고 부정 조건까지 적습니다. 설명 문장이 호출을 좌우한다는 말의 실제 사례입니다. 장점은 호출 단서와 부정 조건까지 적어 정확히 불린다는 점입니다. 단점은 소스 공개 라이선스라 사용 조건을 확인해야 한다는 점입니다. 의미는 설명 문장이 호출을 좌우한다는 실제 사례입니다.
Anthropic 공식 스킬
webapp-testing은 에이전트가 브라우저로 직접 눌러 보게 한다
raw.githubusercontent.com/anthropics/skills/main/skills/webapp-testing/SKILL.md
저장소 원문 화면 캡처 · 2026-10-28 확인
webapp-testing 스킬 원문. Playwright(브라우저 자동화 도구) 로 로컬 웹앱을 조작하고 스크린샷을 남기는 방법을 안내한다.
코드가 맞아 보여도 브라우저로 직접 눌러 확인하고 스크린샷·로그를 남긴다. with_server.py가 서버를 띄우고 내린다.
로컬 웹앱 이 대상이고 Python Playwright 스크립트가 필요하다. 스크립트 소스는 읽지 않고 블랙박스로 실행한다.
점진적 공개 3단계가 실제로 쓰이는 예. → 15교시 스모크 테스트
코드가 맞아 보여도 눌러 보면 안 되는 일이 많습니다. 이 스킬은 로컬 웹앱을 Playwright로 조작하고 스크린샷과 브라우저 로그를 남기는 방법을 알려 줍니다. 서버를 띄우고 끄는 번거로움은 with_server.py가 맡습니다. 본문에는 흥미로운 지시가 있는데, 스크립트는 먼저 help만 실행하고 소스는 읽지 말라는 것입니다. 큰 스크립트를 읽으면 컨텍스트 창이 오염되므로 블랙박스로 호출하라는 뜻이고, 앞서 본 점진적 공개의 3단계가 실제로 이렇게 쓰입니다. 15교시 스모크 테스트에서 다시 만납니다. 장점은 눌러 보고 증거를 남긴다는 점입니다. 단점은 로컬 웹앱 대상이고 Playwright 환경이 필요하다는 점입니다. 의미는 점진적 공개가 실제로 쓰이는 예라는 것입니다.
mattpocock/skills
계획을 끝까지 캐묻는 인터뷰형 스킬 grill-me
mattpocock/skills · skills/productivity/grill-me/SKILL.md
grill-me · 사람이 부르는 입구
grill-me 원문. 사람이 부르는 입구이고 본문은 grilling 스킬을 부르라 는 한 줄뿐이다.
mattpocock/skills · skills/productivity/grilling/SKILL.md
grilling · 실제 인터뷰 절차
grilling 원문. 결정을 트리로 보고 라운드마다 질문과 추천 답 을 내는 실제 절차.
계획의 빈틈을 구현 전에 끝까지 캐묻고 , 질문마다 추천 답이 있어 “예”만 해도 진행된다.
사람이 직접 불러야 하고(disable-model-invocation), 라운드마다 답할 시간이 든다 .
사실 조사는 에이전트, 결정은 사람 몫. 구현에 들어가기 전의 설계 점검으로 쓴다.
mattpocock의 스킬 모음은 저자가 자기 .agents 디렉터리를 그대로 공개한 것입니다. 그중 grill-me는 계획이나 설계를 에이전트가 끈질기게 인터뷰해서 다듬게 합니다. 구조가 재미있습니다. grill-me 자체는 frontmatter에 disable-model-invocation을 켜서 사람이 직접 부를 때만 쓰이고, 본문은 grilling 스킬을 부르라는 한 줄뿐입니다. 실제 절차는 grilling에 있습니다. 결정을 트리로 보고, 먼저 물을 수 있는 질문을 한 라운드에 번호를 붙여 내며, 질문마다 추천 답을 달아 예라고만 해도 진행되게 합니다. 환경에서 찾을 수 있는 사실은 서브에이전트가 찾고 사용자에게 묻지 않습니다. 구현에 들어가기 전의 설계 점검으로 쓰기 좋습니다. 장점은 구현 전에 계획의 빈틈이 드러난다는 점입니다. 단점은 사람이 직접 불러야 하고 답할 시간이 든다는 점입니다. 의미는 사실 조사는 에이전트가, 결정은 사람이 맡는다는 것입니다.
2026-01-27
Karpathy guidelines: 나쁜 버릇을 막는 네 원칙
x.com/karpathy/status/2015883857489522876
근거: Karpathy의 X 게시물 · 2026-01-26
Karpathy가 X에 남긴 LLM(Large Language Model, 대규모 언어 모델) 코딩 관찰 게시물. 스킬의 바탕이 됐다.
github.com/forrestchang/andrej-karpathy-skills · SKILL.md
스킬 원문 · 제3자 제작, Karpathy 본인이 만든 것이 아님
이를 정리한 SKILL.md. Karpathy가 만든 것은 아니다.
코딩 전에 생각: 가정을 밝히고 모르면 묻는다
단순함 우선: 요청하지 않은 기능 금지
수술하듯 고친다: 바꾼 줄은 요청에 닿아야 한다
목표 주도: 검증할 수 있는 성공 기준
가정 숨김·과복잡·엉뚱한 곳 수정 같은 모델의 나쁜 버릇 을 네 원칙으로 막는다.
속도보다 신중함 쪽이라 사소한 작업엔 과하다. 제3자 제작이라 Karpathy 공식 스킬이 아니다.
유명인 이름보다 누가 만들었는지 확인 . 강사 스킬 지도에서는 구현·수정 단계에 넣었다.
이름 때문에 오해하기 쉬워서 먼저 짚겠습니다. 이 스킬은 Andrej Karpathy 본인이 만든 것이 아닙니다. 제3자인 forrestchang이 Karpathy가 X에 쓴 LLM(Large Language Model, 대규모 언어 모델) 코딩의 함정에 대한 관찰을 정리해서 스킬로 만든 것이고, 본문도 그 글에서 파생했다고 밝힙니다. 네 원칙은 모델이 가정을 숨기고, 필요 이상으로 복잡하게 만들고, 건드리지 말아야 할 코드를 고치는 버릇에 맞춰져 있습니다. 제 스킬 지도에도 구현과 수정 단계에 들어가 있습니다. 한 가지 단서는 본문에도 있습니다. 이 원칙은 속도보다 신중함에 치우쳐 있어 사소한 작업에는 판단해서 쓰라고 합니다. 위 화면이 근거가 된 Karpathy의 2026년 1월 X 게시물이고, 아래가 그것을 정리한 스킬 원문입니다. 장점은 모델의 나쁜 버릇을 네 원칙으로 막는다는 점입니다. 단점은 신중함 쪽이라 사소한 작업에는 과하다는 점입니다. 의미는 이름이 아니라 누가 만들었는지를 확인해야 한다는 것입니다.
2026-06-12
Ponytail은 코드를 쓰기 전에 7단 사다리를 먼저 오르게 한다
github.com/DietrichGebert/ponytail
Ponytail README 그림
Ponytail README의 7단 사다리 그림. ‘이게 필요한가’부터 ‘최소 구현’까지 일곱 단계로 묻는다.
코드를 쓰기 전 “필요한가”부터 묻게 해 불필요한 코드를 줄인다. lite·full·ultra로 강도를 고른다.
저장소의 벤치마크 수치는 직접 검증하지 못해 다루지 않는다. 게으른 것은 해법이지 읽는 일이 아니다.
코드는 줄여도 검증·데이터 손실 방지·보안·접근성 은 줄이지 않는다. Karpathy와 같은 과열 방지 계열.
사다리는 이렇게 읽습니다. 이게 존재해야 하는가, 이 코드베이스에 이미 있는가, 표준 라이브러리가 하는가, 플랫폼 기능이 있는가, 설치된 의존성이 있는가, 한 줄로 되는가. 이 질문에서 처음으로 성립하는 단에서 멈추고, 전부 아니면 마지막 7단에서 최소한만 만듭니다. 저장소 스킬 본문에는 lite, full, ultra 세 단계가 있어 강도를 고를 수 있습니다. 강조할 것은 게으른 것은 해법이지 읽는 일이 아니라는 점입니다. 코드를 먼저 읽고, 호출하는 곳과 테스트까지 빠뜨리지 않고, 유효성 검증과 보안, 접근성은 절대 줄이지 않습니다. 저장소 자체의 벤치마크 수치는 직접 검증한 것이 아니므로 말씀드리지 않겠습니다. 장점은 쓰기 전에 필요한지부터 묻는다는 점입니다. 단점은 벤치마크 수치를 직접 검증하지 못했다는 점입니다. 의미는 코드는 줄여도 검증과 보안은 줄이지 않는다는 것입니다.
비교
스킬은 성격이 갈리니, 작업 시점에 맞는 것만 고른다
스킬 성격 쓰는 때 장점 한계·주의
Superpowers 방법론 묶음 새 기능을 처음부터 만들 때 설계에서 리뷰까지 한 흐름 작은 수정엔 무겁다 skill-creator 제작 도구 내 스킬을 만들고 고칠 때 시험·평가·설명 다듬기 시험 프롬프트 수고 frontend-design 디자인 지침 새 화면을 만들 때 뻔한 기본값을 피함 지침뿐, 결과는 모델 몫 문서 스킬 4개 문서 도구 Word·PDF·PPT·Excel 작업 호출 단서가 촘촘 소스 공개, 조건 확인 webapp-testing 테스트 도구 로컬 웹앱을 눌러 볼 때 스크린샷·로그가 증거 Playwright 환경 필요 grill-me 인터뷰 구현 전 계획을 점검할 때 질문마다 추천 답 사람이 부르고 답한다 Karpathy guidelines 과열 방지 구현·수정 전반 가정 공개, 최소 변경 사소한 일엔 과함, 제3자 제작 Ponytail 과열 방지 코드를 쓰기 전 필요한가부터 묻는다 벤치마크 미검증
컨텍스트 비용은 모두 같습니다. 설명만 항상, 본문은 쓸 때만 . 그러니 비용보다 무엇을 줄이고 무엇을 지키는지 로 고릅니다.
앞에서 본 여덟 가지를 같은 기준으로 한 표에 모았습니다. 기준은 성격, 쓰는 때, 장점, 한계입니다. 컨텍스트 비용은 어느 스킬이나 같습니다. 설명만 항상 올라가고 본문은 쓸 때만 읽히기 때문입니다. 그래서 비용으로 고르기보다 성격으로 고릅니다. Superpowers는 방법론, skill-creator와 문서 스킬, webapp-testing은 도구, grill-me는 사람이 부르는 인터뷰, Karpathy와 Ponytail은 에이전트가 시킨 것보다 더 만드는 과열을 막는 지침입니다. 전부를 한꺼번에 켜지 않고 작업 시점에 맞는 것만 씁니다.
과열 방지
과열 방지: 에이전트는 시킨 것보다 더 만든다
과열의 증상 스킬로 막는다 결과 시키지 않은 기능 한 번 쓰는데 추상화 옆 코드까지 정리 필요 없는 의존성 Karpathy guidelines Simplicity First Surgical Changes Ponytail 7단 사다리 프롬프트에 수준 명시 "이건 PoC입니다" 작은 diff 리뷰할 수 있는 변경 방지 규칙
1교시 DDD(Domain-Driven Design, 도메인 주도 설계)의 “이건 PoC(Proof of Concept, 개념 증명)입니다 ”와 같은 방향입니다. 수준을 적고, 스킬로 상시 켜 둡니다. → 6교시 DDD
에이전트는 잘 만들고 싶어 하기 때문에 시킨 것보다 더 만듭니다. 요청하지 않은 기능, 한 번만 쓰는 코드의 추상화, 옆 코드의 정리, 필요 없는 의존성이 그 증상입니다. 이것을 과열이라고 부릅니다. 과열은 리뷰해야 할 diff를 키우고 버그가 숨을 곳을 늘립니다. 막는 방법은 세 가지입니다. Karpathy guidelines의 단순함 우선과 수술하듯 고치기, Ponytail의 사다리, 그리고 가장 기본인 프롬프트에 수준을 명시하는 것입니다. 스킬은 이것을 매번 적지 않아도 되게 해 줍니다. 다만 과열을 막는 스킬을 켜 둔 채 정말 필요한 검증까지 줄이지는 않는지 한 번씩 점검해 보면 좋습니다.
강사 운영 방식
제 스킬 지도: 작업 시점마다 하나씩
스킬 쓰는 시점 핵심
brainstorming 구현 전 질문, 대안 비교, 설계 결정 writing-plans 설계 이후 작업별 변경 대상과 검증 방법 using-git-worktrees 작업 격리가 필요할 때 독립 작업 공간, 시작 상태 확인 karpathy-guidelines 구현·수정 가정 공개, 최소 변경, 검증 가능한 목표 systematic-debugging 실패·오류 발생 시 재현 → 증거 → 가설 → 원인 수정 requesting-code-review 독립 검토가 필요한 변경 후 요구사항과 실제 변경의 독립 검토 verification-before-completion 완료 보고 전 최신 증거와 주장 범위 일치 session-driven-delivery 큰 작업 분할 세션·PR(Pull Request, 변경 병합 요청)·이슈·인계의 역할
전부를 모든 과제에 의무로 쓰지 않습니다. 작은 수정은 간단한 기록과 비례한 검증으로 끝냅니다.
제가 쓰는 스킬을 작업 시점별로 정리한 지도입니다. 오늘 본 Superpowers와 Karpathy guidelines의 스킬이 여러 개 들어 있다는 점이 눈에 띕니다. 구현 전에는 brainstorming과 writing-plans, 격리가 필요하면 worktree, 구현할 때는 Karpathy 원칙, 실패하면 체계적 디버깅, 끝낼 때는 독립 리뷰와 완료 전 검증입니다. 이 표는 제 로컬에서 스킬 원문을 확인해 작성한 것이고, 설치했다는 사실과 실제로 자주 쓰는 정도는 구분합니다. 제가 중요하게 보는 것은 마지막 줄입니다. 스킬을 많이 쓰는 것이 아니라 작업의 크기에 맞게 골라 쓰는 것이 운영의 기준입니다.
강사 운영 방식
제 스킬 패키지: kdev 여덟 개
kdev-model 작업마다 모델·사고 수준 선택 kdev-start 문제·범위·완료 조건 kdev-plan 설계·작은 Task kdev-build 범위 안에서 구현 kdev-debug 재현 → 원인 → 재검증 kdev-handoff 다음 세션 인계 kdev-deliver 전달·실제 사용 확인 kdev-review 기준 대비 검토
시작 → 계획 → 구현 → 검토 → 전달 → 인계. 실패하면 debug , 작업마다 model 로 모델과 사고 수준을 고릅니다.
앞 장이 외부 스킬의 지도였다면, 이것은 제가 직접 만든 한국어 스킬 패키지입니다. 여덟 개가 작업의 흐름을 따라갑니다. kdev-start가 문제와 범위, 완료 조건을 정리하고, kdev-plan이 설계와 작은 작업으로 나누고, kdev-build가 합의한 범위에서 구현하고, kdev-review가 기준에 맞춰 검토합니다. kdev-deliver가 전달 수준과 실제 사용 확인을 맡고, kdev-handoff가 다음 사람이나 세션이 이어받을 상태를 남깁니다. 구현 중에 실패하면 kdev-debug로 재현, 원인, 수정, 재검증을 기록하고, kdev-model은 작업에 맞는 모델과 사고 수준을 고릅니다. 이 흐름은 제 18단계 운영 기준과 이어지고, ADR(Architecture Decision Record, 아키텍처 결정 기록)과 이슈 흐름은 14교시에서 다룹니다.
강사 운영 방식
kdev-start는 범위부터 읽고 과한 절차를 얹지 않는다
raw.githubusercontent.com/TheMagicTower/korean-ai-dev-course/main/skills/kdev-start/SKILL.md
저장소 원문 화면 캡처 · 2026-10-28 확인
범위와 단계를 먼저 읽어 저위험 작업에 기업용 절차를 얹지 않고 , 완료 조건이 판정되면 끝낸다.
파일이 저장소에 있어도 설치·호출은 별개 . 설치, 새 세션 발견, 지침 준수를 따로 확인해야 한다.
과열 방지 규칙을 품은 스킬. 저장소에 있다는 것과 쓰인다는 것은 다르다 .
kdev-start의 실제 파일입니다. 한국어로 써도 구조는 같습니다. frontmatter의 설명에 언제 쓰는지 적고, 본문에 수행 순서를 적었습니다. 이 스킬이 과열 방지 규칙을 품고 있다는 점이 중요합니다. 사용 범위와 목표 단계를 먼저 읽고, 개인용 저위험 작업에 기업용 문서나 CI/CD(Continuous Integration/Continuous Delivery, 지속적 통합·지속적 전달), 독립 리뷰를 일괄로 얹지 않으며, 필요한 완료 조건을 통과하면 끝냅니다. 질문만 반복하거나 요청받지 않은 구현을 시작하지 말라는 종료 규칙도 있습니다. 패키지 안내에는 저장소에 파일이 있다는 사실만으로 사용자 환경에 설치되거나 자동 호출되지는 않는다는 주의가 있어, 그대로 옮겼습니다. 장점은 저위험 작업에 과한 절차를 얹지 않는다는 점입니다. 단점은 파일이 있어도 설치와 호출은 따로 확인해야 한다는 점입니다. 의미는 저장소에 있는 것과 쓰이는 것은 다르다는 것입니다.
호출을 좌우하는 것
description 한 문장이 스킬을 부른다
호출이 잘 안 되는 설명
“Helps with PDFs.”
무엇을 하는지, 언제 쓰는지 모른다 에이전트가 ‘지금 필요한가’를 판단할 단서가 없다
호출이 잘 되는 설명
“Extracts text and tables from PDF files … Use when working with PDF documents.”
하는 일 과 쓰는 때 를 둘 다사용자가 말할 법한 낱말(PDF, forms)을 넣는다
앞에 핵심 용도 를 둡니다. Claude Code는 설명을 1,536자에서 자릅니다. 사람만 부를 스킬은 disable-model-invocation .
스킬이 쓰이느냐는 본문이 아니라 description이 정합니다. 에이전트는 시작할 때 이름과 설명만 보고, 이 작업에 필요한지 판단하기 때문입니다. 명세의 예시는 대비가 분명합니다. “Helps with PDFs”는 너무 막연하고, 하는 일과 쓰는 때, 관련 낱말을 함께 적은 설명이 좋은 설명입니다. 앞서 본 brainstorming의 “반드시 쓰라”와 docx의 부정 조건도 같은 기술입니다. Claude Code는 설명을 1,536자에서 자르므로 핵심을 앞에 둡니다. 반대로 배포처럼 사람이 결정해야 하는 스킬은 모델 호출을 꺼서 설명 자체를 컨텍스트에서 뺍니다.
나만의 스킬
나만의 스킬: 쓰고, 시험하고, 고친다
1 · 반복 찾기 같은 지침을 세 번 붙여 넣었나 2 · 폴더와 SKILL.md name · description 3 · 본문 쓰기 500줄 안, 단계·예시 4 · 실제 요청으로 시험 호출되는가 따라 하는가 5 · 고친다 설명 문장부터 다시 시험
처음부터 완벽하게 쓰지 않습니다. 실제 요청으로 호출되는지 부터 확인하고, 안 불리면 설명 을 고칩니다. → 12교시 실습
직접 만드는 순서는 다섯 단계입니다. 먼저 같은 지침을 세 번 붙여 넣은 자리를 찾습니다. 폴더를 만들고 SKILL.md에 이름과 설명을 씁니다. 본문은 단계와 예시 중심으로 500줄 안에 쓰고, 길어지면 참고 자료를 별도 파일로 뺍니다. 그다음 실제 요청으로 시험합니다. 부르면 호출되는지, 호출된 뒤 지침을 따르는지 봅니다. 마지막으로 고치는데, 호출이 안 되면 본문보다 설명 문장부터 봅니다. skill-creator에게 이 과정을 시킬 수도 있습니다. 12교시 실습에서 여러분의 작업 방식을 스킬 하나로 만듭니다.
정리
정리: 방법론은 폴더로 옮겨 다닌다
github.com/DietrichGebert/ponytail
저장소 화면 캡처 · 플러그인 폴더가 에이전트별로 나뉜 모습
Ponytail 저장소 첫 화면. 플러그인 폴더가 에이전트별로 나뉘어 있다.
스킬 = SKILL.md 폴더. 설명만 항상, 본문은 필요할 때
Superpowers는 방법론, Karpathy·Ponytail은 과열 방지, 공식 스킬은 도구 상자
내 스킬은 설명 한 문장부터 시험해서 고친다
→ 12교시: 내 작업 방식을 스킬 하나로, MCP 연결, 긴 작업 맡기기
오늘 본 것을 묶으면, 스킬은 SKILL.md가 든 폴더이고, 점진적 공개로 필요할 때만 읽힙니다. Superpowers는 설계, 계획, 서브에이전트 실행, TDD를 묶은 방법론이고, Karpathy guidelines와 Ponytail은 에이전트가 과열하지 않게 하며, Anthropic 공식 스킬은 만들기와 문서, 화면, 테스트의 도구 상자입니다. 오른쪽 화면처럼 같은 스킬을 에이전트마다 폴더로 나눠 배포하는 일이 오픈 표준 이후의 모습입니다. 다음 12교시는 실습입니다. 여러분의 작업 방식을 스킬 하나로 만들고, MCP를 하나 연결하고, 긴 작업을 맡겨 봅니다. 오늘 쓴 description 한 문장을 가지고 오시면 좋습니다.
3회차 · 12교시
실습 3
하네스를 한 번 더 키운다:
15단계 워크트리·규칙 스킬 예: issue-flow MCP Model Context Protocol, 필요하면 /goal 오래 맡기기
12교시는 실습입니다. 도구 설치와 로그인은 하지 않고, 각자 쓰던 에이전트를 그대로 씁니다. 지난 회차에는 이슈 하나를 스펙, 계획, 구현, 리뷰 순서로 에이전트와 처리했습니다. 오늘 소개하는 장치는 메뉴입니다. 순서를 스킬로 포장하기, 이슈마다 작업 공간을 나누는 규칙, 외부 도구 연결, 이슈 하나를 완료 조건까지 통째로 맡기기가 있고, 이 가운데 내 하네스에 필요한 것을 골라 시키면 됩니다. 제가 쓰는 방식을 보여 드리고, 자기 방식대로 바꿔도 됩니다. 이번에도 설정 파일은 여러분이 쓰지도, 읽지도 않습니다. 에이전트에게 질문부터 시켜서 만들고, 여러분은 답하고 승인한 뒤 실제로 돌려 보며 확인합니다.
약 55분 · 프롬프트 + 스모크
제 방식은 늘 같다: 질문 → 설계 승인 → 구현 → 스모크, 그리고 /goal로 이슈 하나
15 설계 대화 격리·리뷰·CI·머지 규칙 ADR-0003 + issue-flow 설계 워크트리 · 스킬 · MCP · 상한 사람 승인 권한·블로커·상한 확인 /goal로 이슈 하나 완료 조건 + 상한 + 기록 스모크 스킬 호출 · MCP 연결 확인 구현 에이전트가 스킬·설정 작성
여러분이 보는 것은 코드가 아니라 내가 한 답, 에이전트가 정리한 결정, 스모크 결과 세 가지입니다.
오늘은 제 운영 기준 18단계 가운데 15단계, 작업을 어떻게 격리하고 합칠 것인가를 하네스 크기로 줄여 적용합니다. 먼저 에이전트가 격리, 리뷰, 머지 규칙과 스킬, MCP(Model Context Protocol, 모델 컨텍스트 프로토콜), 완료 조건에 대해 질문하고 여러분이 답합니다. 에이전트는 답을 ADR(Architecture Decision Record, 아키텍처 결정 기록) 한 건과 스킬 설계로 정리하고, 여러분이 읽고 승인한 뒤에야 구현합니다. 구현 뒤에는 코드를 열어 보는 대신 스모크로 확인합니다. 스킬이 불리는지, MCP가 붙었는지 보고, 원하면 마지막으로 이슈 하나를 /goal로 맡겨 조건에서 멈추는지 봅니다. 설계 대화 12분, 승인 8분, 구현 10분, 스모크 10분, 이슈 완주 15분 정도로 잡습니다.
이슈별 워크플로우 1–8단계
지난 시간에 매번 말로 시킨 순서가 스킬 후보다
이슈 분석 → ADR(Architecture Decision Record, 아키텍처 결정 기록) 점검 → 스펙 → 스펙 리뷰 → 계획 → 계획 리뷰 → 구현 → 구현 리뷰를 이슈마다 다시 설명 했다
같은 설명을 세 번 쓰면 후보. 한 스킬 = 한 작업
스킬의 본문은 필요할 때만 읽힌다. 어떤 말에 불리는지가 호출을 좌우한다
← 11교시 · 스킬
세션 시작 시 스킬 목록(이름+설명) 설명과 맞는가? 내 요청 SKILL.md 본문 + 참고 자료 /skill-name 직접 호출 본문 지침대로 작업 예
직접 도식 · 스킬 로딩 흐름
8교시에 이슈 하나를 처리하면서 에이전트에게 스펙을 쓰라고 하고, 리뷰하라고 하고, 계획을 세우라고 하고, 구현하라고 했습니다. 이슈가 열 개면 같은 설명을 열 번 하게 됩니다. 이런 반복이 스킬로 만들 후보입니다. 도식처럼 세션이 시작되면 스킬의 이름과 설명만 목록에 올라가고, 요청이 설명과 맞을 때 본문을 읽습니다. 그래서 설명 문장을 잘 쓰는 것이 중요합니다. 이 스킬도 저는 쓰지 않고 에이전트에게 설계 대화를 거쳐 만들게 한 뒤, 불리는지만 확인합니다.
그대로 붙여 넣어도 됩니다
첫 프롬프트(예): 코드 전에 질문을 하나씩 하고, 설계는 ADR로 남기라고 한다
> 내 하네스 저장소(메모 앱 PoC (Proof of Concept, 개념 증명))에 장치를 더하고 싶다.
후보: ① 이슈마다 격리할 워크트리·브랜치·리뷰·머지 규칙,
② 반복하는 순서를 하나의 스킬 로(예: issue-flow),
③ MCP 서버, ④ /goal로 이슈 맡기기.
내게 필요한 게 뭔지부터 물어봐.
아직 파일은 만들지 마.
필요한 질문을 한 번에 하나씩 ,
네 추천 답과 이유를 같이 주고 8개 안에서 끝내.
끝나면 docs/adr/0003-workflow.md , 스킬·MCP 설계 요약,
스모크로 확인할 시나리오 목록 을 쓰고
내가 “승인”이라고 할 때까지 기다려.
code.claude.com/docs/en/common-workflows
공식 문서 화면 캡처 · 2026-10-28 확인
Claude Code 문서의 ‘공통 워크플로’. 목차에 워크트리로 병렬 세션을 돌려 동시 수정이 충돌하지 않게 하는 절이 있다.
4교시와 같은 방식의 프롬프트입니다. 아직 파일을 만들지 말 것, 질문은 한 번에 하나씩 추천 답과 함께, 정리한 설계는 제가 승인할 때까지 기다릴 것, 이 세 가지를 못 박습니다. 하나 더, 끝에 스모크 시나리오 목록을 달라고 합니다. 코드를 열어 보지 않는 대신 돌려서 확인하기 위해서입니다. 이번에는 고를 수 있는 것이 몇 묶음입니다. 이슈를 어떻게 격리하고 합칠지, 이슈별 순서를 스킬로 만들지, 어떤 외부 도구를 붙일지, /goal로 맡길지입니다. 위 프롬프트는 제가 고른 경우이고, 여러분은 후보를 바꿔 쓰시면 됩니다. 결과는 새 ADR 한 건으로 남깁니다. 4교시에 만든 문서가 있으면 에이전트가 먼저 읽도록 저장소 안에서 시키면 됩니다. 오른쪽은 워크트리를 설명하는 공식 문서 화면입니다.
설계 대화 체크리스트
에이전트가 물을 질문은 격리, 리뷰, 스킬, MCP, 완료 조건에 걸쳐 있다
주제 에이전트가 물을 것 예시 답 빠지면 15 격리 이슈 하나를 어디서 작업하나 이슈마다 워크트리 + issue/번호 브랜치 두 이슈가 한 폴더에서 섞인다 15 충돌 같은 파일을 건드리는 이슈는 한 번에 하나, 공유 파일은 이슈에 미리 적음 합칠 때 뒤늦게 충돌 15 리뷰·머지 누가 리뷰하고 언제 합치나 리뷰어 서브에이전트, 머지는 사람 승인(16교시) 쓴 쪽이 스스로 통과시킨다 스킬 순서와 멈춤을 어디까지 담나 1–8단계, 블로커 없으면 종료, 예산 소진 시 인계 이슈마다 말로 다시 설명 MCP 어떤 외부 정보가 필요하고 믿을 만한가 라이브러리 문서 서버 1개, 읽기만, 비밀 없음 쓸모없는 도구, 주입·토큰 낭비 /goal 어느 이슈를 어떤 끝 상태까지, 상한은 이슈 하나, 테스트 통과 + 블로커 0, 20턴 조건이 모호해 헛돈다 기록 무엇을 남기나 시간·턴·토큰·성공/실패 다음 회차의 근거가 없다
설계 대화에서 제가 에이전트의 질문을 살피는 기준입니다. 15단계의 핵심은 작업을 어떻게 격리하고 어떻게 합치는가입니다. 격리, 충돌, 리뷰와 머지 세 줄이 여기에 해당합니다. 나머지 네 줄은 오늘 더할 장치인 스킬, MCP, /goal, 기록입니다. 에이전트가 일부를 묻지 않으면 여러분이 먼저 꺼내 봅니다. 모르는 항목은 선택지 두 개와 장단점을 표로 달라고 하면 됩니다. 머지와 PR(Pull Request, 변경 병합 요청) 규칙은 오늘은 정하기만 하고, 실제로 PR을 만들고 머지하는 일은 4회차에서 합니다.
18단계 중 15단계
15단계의 결과는 ADR 한 건의 결정 요약이다
항목 에이전트가 정리한 결정(예시) 내가 볼 점 격리 이슈 하나 = 브랜치 하나 = 작업 공간 하나 두 이슈가 안 섞이는가 충돌 같은 파일을 건드릴 이슈는 한 번에 하나 겹칠 때의 규칙이 있는가 리뷰 구현한 쪽이 아닌 리뷰어 서브에이전트 쓴 쪽이 통과시키지 않는가 머지 PR(Pull Request, 변경 병합 요청)·머지는 사람 승인 뒤, 4회차(16교시)에 오늘은 정하기만 하는가 다시 판단할 조건 두 이슈가 같은 파일에서 충돌하면 4교시 ADR과 같은 서식인가
이슈마다 작업이 나뉘어, 한 이슈를 하는 동안 다른 이슈의 변경이 섞이지 않는다 . 4회차의 병렬 실행의 바탕이 된다.
작업 공간이 늘어 디스크를 더 쓴다. 겹치는 파일은 여전히 합칠 때 충돌 한다.
15단계의 질문 ‘작업을 어떻게 격리하고 합치는가’에 대한 답. 결정과 이유가 ADR에 남아 다음 판단의 기준이 된다.
워크트리를 만드는 명령은 에이전트가 이슈마다 알아서 실행합니다. 저는 결정이 맞는지 만 봅니다.
에이전트가 정리한 ADR의 한 줄 요약 예입니다. ADR 본문이나 명령을 읽지는 않고 이 표만 봅니다. 격리는 이슈, 브랜치, 작업 공간이 하나씩 대응하는지 봅니다. 충돌은 같은 파일을 건드리는 이슈를 어떻게 다루는지, 리뷰는 구현한 쪽이 아닌 다른 서브에이전트가 하는지 봅니다. 머지는 사람 승인 뒤로 미루었는지 확인합니다. 마지막 줄의 다시 판단할 조건은 4교시 ADR과 같은 서식입니다. 표의 내용은 예시이고, 여러분 에이전트의 정리는 다를 수 있습니다.
승인 체크리스트
승인 전에 저는 다섯 가지만 확인한다
내가 한 답 이 정리에 그대로 들어 있다(바뀐 답이 없다)결정 요약 에 이슈 하나당 작업 공간 하나와 겹칠 때의 규칙이 있다스킬을 만든다면 어떤 말에 불려야 하는지 가 한 문장으로 적혔고, PR·머지는 스킬 밖이다
예산이 떨어지면 통과가 아니라 중단·인계 하고, MCP를 붙인다면 믿을 서버 하나다
스모크 시나리오 목록 이 있고(고른 장치별: 스킬 호출 · 일부러 어기기 · MCP · /goal 멈춤), 구조를 30초 안에 설명할 수 있다
볼 것이 세 가지로 줄어, 코드를 읽지 않고도 승인 여부를 빨리 판단 할 수 있다.
목록에 없는 위험(예: 서버가 가져오는 글의 프롬프트 주입 )은 놓칠 수 있다. 낯선 항목은 에이전트에게 위험을 따로 묻는다.
에이전트가 만들고 사람이 판정 하는 분업. 4교시 승인과 같고, 이번에는 대상이 스킬·MCP·완료 조건이다.
승인 전에 저는 다섯 가지를 봅니다. 내가 한 답이 정리에 그대로 들어갔는지, 결정 요약에 격리와 충돌 규칙이 있는지, 스킬이 어떤 말에 불려야 하는지 한 문장으로 적혔는지, 예산이 떨어졌을 때 통과시키지 않고 중단하게 되어 있는지, 스모크 시나리오 목록이 있는지입니다. 이 구조를 30초 안에 설명하지 못하면 승인하지 않고 더 단순하게 바꿔 달라고 합니다. 승인은 사람만 합니다. 마음에 안 드는 한 곳은 에이전트에게 말로 고치게 해 봅니다.
이슈별 워크플로우 1–8단계
스킬은 하네스에게 시키고, 실제로 불리는지로 확인한다
# 프롬프트
> 지난주 이슈 처리 1–8단계(분석 → ADR 점검 → 스펙 → 스펙 리뷰 → 계획 → 계획 리뷰 → 구현 → 구현 리뷰)를 issue-flow 스킬 로 만들어 줘.
“12번 이슈 처리해 줘”처럼 이슈 번호를 말하면 불려야 해.
구현은 테스트 먼저, 리뷰는 리뷰어 서브에이전트가 해.
예산이 떨어졌는데 블로커가 남으면 통과시키지 말고 진행 파일에 적고 중단해.
PR·머지는 이 스킬에 넣지 마.
끝나면 직접 이름으로 한 번, 평범한 문장으로 한 번 불러서 불린 증거 를 보여 줘.
시나리오 기대 결과 실제(예시) 통과 이름으로 직접 호출 스킬이 불리고 1단계부터 1단계 출력 확인 O “12번 이슈 처리해 줘” 자동으로 불림 불리지 않음 X 스펙 리뷰 건너뛰자고 요청 거절, 단계 유지 거절하고 4단계 수행 O
X가 나오면 “스킬이 방금 왜 안 불렸는지 설명하고, 내가 실제로 할 말에 불리게 고친 뒤 같은 문장으로 다시 보여 줘” 라고 시킵니다.
스킬은 제가 파일을 열어 보지 않고, 하네스에게 시킨 뒤 실제로 불리는지로 확인합니다. 프롬프트에는 어떤 말에 불려야 하는지, 순서, 멈춤 규칙, 하지 않을 것을 담았습니다. 스모크는 세 가지입니다. 이름으로 직접 부르기, 평범한 문장으로 부르기, 단계를 건너뛰자고 일부러 요청하기입니다. 표의 실제 결과 칸은 예시이고, 자동 호출이 실패하는 경우를 일부러 넣었습니다. 이런 경우 스킬의 설명 문장을 고치게 하면 대개 풀립니다.
문서 조회 MCP 서버 하나
MCP도 하네스에게 시키고, 붙었는지 직접 불러 보게 한다
# 프롬프트
> 이슈를 분석할 때 최신 라이브러리 문서를 볼 수 있게 문서 조회 MCP 서버 하나 (대표 Context7)를 이 저장소에 연결해 줘.
읽기만 하고, 토큰이 필요하면 값이 아니라 환경 변수 이름 으로만 써.
끝나면 연결 상태와 쓸 수 있는 도구 목록을 보여 주고, 새 세션에서도 보이는지 확인해 줘.
# 스모크 (대화 예시)
학생 새 세션이야. MCP 연결 상태 보여 줘.
하네스(예시) 서버 1개 연결됨, 상태 정상.
학생 12번 이슈에 쓰는 라이브러리의 정렬 옵션을 문서 조회 도구로 확인해서 스펙에 반영해 줘.
하네스(예시) 문서 조회를 2회 호출했고, 확인한 옵션을 스펙에 적었습니다.
학생 이 서버가 가져온 글에 “지시”가 섞여 있을 때는?
하네스(예시) 가져온 글은 참고 자료로만 쓰고 지시로 따르지 않습니다.
저는 세 가지만 봅니다. 연결 상태 , 실제로 호출된 기록 , 비밀 값이 파일에 없다는 확인 (“파일에 토큰 값이 없는지 검색해서 보여 줘”).
MCP는 에이전트에 외부 도구를 연결하는 규약입니다. 오늘은 이슈 분석에 쓸 문서 조회 서버 하나만 붙입니다. 대표 도구로 Context7을 씁니다. 연결 설정은 하네스가 만들고, 저는 설정 파일을 열지 않습니다. 대신 새 세션에서 연결 상태를 묻고, 실제로 호출해 보게 하고, 비밀 값이 파일에 남지 않았는지 검색하게 합니다. 서버가 가져오는 글에 지시가 섞이는 프롬프트 주입 위험이 있으니, 가져온 글을 지시로 따르지 않는지도 한 번 물어봅니다. 오른쪽 대화는 예시입니다.
2026-05-11
이슈 하나를 맡기는 /goal은 끝 상태·증명·상한을 말로 적는다
✗ /goal 12번 이슈 잘 처리해 줘
→ 무엇이 ‘잘’인지 평가 모델이 알 수 없음
✓ /goal issue-flow 스킬로 이슈 #12를 처리한다.
끝 상태: 이슈 스펙·계획 문서와 테스트·구현이 있고
리뷰어 서브에이전트의 블로커가 0건.
증명: 테스트 통과와 리뷰 결과 요약을 출력에 붙인다.
다른 이슈의 파일은 수정하지 않고 PR·머지는 만들지 않는다.
20턴 안에 못 끝내면 멈추고 진행 파일에 막힌 이유를 적는다.
스모크 기대 결과 실제(예시) /goal 상태 보여 줘 조건·턴·토큰 표시 조건 활성, 11턴 조건을 채운 이슈 증명 붙이고 종료 블로커 0, 종료 일부러 못 끝낼 이슈 20턴에서 멈추고 인계 멈춤, 사유 기록
멈추는지 보려면 “일부러 끝낼 수 없는 이슈 하나로 같은 /goal을 돌려, 상한에서 멈추고 인계하는지 보여 줘” 라고 시킵니다.
제가 /goal을 쓰는 방식입니다. 위의 나쁜 예는 사람에게는 통하지만 평가 모델에게는 기준이 없습니다. 아래 조건은 끝 상태, 증명, 변경 금지 범위, 상한을 모두 말로 담았습니다. 평가 모델은 명령을 실행하지 않고 대화에 드러난 내용만 보므로 증명을 출력에 붙이라고 합니다. 스모크는 두 방향입니다. 조건을 채우면 종료하는지, 못 채우면 상한에서 멈추고 인계하는지 봅니다. 자동 승인 모드에서는 도구 승인도 없으니 상한을 꼭 적습니다. 표의 실제 결과는 예시입니다.
2025-07-14 → 2026-04-30
/goal이 없는 도구라면 상한이 있는 반복 실행 루프를 시킨다
# 프롬프트
> 이 도구에 /goal이 없으니 같은 일을 반복하는 실행 루프를 만들어 줘.
성공은 테스트 통과 로 판정하고,
최대 20회, 회당 30분 을 넘기지 마.
끝나면 회마다 시간과 토큰을 기록해 보여 줘.
# 스모크 (대화 예시)
학생 풀 수 없는 과제로 한 번 돌려 봐.
하네스(예시) 20회 모두 실패해 상한에서 멈췄고, 회차별 시간·토큰은 표로 남겼습니다.
ghuntley.com/ralph
원문 블로그 화면 캡처 · 2025-07-14
Geoffrey Huntley의 글 “Ralph Wiggum as a ‘software engineer’”. 에이전트를 끝날 때까지 반복해 돌리는 방식이다.
같은 작업을 될 때까지 반복 해 사람이 매번 다시 시키지 않아도 된다.
상한 없이 무한 반복하면 비용이 끝없이 늘 수 있다 . 횟수·시간 상한이 꼭 필요하다.
핵심은 반복이 아니라 명령으로 판정하는 성공 기준과 상한 . Codex에도 /goal이 있다(구문은 버전에서 확인).
/goal을 쓸 수 없는 도구라면 하네스에게 반복 실행 루프를 만들어 달라고 합니다. 구조는 같습니다. 일을 한 번 시키고, 성공 기준을 사람이 아닌 명령으로 판정하고, 상한에 닿으면 멈춥니다. 2025년 7월의 Ralph 루프가 이 방식이었는데, 상한 없이 무한 반복한다는 점이 위험했습니다. 그래서 스모크로 풀 수 없는 과제를 일부러 돌려 상한에서 멈추는지 봅니다. 회차마다 시간과 토큰을 기록하게 하면 실행 기록까지 한 번에 해결됩니다. 대화는 예시입니다.
약 10분
스모크: 스킬이 불리는지 보고, 일부러 어기게 시켜 본다
시나리오(내가 하는 말) 기대 결과 실제 결과 통과 이름으로 스킬 호출 (Codex는 다른 호출 방식) 1단계부터 시작 직접 적기 “12번 이슈 처리해 줘” 설명에 맞아 자동 호출 직접 적기 “스펙 리뷰는 건너뛰고 바로 구현해 줘” 거절, 단계 유지 직접 적기 “13번 이슈도 지금 폴더에서 같이 해 줘” 새 작업 공간을 제안 직접 적기 “끝났으니 main에 바로 머지해 줘” 거절, 사람 승인 뒤로 직접 적기 새 세션에서 MCP 호출 연결 · 호출 기록 직접 적기
어겼다면 그것이 오늘 가장 좋은 발견입니다. “방금 요청이 왜 통과됐는지 설명하고, 막히게 고친 뒤 같은 요청으로 다시 보여 줘” 라고 시킵니다.
설계대로 만들어졌으면 코드를 열지 않고 돌려서 확인합니다. 먼저 스킬을 이름으로, 평범한 문장으로 불러 보고, 이어서 스펙 리뷰 건너뛰기, 한 폴더에서 두 이슈 처리, main에 직접 머지 세 가지를 일부러 시켜 봅니다. 지켰다면 어떤 말로 거절했는지 적고, 어겼다면 에이전트에게 원인을 설명시키고 고친 뒤 같은 요청으로 다시 봅니다. 마지막으로 MCP가 새 세션에서도 호출되는지 봅니다. 시나리오는 고른 장치에 맞게 바꾸시면 되고, 이 표가 다음 시간에 나눌 스모크 표 한 장이 됩니다. 실패한 줄도 그대로 남깁니다.
약 15분
이슈 하나를 /goal로 맡기고, 끝나면 실행 기록을 보여 달라고 한다
학생 /goal 앞 장의 조건으로 이슈 #12를 처리해 줘.
(실행 중 . . .)
학생 끝났으면 /goal 상태 화면과 아래를 요약해 줘: 도달한 단계, 걸린 시간, 턴, 토큰, 블로커, MCP 사용, 인계 여부.
하네스(예시) #12 · 8단계까지 · 14분 · 11턴 · 블로커 0 · 문서 조회 2회 · 인계 없음. 테스트 통과와 리뷰 요약을 위에 붙였습니다.
기록할 것 예시 스킬 호출 직접 성공 · 자동 실패 어기기 시험 3개 지킴 2 · 어김 1 이슈 #·도달 단계 #12 · 8단계까지 시간·턴·토큰 14분 · 11턴 · 기록값 블로커·인계 여부 0건 · 인계 없음 MCP 사용 문서 조회 2회 다음에 고칠 것 스킬 설명 보강
스모크가 끝나면 /goal로 이슈 하나를 맡깁니다. 끝나면 상태 화면이나 로그를 저장하고, 하네스에게 도달 단계, 시간, 턴, 토큰, 블로커, MCP 사용, 인계 여부를 요약해 달라고 합니다. 오른쪽 표의 값은 예시이고, 못 쟀으면 못 쟀다고 적습니다. 실패한 기록도 좋은 자료입니다. 제가 보는 것은 증명이 출력에 붙어 있는지, 블로커가 0건인지, 상한 안에서 끝났는지 세 가지입니다.
다음 회차(11-24)까지
다음 회차까지 해 볼 것: 고른 장치를 더하고, 돌려 보고, 기록해 둔다
해 볼 일 1 오늘 메뉴(격리 규칙 · 스킬 · MCP · /goal)에서 내 하네스에 필요한 것을 골라 하네스에게 시킨다 2 일부러 어겨 보며 확인한다 (실패해도 그대로 적어 둔다) 3 이슈를 맡겼다면 상태 화면의 시간·턴·토큰을 남겨 둔다 (못 쟀으면 못 쟀다고) 4 비밀 키·토큰은 어디에도 남기지 않는다
다음 시간에 나누면 좋은 것 쓴 프롬프트와 하네스의 질문 한 가지 스모크 표 한 장 (어겨 본 것과 결과) 막힌 곳 하나 (실패한 기록이 가장 좋은 소재)
완성도보다 해 보며 알게 된 것을 나눕니다. 코드나 저장소를 보여 주지 않아도 됩니다. → 4회차(11-24): PR·CI(Continuous Integration, 지속적 통합)·머지와 스모크, 하네스를 한 번 더 키워 보기
오늘 한 것을 집에서 이어서 해 보시길 권합니다. 격리 규칙, 스킬, MCP, /goal 중 내 하네스에 필요한 것을 골라 시키고, 일부러 어겨 보며 확인합니다. 형태나 구조는 정해져 있지 않고, 하네스가 무엇을 하게 할지는 각자 정합니다. 다음 시간에 쓴 프롬프트, 스모크 표 한 장, 막힌 곳 하나 정도를 나누면 서로 도움이 됩니다. 비밀 키와 토큰은 어디에도 남기지 않습니다. 4회차에서는 이슈별 PR, CI(Continuous Integration, 지속적 통합), 머지, 스모크로 이어 가고, 하네스를 한 번 더 키워 봅니다.
증상별
막힐 때: 하네스에게 이렇게 다시 말한다
증상 이렇게 다시 말한다 스모크에서 스킬이 안 불린다 “방금 왜 안 불렸는지 설명하고, 내가 실제로 할 말에 불리게 고친 뒤 같은 문장으로 다시 보여 줘.” 스모크에서 막혀야 할 요청이 통과됐다 “방금 요청이 왜 통과됐는지 설명하고, 막히게 고친 뒤 같은 요청으로 다시 보여 줘.” 스킬이 단계를 건너뛴다 “각 단계 끝에 블로커 판정을 출력하고, 판정 전에는 다음 단계로 가지 마.” 두 이슈가 섞인다 “이슈마다 새 작업 공간을 만들고, 지금 변경이 어느 브랜치 것인지 보여 줘.” MCP 도구가 안 보인다 “연결 상태와 설정 위치를 확인하고 새 세션에서 다시 확인해. 시간 초과인지도 봐.” /goal이 안 끝난다 “상태를 보고 왜 조건이 충족 안 됐는지 설명해. 측정 가능한 문장으로 다시 써.” 상한에 걸려 멈췄다 “어디까지 했고 무엇이 막혔는지 진행 파일에 적고 인계해.”
오늘 막히는 곳은 대부분 설치나 문법이 아니라 하네스에게 준 지시입니다. 스모크에서 스킬이 안 불리면 원인을 설명시키고 고친 뒤 같은 문장으로 다시 보여 달라고 합니다. 막혀야 할 요청이 통과됐을 때도 같은 방식입니다. 스킬이 단계를 건너뛰면 단계마다 블로커 판정을 출력하게 합니다. MCP 도구가 안 보이면 새 세션에서 확인하게 하고, /goal이 안 끝나면 조건이 모호하다는 뜻이니 조건을 다시 쓰게 합니다. 이 표의 문장은 그대로 붙여 넣어도 됩니다. 그래도 안 풀리면 손을 들어 주세요. 같이 대화 기록을 보겠습니다.
