이 레포가 무엇을 하는 물건인가.
당신이 에이전트에게 "날짜 선택기 만들어 줘"라고 하면, 보통 에이전트는 flatpickr를 설치하고 래퍼 컴포넌트를 만들고 스타일시트를 붙이고 타임존 논의를 시작한다. ponytail이 켜져 있으면 그 답은 <input type="date"> 한 줄이다.
즉 ponytail은 새 기능을 만드는 도구가 아니라, 에이전트가 "과하게 만드는 습관(over-engineering)"을 멈추게 하는 규칙이다. 게으름은 무책임이 아니라 효율이다 — "가장 좋은 코드는 애초에 쓰지 않은 코드다."
ponytail은 에이전트 행동 규칙 배포판(agent-portable ruleset)이다. 핵심 행동은 skills/ 안의 SKILL.md 몇 개에 담겨 있고, 나머지는 그 행동을 각 에이전트에 손쉽게 로드하기 위한 얇은 어댑터 파일들이다. 설정 파일이 필요 없고("Does it need a config file? No."), 설치 후 매 세션 자동으로 켜진다. 직접 실행되는 백엔드/서버가 아니라, 에이전트의 시스템 프롬프트에 규칙 텍스트를 끼워 넣는 방식으로 동작한다.
트렌딩 이유 · 다른 프롬프트/스킬 대비 장점.
AI 코딩 에이전트가 보편화되면서 새로운 골칫거리가 생겼다 — 에이전트는 "더 많이 쓰는 쪽"으로 편향돼 있다. 한 줄이면 될 일에 클래스를 만들고, 표준 라이브러리에 있는 걸 직접 구현하고, 의존성을 추가하고, 묻지도 않은 설정·추상화를 미리 깔아 둔다. ponytail은 이 "에이전트 비대증"을 규칙 한 장으로 억제하고, 그 효과를 실측 벤치마크로 증명했기 때문에 주목받는다.
이메일 검증기, JS 디바운스, CSV 합계, React 카운트다운, FastAPI 레이트리밋 — 다섯 가지 흔한 작업을 "스킬 없음(baseline) / caveman 스킬 / ponytail" 세 조건으로 돌려 코드 줄 수·비용·지연을 측정했다. 결과는 모든 모델에서 일관됐다.
| 지표 (5작업 합) | 스킬 없음 | caveman | ponytail |
|---|---|---|---|
| 코드 줄 수 (Sonnet) | 693줄 | 120줄 | 44줄 |
| 비용 USD (Sonnet) | $0.141 | $0.045 | $0.032 |
| 지연 초 (Sonnet) | 124.1s | 34.7s | 20.1s |
| 코드 줄 수 (Haiku) | 518줄 | 116줄 | 39줄 |
| 코드 줄 수 (Opus) | 256줄 | 67줄 | 51줄 |
요약하면 baseline 대비 코드 80~94% 감소, 비용 47~77% 절감, 속도 3~6배. 게다가 벤치마크는 correctness.js라는 정답 게이트를 둬서, 줄 수만 줄이고 실제로 동작하지 않는 "부서진 한 줄"은 탈락시킨다 — 즉 "게으른데 맞기까지" 한 것이다.
| 비교 항목 | 그냥 에이전트 | ponytail |
|---|---|---|
| 기본 성향 | 더 많이·더 화려하게 | 덜·단순·삭제 우선 |
| 설정 파일 | 도구마다 제각각 | 불필요(No config) |
| 지원 에이전트 | 도구별 락인 | 13개 에이전트 이식(Claude Code·Codex·Gemini·OpenCode·Cursor·Windsurf·Cline·Copilot·Copilot CLI·Kiro·Antigravity·VS Code·Pi) |
| 강도 조절 | 없음 | lite / full / ultra / off 4단계 |
| 검토 도구 | 일반 리뷰 | /ponytail-review(diff)·/ponytail-audit(전체 레포)·/ponytail-debt(기술 부채 ledger) |
| 효과 근거 | 주장 | 재현 가능한 벤치마크(promptfoo) |
단순히 "짧게 써"가 아니다. ponytail은 게으르게 굴면 안 되는 것을 명시한다 — 신뢰 경계의 입력 검증, 데이터 손실을 막는 에러 처리, 보안, 접근성, 그리고 사용자가 명시적으로 요구한 것. "lazy, not negligent(게으르되 부주의하지 않게)." 또 두 가지 표준 라이브러리 방식이 같은 길이라면 엣지 케이스에 더 정확한 쪽을 고른다. 게으름은 "더 부실한 알고리즘"이 아니라 "더 적은 코드"를 뜻한다.
"행동 규칙"이라는 비대칭적 산출물의 구성 요소.
ponytail은 일반적인 앱과 다르다. 무거운 런타임이 없고, 핵심 자산은 Markdown으로 쓴 규칙 텍스트다. 기술 스택은 "그 규칙을 각 에이전트에 어떻게 주입하느냐"의 접착제로 이뤄져 있다.
| 요소 | 역할 |
|---|---|
skills/ponytail/SKILL.md | ★ 핵심. "게으른 시니어" 행동 규칙 본문 — 사다리·규칙·출력형식·강도(lite/full/ultra). |
skills/ponytail-review/SKILL.md | diff 대상 과잉설계 리뷰. delete/stdlib/native/yagni/shrink 5개 태그로 한 줄씩 지적. |
skills/ponytail-audit/SKILL.md | 레포 전체를 훑어 "삭제·단순화 가능 목록"을 큰 절감 순으로 랭킹. |
skills/ponytail-help/SKILL.md | 모드·스킬·명령 빠른 참조 카드(1회성 출력). |
skills/ponytail-debt/SKILL.md | 코드에 주석으로 남긴 기술 부채를 수집해 ledger로 정리. |
AGENTS.md | 스킬을 못 읽는 에이전트용 압축 규칙. 모든 어댑터 사본의 단일 진실원. |
Claude Code·Codex·OpenCode에서는 규칙을 "항상 켜진 컨텍스트"로 끼워 넣어야 한다. 이 일을 순수 Node.js 스크립트(외부 의존성 0)가 한다.
| 요소 | 역할 |
|---|---|
hooks/ponytail-activate.js | SessionStart 훅. 활성 모드 플래그 기록 + 규칙을 숨은 컨텍스트로 방출 + 상태표시줄 설정 안내. |
hooks/ponytail-mode-tracker.js | UserPromptSubmit 훅. 사용자 입력에서 /ponytail ultra 같은 명령을 감지해 모드 전환·"stop ponytail" 해제. |
hooks/ponytail-config.js | 기본 모드 해석기 — 환경변수 > 설정파일 > full 순. XDG·Windows APPDATA 경로 처리. |
hooks/ponytail-instructions.js | SKILL.md를 읽어 현재 강도에 맞는 줄만 필터링해 규칙 텍스트를 생성(공유 빌더). |
hooks/ponytail-runtime.js | 모드 플래그 파일 읽기/쓰기 + Codex/Claude 출력형식 분기. |
hooks/ponytail-statusline.{sh,ps1} | 현재 모드 배지 [PONYTAIL:ULTRA]를 상태표시줄에 표시. |
| 요소 | 역할 |
|---|---|
| 플러그인 매니페스트 | .claude-plugin/(Claude Code), .codex-plugin/(Codex), gemini-extension.json, opencode.json. |
| 규칙 사본(얇은 어댑터) | .cursor/rules/·.windsurf/rules/·.clinerules/·.kiro/steering/·.github/copilot-instructions.md — 모두 AGENTS.md의 사본. |
| 슬래시 명령 | commands/*.toml(Claude·Gemini), .opencode/command/*.md(OpenCode). |
| Pi 패키지 | pi-extension/index.js + package.json(pi-package 키워드) — Pi 하니스용. |
| 일관성 검증 | scripts/check-rule-copies.js — 모든 어댑터 사본이 AGENTS.md와 동일한지 확인(드리프트 방지). |
| 벤치마크 | benchmarks/ — promptfoo 설정 + loc.js(줄 수)·correctness.js(정답 게이트). |
규칙 본문 1개 → 13개 에이전트로 퍼지는 "단일 진실원 + 어댑터" 구조.
ponytail의 진짜 설계는 코드가 아니라 배포 구조에 있다. 행동(behavior)은 skills/와 AGENTS.md에 한 번만 정의하고, 각 에이전트는 그것을 "로드하는 방법만 다른 얇은 어댑터"로 연결한다. 호스트가 스킬/훅을 지원하면 그대로 가리키고, 프로젝트 규칙 파일만 지원하면 AGENTS.md의 사본을 둔다. 이게 흩어지지 않도록 check-rule-copies.js가 모든 사본이 원본과 일치하는지 검사한다.
ponytail 규칙의 심장이다. 에이전트는 코드를 쓰기 전에 위에서부터 "성립하는 첫 번째 칸"에서 멈춘다. 두 칸이 다 되면 더 높은(게으른) 칸을 택하고 끝낸다 — 연구 프로젝트가 아니라 반사 신경이어야 한다.
같은 사다리를 얼마나 공격적으로 적용하느냐가 강도다. instructions.js가 SKILL.md에서 현재 모드에 해당하는 표 행/예시 줄만 골라내 주입한다(모드 키워드가 붙은 줄만 필터, 일반 규칙은 그대로 유지).
| 강도 | 전환 | 행동 |
|---|---|---|
| lite | /ponytail lite | 요청한 대로 만들되, 더 게으른 대안을 한 줄로 알려 줌. 선택은 사용자. |
| full | /ponytail | 기본값. 사다리 강제 — stdlib·네이티브 우선, 최단 diff, 최단 설명. |
| ultra | /ponytail ultra | YAGNI 극단주의. 추가보다 삭제. 한 줄짜리를 내고 요구사항 자체에 반문. |
| off | /ponytail off · "stop ponytail" | 비활성화. 플래그 파일 삭제, 규칙 주입 중단. |
| 패턴 | ponytail에서의 구현 |
|---|---|
| 단일 진실원 + 얇은 어댑터 | 행동은 SKILL.md/AGENTS.md 1곳, 호스트별 파일은 로드 방법만 다른 어댑터. |
| 드리프트 방지 게이트 | check-rule-copies.js가 사본들이 원본과 다르면 빌드 실패시킴. |
| 훅 기반 컨텍스트 주입 | SessionStart에 규칙 방출, UserPromptSubmit에 모드 명령 가로채기. |
| 설정 우선순위 폴백 | env > 설정파일 > full — 명시 없으면 항상 안전한 기본으로 수렴. |
| 강도별 텍스트 필터 | 한 SKILL.md에서 모드별 줄만 골라 주입(여러 파일 안 만듦 — 그 자체가 ponytail). |
| 증거 기반 주장 | 효과를 promptfoo 벤치마크 + 정답 게이트로 재현 가능하게 증명. |
| 경계 명시(안전선) | 입력검증·보안·접근성·명시 요청은 "게으름 예외"로 규칙에 못 박음. |
ponytail을 "여러 나라에 같은 가전을 파는 회사"로 보자. 가전 본체(행동 규칙)는 하나만 설계한다. 각 나라의 콘센트가 다를 뿐이라, 회사는 전원 어댑터(플러그)만 나라 수만큼 얇게 만든다. 가전을 나라마다 새로 설계하지 않는다. ponytail의 11개 어댑터가 바로 그 "플러그"고, 본체를 매번 베껴 쓰지 않게 check-rule-copies.js가 "모든 플러그가 같은 본체에 맞물리는지" 검사한다. 이것 자체가 "중복을 만들지 말라"는 ponytail 철학의 자기 적용이다(AGENTS.md 끝줄: "이 파일은 ponytail 레포 자신에게도 적용된다. 특히 더.").
대부분이 "어댑터 파일" — 핵심 행동은 skills/ 와 AGENTS.md 단 두 곳.
① AGENTS.md로 규칙의 정수(압축본)를 한눈에 → ② skills/ponytail/SKILL.md로 사다리·강도·출력형식 전체 → ③ hooks/ponytail-activate.js로 "어떻게 자동 주입되나" → ④ hooks/ponytail-instructions.js로 "강도별 줄 필터링" 트릭 → ⑤ scripts/check-rule-copies.js로 "사본 드리프트를 어떻게 막나" → ⑥ benchmarks/README.md로 효과 측정법. 설계 통찰은 이 여섯 곳에 다 있다.
"규칙을 배포 가능한 소프트웨어로 만드는 법"을 배운다.
ponytail의 SKILL.md는 좋은 행동 규칙 작성의 교과서다. ① 의사결정 절차(사다리)를 번호 목록으로 명시해 모호함을 없애고, ② 출력 형식을 강제("코드 먼저, 설명은 최대 3줄")하며, ③ 안티패턴을 구체 예시로 보여 준다(잘못된 장황한 리뷰 vs 한 줄 지적). 막연한 "잘 해 줘"가 아니라 측정 가능한 행동으로 번역한 점이 핵심이다.
"같은 내용을 11곳에 둬야 하는데 어떻게 안 어긋나게 하나?"는 실무에서 끝없이 마주치는 문제다(i18n 번역, 설정, 문서). ponytail의 답은 원본 1개 + 자동 동일성 검증이다. check-rule-copies.js는 AGENTS.md 본문에서 프론트매터·호스트별 군더더기를 정규화로 벗겨 낸 뒤 사본과 비교한다 — CI로 돌리면 "누가 한 곳만 고치고 나머지를 안 고친" 사고를 빌드 단계에서 잡는다.
Claude Code·Codex·OpenCode의 훅 시스템으로 "세션 시작 시 규칙 자동 주입", "사용자 입력 가로채 모드 전환"을 구현한 점을 보라. 훅은 외부 의존성 0의 순수 Node이고, 모든 실패를 조용히 삼킨다(Silent fail) — 훅이 깨져도 세션 시작 자체는 막지 않는 방어적 설계다. 이건 IDE 확장·git hook·CI 어디서나 쓰이는 패턴이다.
prompt 필드에 특정 명령이 있으면 플래그 파일을 쓰는 미니 UserPromptSubmit 훅을 짜고, JSON 파싱 실패 시에도 절대 크래시하지 않게 try/catch로 감싸 보라."우리 스킬이 코드를 줄여 준다"를 재현 가능한 실험으로 만든 점이 인상적이다. promptfoo로 동일 작업×모델×조건을 10회 반복하고, 줄 수는 측정만(항상 통과)·정답은 게이트(틀리면 실패)로 분리했다. "짧기만 하고 안 돌아가는 코드"를 정답 게이트가 걸러 낸다는 점이 평가 설계의 핵심 — 한 지표만 최적화하면 다른 지표가 망가지는 함정을 막는다.
설치는 거의 없다 — "그가 요구하는 가장 큰 수고"가 설치 한 줄이다.
| 항목 | 요구사항 |
|---|---|
| 지원 에이전트 | Claude Code·Codex(풀 플러그인+훅), Gemini CLI·OpenCode(규칙+명령), Cursor·Windsurf·Cline·Copilot·Kiro·Antigravity·VS Code(정적 규칙). |
| 런타임(훅용) | Node.js — 훅·플러그인 스크립트 실행용. 외부 npm 의존성 없음. |
| 설치(Claude Code) | /plugin marketplace add DietrichGebert/ponytail → /plugin install ponytail@ponytail, 훅 2개 trust. |
| 설치(Gemini CLI) | gemini extensions install https://github.com/DietrichGebert/ponytail. |
| 설치(Pi) | pi install git:github.com/DietrichGebert/ponytail. |
| 정적 규칙 호스트 | 해당 규칙 파일을 복사만 하면 됨(예: .cursor/rules/, ~/.kiro/steering/). |
| 기본 모드 설정 | 환경변수 PONYTAIL_DEFAULT_MODE 또는 config.json의 defaultMode. 미설정 시 full. |
| 벤치마크 재현(선택) | ANTHROPIC_API_KEY + npx promptfoo eval -c benchmarks/promptfooconfig.yaml --repeat 10. |
훅 스크립트가 외부 npm 패키지를 전혀 쓰지 않고 Node 표준 모듈(fs·path·os)만으로 동작하는 건 우연이 아니다. "새 의존성을 피할 수 있으면 피하라"는 자기 규칙을 레포 스스로 지킨 결과다. 설정 파일도 기본적으로 필요 없다("Does it need a config file? No.").
난이도별 5단계 — 규칙을 설치·체감하고, 직접 만들어 보기까지.
examples/의 date-picker.md·caching.md를 읽고, "ponytail 없는 답"과 "ponytail 답"이 각각 몇 줄·몇 파일·몇 의존성인지 직접 세어 표로 정리한다. "어떤 안전선(검증·보안)은 그대로 남았는가"도 표시해 본다.
사용 중인 에이전트(Claude Code·Cursor 등)에 ponytail을 설치한 뒤, 같은 요청("캐시 추가해 줘")을 /ponytail lite → full → ultra로 바꿔 가며 던지고 응답 길이·태도 차이를 기록한다. off로 끈 baseline과도 비교.
자신의 프로젝트에 /ponytail-audit(또는 AGENTS.md 규칙을 붙여 일반 에이전트에)로 과잉설계 감사를 돌린다. delete/stdlib/native/yagni/shrink 태그별로 나온 지적 중 실제로 한 건을 직접 리팩터링해 줄 수가 얼마나 줄었는지 확인한다.
ponytail 구조를 모방해 자신의 규칙(예: "주석 최소화 모드", "타입 우선 모드")을 SKILL.md 1개 + AGENTS.md 압축본 + 호스트별 사본 1~2개로 만든다. check-rule-copies.js를 본떠 사본 동일성 검증 스크립트도 붙인다.
benchmarks/를 참고해, 과제 4에서 만든 규칙의 효과를 측정하는 promptfoo 설정을 짠다. 작업 3~5개 × 조건 2개(규칙 on/off)를 반복 실행하고, 측정 지표(줄 수 등)와 정답 게이트를 분리해 "짧지만 동작하는가"를 동시에 확인한다.
6주 코스 — 소프트웨어 단순성 철학부터 에이전트 규칙 배포·평가까지.
| 주차 | 주제 | 실습 · 참고 |
|---|---|---|
| 1주차 | 단순성 철학 — YAGNI·KISS·"필요한 만큼만" | AGENTS.md 정독 · examples/ 전부 읽고 before/after 분석 |
| 2주차 | 프롬프트/규칙 설계 — 행동을 절차로 명세 | skills/ponytail/SKILL.md · 사다리·출력형식 모방해 직접 작성 |
| 3주차 | 에이전트 훅 시스템 — 생애주기 주입 | hooks/*.js · SessionStart/UserPromptSubmit 미니 훅 구현 |
| 4주차 | 다중 타깃 배포 — 단일 진실원 + 어댑터 | docs/agent-portability.md · check-rule-copies.js 분석 |
| 5주차 | 코드 리뷰 자동화 — 과잉설계 탐지 | ponytail-review/audit 태그 체계 · 내 레포 감사·리팩터 |
| 6주차 | LLM 평가(eval) — 재현 가능한 측정·정답 게이트 | promptfoo · benchmarks/correctness.js · 나만의 벤치마크 |
본문·소스에 나온 용어 빠른 참조.
| 용어 | 의미 |
|---|---|
| ponytail | AI 코딩 에이전트에 "게으른 시니어 개발자" 행동 규칙을 주입하는 배포판. |
| over-engineering | 필요 없는 유연성·추상화·의존성으로 코드를 복잡하게 만드는 것. ponytail의 박멸 대상. |
| YAGNI | "You Aren't Gonna Need It" — 미래 가정만으로 코드를 추가하지 말라는 원칙. 사다리 1칸. |
| the ladder (사다리) | 코드 쓰기 전 멈추는 6칸: YAGNI → stdlib → 네이티브 → 기존 의존성 → 한 줄 → 최소 코드. |
| lite / full / ultra / off | 강도 4단계. full이 기본, ultra는 YAGNI 극단주의, off는 비활성화. |
| ponytail-review | diff의 과잉설계만 잡는 리뷰. delete/stdlib/native/yagni/shrink 5태그. |
| ponytail-audit | 레포 전체를 훑어 "삭제·단순화 목록"을 큰 절감 순으로 랭킹. |
| SKILL.md | 스킬 본문 파일. 프론트매터(name·description) + 행동 규칙 본문. |
| AGENTS.md | 스킬 미지원 에이전트용 압축 규칙. 모든 어댑터 사본의 단일 진실원. |
| hook (훅) | 세션 시작·입력 제출 등에 자동 실행되는 스크립트. ponytail은 규칙 주입·모드 추적에 사용. |
| SessionStart / UserPromptSubmit | 각각 "세션 시작 시"·"사용자 입력 제출 시" 발화하는 Claude Code 훅 이벤트. |
| single source of truth | 같은 정보를 한 곳에서만 정의하는 원칙. ponytail은 행동을 SKILL.md/AGENTS.md에만 둔다. |
| adapter (어댑터) | 핵심 행동을 각 호스트에 로드하기 위한 얇은 연결 파일(플러그인 매니페스트·규칙 사본 등). |
| drift (드리프트) | 사본들이 시간이 지나 원본과 어긋나는 현상. check-rule-copies.js가 차단. |
| ponytail: 주석 | 의도적 단순화임을 표시하는 코드 주석. 한계가 있으면 그 한계와 업그레이드 경로까지 명시. |
| promptfoo | LLM 출력을 작업·모델·조건별로 반복 평가하는 도구. ponytail 벤치마크의 기반. |
| correctness gate | 생성 코드가 실제로 동작하는지 검사하는 게이트. "짧지만 안 도는 코드"를 탈락. |
| caveman | 벤치마크 비교군으로 쓰인 또 다른 간결화 스킬. ponytail이 더 적은 코드를 만듦. |