On this page목차
1 · Start here
1 · 여기부터
New here? Read this first처음 오셨나요? 이것부터 읽으세요
/supergoal is an agent skill - a set of instructions your AI coding agent loads when you type /supergoal. It does not replace your agent; it gives it a disciplined way to work.
/supergoal은 에이전트 스킬입니다. /supergoal이라고 입력하면 AI 코딩 에이전트가 불러오는 지침 묶음이죠. 에이전트를 대체하는 게 아니라, 에이전트가 규율 있게 일하도록 방식을 바꿔 줍니다.
What is an "agent skill"?"에이전트 스킬"이 뭔가요?
Tools like Claude Code, Codex, and agy let you drop in reusable instruction packs called skills. /supergoal is one such pack. When you invoke it, the agent follows supergoal's playbook for that task instead of just editing files ad hoc.
Claude Code, Codex, agy 같은 도구는 재사용 가능한 지침 묶음(스킬)을 끼워 넣을 수 있습니다. /supergoal이 그런 묶음 중 하나예요. 이걸 부르면 에이전트가 즉흥적으로 파일을 고치는 대신 supergoal의 작업 지침을 따릅니다.
Who is it for?누구를 위한 건가요?
Developers who already use an AI coding agent and want it to stop declaring "done" when it isn't. If an agent has ever told you "tests pass" on a change that was actually broken or incomplete, that is the exact gap supergoal is built to close.
이미 AI 코딩 에이전트를 쓰면서, 에이전트가 끝나지도 않았는데 "완료"라고 말하는 걸 막고 싶은 개발자를 위한 것입니다. 실제로는 깨졌거나 덜 끝난 변경인데 에이전트가 "테스트 통과"라고 했던 경험이 있다면, 바로 그 틈을 메우려고 만든 스킬입니다.
The 30-second version30초 요약
- Route the objective - it reads your request and picks the right workflow (build, fix a bug, add to legacy code, spec, QA, and more).경로 선택 - 요청을 읽고 알맞은 작업 방식을 고릅니다 (새로 만들기, 버그 고치기, 기존 코드에 추가, 설계, QA 등).
- Change the smallest correct amount - it matches your existing code and does not rewrite whole files to touch a few lines.최소한만 변경 - 기존 코드 스타일에 맞추고, 몇 줄 바꾸려고 파일 전체를 다시 쓰지 않습니다.
- Verify against ground truth - a fresh reviewer re-runs your real tests and re-reads the request/docs, ticking off only what is actually proven.실체로 검증 - 새로운 검토자가 프로젝트의 실제 테스트를 다시 돌리고 요청/문서를 다시 읽어, 정말로 증명된 것만 체크합니다.
- Stop at the verified result - no endless refactor, no made-up checklist, no fake green.검증된 결과에서 멈춤 - 끝없는 리팩터링도, 스스로 지어낸 체크리스트도, 가짜 통과도 없습니다.
A plain agent trusts the green checkmark. supergoal distrusts it and proves the result independently before it stops.
보통 에이전트는 초록색 통과 표시를 믿습니다. supergoal은 그걸 의심하고, 멈추기 전에 결과를 독립적으로 증명합니다.
2 · The core idea
2 · 핵심 아이디어
Don't trust green초록불을 그대로 믿지 마라
Everything in supergoal comes from one belief: passing tests is not the same as being correct. Tests only check what someone remembered to write down. The request, the docs, and the edge cases usually say more.
supergoal의 모든 것은 한 가지 믿음에서 나옵니다. 테스트 통과가 곧 정답은 아니다. 테스트는 누군가 적어 둔 것만 확인합니다. 요청, 문서, 예외 상황이 대개 그보다 더 많은 것을 담고 있죠.
The writer and the editor작가와 편집자
Think of two people. The writer is deep in the work and can be fooled by their own assumptions - "I meant it to do that, so it must." The editor reads the same work fresh, with no attachment to how it was made, and tries to poke holes. They sign off only on what actually holds up.
두 사람을 떠올려 보세요. 작가는 작업에 깊이 빠져 있어서 자기 가정에 속기 쉽습니다 - "이렇게 하려던 거니까 맞겠지." 편집자는 같은 글을 처음 보는 눈으로, 어떻게 썼는지에 얽매이지 않고 허점을 찾습니다. 그리고 실제로 버티는 것만 통과시키죠.
supergoal builds this separation into every code run: one role builds the change, and a different role - with a fresh, empty context that never saw the building happen - audits it. The auditor cannot be fooled by the builder's assumptions because it does not share them.
supergoal은 코드 작업마다 이 분리를 심어 둡니다. 한 역할이 변경을 만들고(Build), 만드는 과정을 전혀 보지 않은 새롭고 빈 컨텍스트를 가진 다른 역할이 그것을 감사(Audit)합니다. 감사자는 작성자의 가정을 공유하지 않으므로 거기에 속지 않습니다.
Ground truth, never a proxy대충 만든 기준이 아니라, 실체로
A tempting shortcut is for the agent to write its own checklist and grade itself against it. That is a proxy - and an agent can unconsciously shape the work to pass its own checklist while missing the real point (this trap has a name: Goodhart's law). supergoal refuses this. It grades only against ground truth: your project's real test suite and the actual request and docs.
에이전트가 스스로 체크리스트를 만들고 거기에 맞춰 자기 점수를 매기는 건 솔깃한 지름길입니다. 하지만 그건 대리 지표(proxy)일 뿐이고, 에이전트는 무의식적으로 자기 체크리스트를 통과하도록 작업을 맞추면서 정작 진짜 목적을 놓칠 수 있습니다 (이 함정엔 이름도 있습니다: 굿하트의 법칙). supergoal은 이를 거부합니다. 오직 실체(ground truth), 즉 프로젝트의 실제 테스트 스위트와 원래의 요청·문서에만 비추어 채점합니다.
supergoal deliberately stays lean. The bar it measures against is "a strong model that actually read the real spec." It adds only the few checks a rushed pass tends to skip - a reviewed plan, a builder that must exit green, and an independent verify - not a pile of gates for their own sake.
supergoal은 일부러 가볍게 유지합니다. 기준선은 "실제 스펙을 제대로 읽은 좋은 모델"입니다. 급하게 지나가는 작업이 놓치기 쉬운 몇 가지, 즉 검토된 계획, 반드시 통과 상태로 끝나야 하는 빌더, 독립적인 검증만 더합니다. 형식을 위한 게이트 더미가 아닙니다.
3 · Install
3 · 설치
Install in 3 steps3단계로 설치
This repository is the skill - there is nothing to compile. You put it where your agent looks for skills, then invoke it. The clean way is one canonical copy, symlinked into each agent.
이 저장소가 곧 스킬입니다. 컴파일할 것이 없어요. 에이전트가 스킬을 찾는 위치에 두고 부르기만 하면 됩니다. 깔끔한 방법은 원본 하나를 두고 각 에이전트에 심볼릭 링크로 연결하는 것입니다.
Step 1 - Clone1단계 - 클론
# download the skill once, anywhere you keep code
git clone https://github.com/cskwork/supergoal-skill.git
cd supergoal-skill
SRC="$(pwd)"
# 스킬을 한 번만 내려받습니다 (코드를 두는 곳 어디든)
git clone https://github.com/cskwork/supergoal-skill.git
cd supergoal-skill
SRC="$(pwd)"
Step 2 - Link it into your agent(s)2단계 - 에이전트에 연결
Create the skills folder for whichever agents you use, then symlink. A symlink means updating the skill later is just git pull in the source - every agent sees it.
사용하는 에이전트의 스킬 폴더를 만든 뒤 심볼릭 링크를 겁니다. 링크로 연결해 두면 나중에 업데이트는 원본에서 git pull 한 번이면 되고, 모든 에이전트에 반영됩니다.
mkdir -p ~/.claude/skills ~/.codex/skills ~/.agents/skills ln -s "$SRC" ~/.claude/skills/supergoal # Claude Code ln -s "$SRC" ~/.codex/skills/supergoal # Codex ln -s "$SRC" ~/.agents/skills/supergoal # agy / other CLIs
mkdir -p ~/.claude/skills ~/.codex/skills ~/.agents/skills ln -s "$SRC" ~/.claude/skills/supergoal # Claude Code ln -s "$SRC" ~/.codex/skills/supergoal # Codex ln -s "$SRC" ~/.agents/skills/supergoal # agy / 기타 CLI
Step 3 - Use it3단계 - 사용
# in your agent CLI, hand it one objective: /supergoal build a CLI todo app in Python and ship it
# 사용하는 에이전트 CLI에서 목표 하나를 넘깁니다: /supergoal 파이썬으로 CLI 할 일 앱 만들고 배포해줘
Optional but recommended - confirm the install is healthy and not drifting from the source:
선택 사항이지만 권장 - 설치본이 원본과 어긋나지 않았는지 확인합니다:
# read-only drift check for an active install node templates/skill-install-audit.mjs "$SRC" # run the repo's own contract tests bash tests/run-all.sh
# 활성 설치본이 원본과 어긋났는지 읽기 전용으로 점검 node templates/skill-install-audit.mjs "$SRC" # 저장소 자체 계약 테스트 실행 bash tests/run-all.sh
The skill runs on Windows, but the gate/test scripts are POSIX shell - run them under Git Bash or WSL with node on your PATH. If symlinks need admin rights, install by copy (cp -R) and re-run the audit script after copying.
스킬 자체는 Windows에서 동작하지만, 게이트/테스트 스크립트는 POSIX 셸이라 Git Bash나 WSL에서 실행해야 하고 node가 PATH에 있어야 합니다. 심볼릭 링크에 관리자 권한이 필요하면 복사(cp -R)로 설치한 뒤, 복사 후 감사 스크립트를 다시 실행하세요.
4 · Your first run
4 · 첫 실행
Your first run, walked through첫 실행, 한 걸음씩
Say you type this into your agent. Here is what actually happens, and the two moments where you are in control.
에이전트에 아래처럼 입력했다고 해 봅시다. 실제로 무슨 일이 벌어지는지, 그리고 여러분이 결정권을 쥐는 두 순간을 짚어 봅니다.
/supergoal build a CLI todo app in Python and ship it
/supergoal 파이썬으로 CLI 할 일 앱 만들고 배포해줘
It states the mode모드를 선언합니다
First line back is something like Mode: GREENFIELD. "Building a new thing" routes to the GREENFIELD lane. It always tells you the lane it picked in one line.
첫 응답은 Mode: GREENFIELD 같은 한 줄입니다. "새로 만들기"는 GREENFIELD 경로로 갑니다. 어떤 경로를 골랐는지 항상 한 줄로 알려 줍니다.
It writes down the goal목표를 글로 적습니다
It creates GOAL.md: your request quoted word for word, a refined spec, and a checklist of Success Criteria - including edge cases you did not spell out (empty list, duplicate item, bad input). This is where hidden requirements surface.
GOAL.md를 만듭니다. 여러분의 요청을 토씨 그대로 인용하고, 다듬은 스펙과 성공 기준 체크리스트를 적습니다. 여러분이 말하지 않은 예외 상황(빈 목록, 중복 항목, 잘못된 입력)까지 포함됩니다. 숨은 요구사항이 드러나는 지점이죠.
It freezes a plan and STOPS for your OK계획을 확정하고, 승인을 기다리며 멈춥니다
It writes PLAN.md (the steps, the tools, how it will verify) and waits. Build does not start until you approve. Read it, adjust anything, then say OK.
PLAN.md(단계, 사용할 도구, 검증 방법)를 적고 기다립니다. 여러분이 승인하기 전에는 Build가 시작되지 않습니다. 읽어 보고, 고칠 것이 있으면 고친 뒤 OK 하세요.
A fresh builder implements it새 빌더가 구현합니다
A separate role with a clean context reads only the approved plan and builds the smallest correct change, test-first. It will not finish until the test suite is green.
깨끗한 컨텍스트를 가진 별도 역할이 승인된 계획만 읽고, 테스트부터 작성하며 최소한의 올바른 변경을 만듭니다. 테스트 스위트가 통과 상태가 되기 전에는 끝내지 않습니다.
Runs as: the executor / builder 담당: executor(빌더)A fresh auditor tries to disprove it새 감사자가 반증을 시도합니다
Another clean-context role re-runs your real tests, compares the change against GOAL.md, and ticks only what is proven. Anything unmet goes to R-LOOP.md and the builder is relaunched to fix it. This loop is capped (3 rounds by default) before it escalates to you.
또 다른 깨끗한 컨텍스트 역할이 여러분의 실제 테스트를 다시 돌리고, 변경을 GOAL.md와 대조해 증명된 것만 체크합니다. 충족되지 않은 항목은 R-LOOP.md로 가고, 빌더가 다시 실행되어 고칩니다. 이 반복은 기본 3회로 제한되며, 그 후엔 여러분에게 넘깁니다.
It finalizes and stops마무리하고 멈춥니다
When every box is checked, it writes Z-<date>.md (the "done" stamp with the branch and timestamp), passes the commit gate, and stops - reporting exactly what it verified, with the command output.
모든 항목이 체크되면 Z-<날짜>.md(브랜치와 타임스탬프가 담긴 "완료" 도장)를 쓰고, 커밋 게이트를 통과한 뒤 멈춥니다. 무엇을 검증했는지 명령 출력과 함께 정확히 보고합니다.
Only two things interrupt you: (1) approving the plan before any code is written, and (2) consenting to any destructive or irreversible step (like a force-push or dropping data). Everything else runs on its own.
여러분을 멈춰 세우는 건 딱 두 가지입니다. (1) 코드를 쓰기 전 계획 승인, (2) 파괴적이거나 되돌릴 수 없는 단계(force-push, 데이터 삭제 등)에 대한 동의. 나머지는 알아서 진행됩니다.
5 · The loop
5 · 루프
The five-gate loop5단계 게이트 루프
Every code-changing run (build, debug, legacy) flows through the same five gates. "Gate" just means a checkpoint the run must pass before moving on.
코드를 바꾸는 모든 작업(새로 만들기, 디버그, 레거시)은 같은 다섯 게이트를 지납니다. "게이트"는 다음으로 넘어가기 전에 반드시 통과해야 하는 체크포인트를 뜻합니다.
Frame -> Plan approval -> Build -> Exact Verify/QA -> Finalize
| | | | |
write you OK fresh fresh "done" stamp
GOAL.md the plan builder auditor + commit gate
(blocking) (green) (real tests)
Frame -> Plan approval -> Build -> Exact Verify/QA -> Finalize | | | | | GOAL.md 여러분 OK 새 빌더 새 감사자 "완료" 도장 작성 (여기서 멈춤) (통과 필수) (실제 테스트) + 커밋 게이트
| Gate게이트 | What happens하는 일 | Who / your part담당 / 여러분의 역할 | Writes남기는 파일 |
|---|---|---|---|
| 1. Frame | Understand the real goal. Quote the request, refine the spec, list falsifiable success criteria including edge cases.진짜 목표를 이해합니다. 요청을 인용하고 스펙을 다듬으며, 예외 상황을 포함한 반증 가능한 성공 기준을 나열합니다. | The conductor. You: nothing yet.컨덕터. 여러분: 아직 없음. | GOAL.md |
| 2. Plan approval | A self-sufficient plan is frozen. This gate blocks - Build cannot start until it is approved.자체 완결적인 계획이 확정됩니다. 이 게이트는 막아섭니다 - 승인 전에는 Build가 시작되지 않습니다. | You: read and approve (or adjust).여러분: 읽고 승인(또는 수정). | PLAN.md |
| 3. Build | A fresh-context builder implements only the approved plan, test-first, and exits only on a green suite.새 컨텍스트 빌더가 승인된 계획만 구현합니다. 테스트부터 쓰고, 스위트가 통과할 때만 끝냅니다. | The executor. You: nothing.executor. 여러분: 없음. | the code + tests코드 + 테스트 |
| 4. Exact Verify/QA | A fresh auditor re-runs the real tests, re-reads request/docs, ticks proven criteria. Gaps relaunch the builder.새 감사자가 실제 테스트를 다시 돌리고 요청/문서를 다시 읽어, 증명된 기준만 체크합니다. 미충족 항목은 빌더를 다시 부릅니다. | The qa-auditor (+ a qa-tester for browser/CLI evidence). You: nothing.qa-auditor (+ 브라우저/CLI 증거가 필요하면 qa-tester). 여러분: 없음. | QA.md, R-LOOP.md |
| 5. Finalize | Only when every box is checked: write the completion marker, pass the commit gate, merge after acceptance.모든 항목이 체크된 뒤에만: 완료 마커를 쓰고 커밋 게이트를 통과하며, 수락 후 병합합니다. | You: accept; consent for destructive steps.여러분: 수락, 파괴적 단계엔 동의. | Z-<date>.md |
Each role starts empty and loads only the file its phase needs. The builder never sees the auditor's doubts; the auditor never sees the builder's rationalizations. That separation is what makes the verify honest - and it keeps each role's attention on one job instead of a bloated history.
각 역할은 빈 상태로 시작해 해당 단계에 필요한 파일만 불러옵니다. 빌더는 감사자의 의심을 보지 못하고, 감사자는 빌더의 자기 합리화를 보지 못합니다. 바로 그 분리가 검증을 정직하게 만들고, 각 역할이 비대해진 맥락에 휘둘리지 않고 한 가지 일에만 집중하게 합니다.
6 · The run vault
6 · 실행 볼트
The run vault - the paper trail실행 볼트 - 작업의 기록장
A code run keeps a small set of Markdown files in a dated folder (a "run vault"). Think of it as a lab notebook: it records what was asked, the agreed plan, what was checked, what failed, and the final sign-off. You can read every file - nothing is hidden.
코드 작업은 날짜가 붙은 폴더("실행 볼트")에 작은 Markdown 파일 묶음을 남깁니다. 실험 노트라고 생각하세요. 무엇을 요청했는지, 어떤 계획에 합의했는지, 무엇을 확인하고 무엇이 실패했는지, 최종 승인까지 기록합니다. 모든 파일을 읽을 수 있고 숨기는 것은 없습니다.
<run vault>/ # a dated folder, e.g. docs/changelog/<YYYY-MM>/<DD-topic>/ GOAL.md request word-for-word + spec + success-criteria checkboxes PLAN.md the frozen plan -> your explicit OK QA.md Before/After evidence as plain checklist sentences R-LOOP.md verify gaps -> the builder is relaunched to fix them Z-<date>.md written ONLY when every box is checked (the "done" stamp) run-state.json resumable state so a run can pick up where it left off
<run vault>/ # 날짜가 붙은 폴더, 예: docs/changelog/<YYYY-MM>/<DD-topic>/ GOAL.md 요청 원문 그대로 + 스펙 + 성공 기준 체크박스 PLAN.md 확정된 계획 -> 여러분의 명시적 OK QA.md 이전/이후 증거를 평이한 체크리스트 문장으로 R-LOOP.md 검증 미충족 -> 빌더를 다시 불러 수정 Z-<date>.md 모든 항목이 체크됐을 때만 작성 ("완료" 도장) run-state.json 중단 지점부터 재개할 수 있는 상태
| File파일 | In plain terms쉽게 말하면 |
|---|---|
GOAL.md | The single source of truth for "what done means." Your request is quoted exactly so it cannot drift, then broken into checkable success criteria."완료란 무엇인가"의 유일한 기준입니다. 여러분의 요청을 그대로 인용해 변질되지 않게 하고, 확인 가능한 성공 기준으로 쪼갭니다. |
PLAN.md | The agreed approach, frozen before any code. This is what you approve at gate 2.코드 작성 전에 확정된 합의된 접근법입니다. 게이트 2에서 여러분이 승인하는 대상이죠. |
QA.md | The evidence: what the state was Before, what it is After, and the commands that prove it.증거입니다. 이전(Before) 상태, 이후(After) 상태, 그리고 그것을 증명하는 명령어를 담습니다. |
R-LOOP.md | The fix channel. When the auditor finds an unmet criterion, it lands here with a timestamp and the builder is sent back in.수정 통로입니다. 감사자가 미충족 기준을 찾으면 타임스탬프와 함께 여기에 적히고, 빌더가 다시 투입됩니다. |
Z-<date>.md | The completion marker. Its existence means every success criterion is green - it is written last, never early.완료 마커입니다. 이 파일이 있다는 건 모든 성공 기준이 통과했다는 뜻이며, 항상 마지막에 쓰입니다. |
For throwaway or single-task workspaces (like a CI checkout or a quick benchmark), supergoal uses a fast path: the same five gates apply, but the state is held in the conversation instead of written to files. That is expected, not a bug - the ceremony only appears when it has a real consumer.
일회성이거나 단일 작업용 작업공간(CI 체크아웃, 빠른 벤치마크 등)에서는 supergoal이 빠른 경로(fast path)를 씁니다. 같은 다섯 게이트를 적용하되, 상태를 파일이 아니라 대화 안에 담아 둡니다. 버그가 아니라 의도된 동작입니다. 형식은 실제로 쓸 대상이 있을 때만 나타납니다.
7 · The roles
7 · 역할들
The roles - who does what역할들 - 누가 무엇을 하나
A code run is not one agent doing everything. It is a small cast, each with a fresh, separate context. Keeping them separate is the whole point (see the writer/editor idea above). Keeping the cast small keeps it fast.
코드 작업은 한 에이전트가 전부 하는 게 아닙니다. 각자 새롭고 분리된 컨텍스트를 가진 작은 팀이 합니다. 이들을 분리하는 것이 핵심이고(위의 작가/편집자 비유 참고), 팀을 작게 유지해 빠르게 만듭니다.
| Role역할 | Persona file지침 파일 | Job하는 일 |
|---|---|---|
| Conductor컨덕터 | SKILL.md | Reads your objective, picks the mode, sets up the run, and dispatches the roles below. Stays lean.목표를 읽고 모드를 고르며, 작업을 설정하고 아래 역할들을 파견합니다. 가볍게 유지합니다. |
| Builder빌더 | agents/executor.md | Implements the smallest correct change from the approved plan, test-first. Must exit green.승인된 계획을 바탕으로 테스트부터 쓰며 최소한의 올바른 변경을 구현합니다. 통과 상태로 끝내야 합니다. |
| Tester테스터 | agents/qa-tester.md | Only for browser/CLI work. Drives the real thing, captures evidence (screenshots, output). Reports evidence, no verdict.브라우저/CLI 작업에만 해당. 실제로 조작해 증거(스크린샷, 출력)를 수집합니다. 증거만 보고하고 판정은 하지 않습니다. |
| Auditor감사자 | agents/qa-auditor.md | The final verifier. Adversarial stance: re-runs real tests, diffs against GOAL.md, owns the verdict and the GOAL ticks.최종 검증자. 반증하려는 자세로 실제 테스트를 다시 돌리고 GOAL.md와 대조하며, 판정과 GOAL 체크를 담당합니다. |
| Escalation reviewer에스컬레이션 리뷰어 | agents/code-reviewer.md | Opt-in only, for under-specified or risky work - the "plan attack." Not part of the default path.불충분하거나 위험한 작업에만 선택적으로 투입되는 "계획 공격". 기본 경로에는 없습니다. |
The default delivery cast is just one builder + one auditor per iteration, plus a tester only when there is a browser or CLI to drive. Other personas (analyst, architect, designer, debugger, explore, db-reader, security-reviewer) load only when a mode calls for them.
기본 딜리버리 팀은 반복마다 빌더 1명 + 감사자 1명이 전부이고, 조작할 브라우저나 CLI가 있을 때만 테스터가 추가됩니다. 다른 페르소나(analyst, architect, designer, debugger, explore, db-reader, security-reviewer)는 해당 모드가 필요로 할 때만 불러옵니다.
Every role is a plain file in agents/. That is why dispatch works the same across Claude Code, Codex, agy, and other agent CLIs - supergoal is not tied to any one tool.
모든 역할은 agents/ 안의 일반 파일입니다. 그래서 Claude Code, Codex, agy 등 어떤 에이전트 CLI에서도 같은 방식으로 역할을 파견할 수 있습니다. supergoal은 특정 도구에 묶여 있지 않습니다.
8 · The modes
8 · 모드
One command, twelve modes명령 하나, 열두 가지 모드
You never pick a mode by hand. supergoal reads your objective and routes to the right lane, then tells you which one in one line. Three modes change code and use the full five-gate loop; the other nine write no product code by default and confirm before installing anything.
모드를 직접 고를 필요가 없습니다. supergoal이 목표를 읽고 알맞은 경로로 보낸 뒤, 어떤 경로인지 한 줄로 알려 줍니다. 세 모드는 코드를 바꾸며 5단계 루프를 쓰고, 나머지 아홉은 기본적으로 제품 코드를 쓰지 않으며 무언가를 설치하기 전에 확인을 받습니다.
Code-changing (use the full loop)코드를 바꾸는 모드 (전체 루프 사용)
GREENFIELD
Build and ship a new app or tool. Broad requests first get a mini map, then one slice enters Build.
새 앱이나 도구를 만들어 출시합니다. 넓은 요청은 먼저 지도를 그린 뒤 한 조각만 Build로 들어갑니다.
/supergoal build a habit tracker and ship it /supergoal 습관 추적 앱 만들어서 배포해줘DEBUG
Fix a hard failure. Reproduce it with a failing test first, then make the smallest change that turns it green.
까다로운 실패를 고칩니다. 먼저 실패하는 테스트로 재현한 뒤, 통과시키는 가장 작은 변경을 만듭니다.
/supergoal checkout hangs in prod, fix it /supergoal 결제 페이지가 가끔 멈춰, 고쳐줘LEGACY
Add to or refactor existing code. Map the touched area first, then make the smallest accurate edit.
기존 코드에 기능을 더하거나 리팩터링합니다. 영향 범위를 먼저 파악한 뒤 가장 작고 정확하게 수정합니다.
/supergoal add SSO to our legacy Django app /supergoal 레거시 장고 앱에 SSO 추가해줘No-code (plan, verify, learn - no product code by default)코드 없는 모드 (계획·검증·학습 - 기본적으로 제품 코드 없음)
WAYFINDER
Spec and split a big, foggy effort into tickets with blockers, and say what to do first.
크고 막연한 작업을 블로커가 있는 티켓들로 나누고, 무엇부터 할지 정합니다.
/supergoal break this migration into tickets /supergoal 이 마이그레이션을 티켓으로 쪼개줘PROTOTYPE
Test one uncertain direction with a throwaway proof, then delete it or route the decision into delivery.
불확실한 방향 하나를 한 번 쓰고 버릴 증명으로 검증한 뒤, 삭제하거나 결정만 딜리버리로 넘깁니다.
/supergoal prototype 3 checkout flows first /supergoal 결제 흐름 3가지 먼저 프로토타입QA-ONLY
QA or compare data with no code change. Builds an "Impact Matrix" of everything a feature can affect.
코드 변경 없이 QA하거나 데이터를 비교합니다. 기능이 영향을 줄 수 있는 모든 것의 "영향 매트릭스"를 만듭니다.
/supergoal QA the checkout flow on staging /supergoal 스테이징에서 결제 흐름 QA해줘REVIEW-ONLY
Review a diff or PR with no fixes. Two independent reviewers; every finding is verified before it is reported.
고치지 않고 diff나 PR을 리뷰합니다. 독립 리뷰어 둘이 보고, 발견 사항은 모두 검증한 뒤 보고합니다.
/supergoal review this PR, no fixes /supergoal 이 PR 리뷰만 해줘ARCHITECTURE
Find what to deepen (or draw a diagram). Surveys friction, grills the pick, routes the refactor out to LEGACY/WAYFINDER.
어디를 손볼지 찾거나 다이어그램을 그립니다. 마찰 지점을 조사하고 후보를 검토한 뒤, 리팩터링은 LEGACY/WAYFINDER로 넘깁니다.
/supergoal find refactoring opportunities /supergoal 리팩터링할 곳 찾아줘TEACH
Understand something, no code. Teaches from real sources, then checks you can explain it back.
코드 없이 무언가를 이해합니다. 실제 자료로 가르친 뒤, 여러분이 자기 말로 설명할 수 있는지 확인합니다.
/supergoal explain how OAuth works /supergoal OAuth 작동 방식 설명해줘LEARN-DOMAIN
Map a codebase and persist a grounded .domain-agent/ wiki the agent can reuse later.
코드베이스를 파악해, 에이전트가 나중에 다시 쓸 수 있는 검증된 .domain-agent/ 위키로 남깁니다.
HARNESS-EVAL
Test whether a harness/skill actually helps. Runs the same task with and without it; weak evidence means "Not proven."
harness나 스킬이 실제로 도움이 되는지 검증합니다. 같은 작업을 적용 전후로 돌리고, 증거가 약하면 "입증 안 됨"으로 남깁니다.
/supergoal does this harness help on 3 cases? /supergoal 이 harness가 3개 케이스에서 도움 되나?SKILL-MINE
Turn repeated work into a reusable skill. Mines your history, suggests a few, forges the one you pick.
반복 작업을 재사용 가능한 스킬로 만듭니다. 히스토리를 훑어 몇 개를 제안하고, 고른 하나를 완성합니다.
/supergoal make a skill from what I keep doing /supergoal 반복하는 작업을 스킬로 만들어줘You do not have to know. Describe the real work in plain words and let supergoal route it. If it picks the wrong lane, just say so - it will re-route.
알 필요 없습니다. 하고 싶은 일을 평범한 말로 설명하면 supergoal이 알아서 경로를 정합니다. 잘못된 경로를 골랐다면 그렇게 말해 주세요. 다시 경로를 잡습니다.
9 · The principles
9 · 원칙
The five principles다섯 가지 원칙
If you remember nothing else, remember these. They apply on every run, in every mode.
다른 건 다 잊어도 이것만은 기억하세요. 모든 실행, 모든 모드에 적용됩니다.
Verify against ground truth실체로 검증한다
Re-run the project's real tests and re-read the request, ticket, README, and design/API docs for checks the tests miss. Never invent a proxy checklist and optimize to it.
프로젝트의 실제 테스트를 다시 돌리고, 테스트가 놓친 부분은 요청·티켓·README·설계/API 문서에서 다시 확인합니다. 대리 체크리스트를 만들어 거기에 맞추지 않습니다.
Smallest correct change필요한 만큼만 정확히 바꾼다
Match the surrounding code. No whole-file rewrite to change a few lines. (This governs code surface area, not UI quality - polished user-facing UI is still baseline correctness.)
주변 코드에 맞춥니다. 몇 줄 바꾸려고 파일 전체를 다시 쓰지 않습니다. (이는 코드 변경 범위에 대한 원칙이지 UI 품질 얘기가 아닙니다 - 다듬어진 사용자 화면은 기본 요건입니다.)
Hidden requirements surface at plan time숨은 요구사항은 계획 단계에서 드러낸다
Full-spec coverage and edge cases are discovered at Frame/Plan and written into the criteria you approve - not bolted on in extra passes later.
전체 스펙 커버리지와 예외 상황은 Frame/Plan 단계에서 발굴해, 여러분이 승인하는 기준에 적어 둡니다. 나중에 별도 패스로 덧붙이지 않습니다.
Ask only when genuinely ambiguous정말 애매할 때만 묻는다
Questions the code can answer are resolved by reading the code. It interrupts you only for a real fork where the answer changes the outcome.
코드로 답할 수 있는 질문은 코드를 읽어 해결합니다. 답에 따라 결과가 갈리는 진짜 갈림길에서만 여러분을 멈춰 세웁니다.
Hard stops반드시 멈추는 지점
A destructive or irreversible step (drop data, force-push, external publish) needs your explicit consent. And if the real tests cannot pass, it reports that honestly - it never fakes a pass.
파괴적이거나 되돌릴 수 없는 단계(데이터 삭제, force-push, 외부 공개)는 여러분의 명시적 동의를 받습니다. 그리고 실제 테스트가 통과할 수 없으면 그대로 정직하게 보고합니다 - 통과를 꾸며 내지 않습니다.
10 · FAQ
10 · 자주 묻는 질문
Frequently asked자주 묻는 질문
Do I have to babysit it?계속 지켜봐야 하나요?
Mostly no. It stops for two things: approving the plan (gate 2) and consenting to a destructive step. Otherwise it runs the loop on its own and reports at the end.
대부분 아닙니다. 두 가지에서만 멈춥니다: 계획 승인(게이트 2)과 파괴적 단계에 대한 동의. 그 외에는 스스로 루프를 돌리고 마지막에 보고합니다.
What if the tests can't pass?테스트가 통과할 수 없으면요?
It tells you, with the failing output. Reporting a real failure is a success of the process; faking a green is the one thing it will not do.
실패 출력과 함께 그대로 알려 줍니다. 진짜 실패를 보고하는 것은 이 방식의 성공입니다. 가짜 통과를 만드는 것만은 절대 하지 않습니다.
Does it work with Codex / Cursor / other agents?Codex / Cursor 등 다른 에이전트에서도 되나요?
Yes. Roles are plain files under agents/, so it is harness-agnostic. It is tested across Claude Code, Codex, and agy; any agent CLI that loads skills can use it.
됩니다. 역할이 agents/ 아래의 일반 파일이라 특정 도구에 얽매이지 않습니다. Claude Code, Codex, agy에서 검증됐고, 스킬을 불러올 수 있는 에이전트 CLI라면 쓸 수 있습니다.
What is a "worktree" and do I need it?"worktree"가 뭐고 꼭 필요한가요?
A git worktree is a second working copy of your repo on its own branch, so a run can edit code without touching your main checkout. Code runs use one by default and only merge into your target branch after verification and your acceptance. You do not have to set it up - supergoal handles it.
git worktree는 저장소의 두 번째 작업 사본으로, 자체 브랜치에서 동작합니다. 그래서 메인 체크아웃은 건드리지 않은 채 작업할 수 있죠. 코드 작업은 기본적으로 worktree를 쓰고, 검증과 여러분의 수락 뒤에만 대상 브랜치로 병합합니다. 직접 설정할 필요 없이 supergoal이 처리합니다.
How is this different from just asking my agent?그냥 에이전트에게 요청하는 것과 뭐가 다른가요?
Three things a plain pass tends to skip under pressure: a plan you approve before code, a builder that must exit green, and an independent verifier that actively tries to disprove the result against your real tests - with the evidence recorded.
급할 때 보통은 건너뛰는 세 가지입니다: 코드 전에 여러분이 승인하는 계획, 반드시 통과 상태로 끝나는 빌더, 그리고 실제 테스트에 비추어 결과를 적극적으로 반증하려 드는 독립 검증자 - 증거까지 기록합니다.
Will it touch my main branch or delete things?메인 브랜치를 건드리거나 무언가를 지우나요?
Not without consent. Work happens on a run branch/worktree, and any destructive or irreversible step is a hard stop that asks you first.
동의 없이는 하지 않습니다. 작업은 실행용 브랜치/worktree에서 이뤄지고, 파괴적이거나 되돌릴 수 없는 단계는 먼저 여러분에게 묻는 하드 스톱입니다.
It created no vault files for my small task - is that broken?작은 작업엔 볼트 파일이 안 생겼어요 - 고장인가요?
No. In a throwaway or single-task workspace it uses the fast path and holds state in the conversation. The same five gates still apply. See The run vault.
아닙니다. 일회성이거나 단일 작업용 작업공간에서는 빠른 경로를 써서 상태를 대화 안에 담습니다. 같은 다섯 게이트는 그대로 적용됩니다. 실행 볼트를 보세요.
Do I need Node.js?Node.js가 필요한가요?
The skill itself is just instructions. Node 18+ is only needed for the optional gate/audit scripts and the repo's own tests (tests/run-all.sh).
스킬 자체는 지침일 뿐입니다. Node 18+는 선택적 게이트/감사 스크립트와 저장소 자체 테스트(tests/run-all.sh)에만 필요합니다.
11 · Glossary
11 · 용어 사전
Glossary용어 사전
The handful of terms this wiki uses, in one place.
이 위키에서 쓰는 용어를 한자리에 모았습니다.
- baseline-first
- The design stance that the bar is "a strong model that read the real spec." supergoal only adds checks a plain baseline skips - it does not pile on ceremony for its own sake.기준선을 "실제 스펙을 읽은 좋은 모델"로 삼는 설계 태도. supergoal은 일반 기준선이 건너뛰는 검증만 더하고, 형식을 위한 절차를 쌓지 않습니다.
- ground truth
- The real, external standard of correctness: your project's actual test suite and the actual request/docs - as opposed to a checklist the agent made up.정답을 판정하는 진짜 외부 기준. 에이전트가 지어낸 체크리스트가 아니라, 프로젝트의 실제 테스트 스위트와 실제 요청·문서입니다.
- proxy
- A stand-in metric the agent could game - e.g. a self-written checklist. supergoal refuses to grade against a proxy.에이전트가 조작할 수 있는 대체 지표 - 예: 스스로 쓴 체크리스트. supergoal은 대리 지표로 채점하기를 거부합니다.
- fresh context
- A role that starts empty, having seen none of another role's reasoning. It is what lets the auditor judge the builder's work honestly.다른 역할의 사고 과정을 전혀 보지 않은 채 빈 상태로 시작하는 역할. 감사자가 빌더의 작업을 정직하게 판단할 수 있게 해 줍니다.
- gate
- A checkpoint the run must pass before continuing. The five gates are Frame, Plan approval, Build, Exact Verify/QA, Finalize.다음으로 넘어가기 전에 반드시 통과해야 하는 체크포인트. 다섯 게이트는 Frame, Plan approval, Build, Exact Verify/QA, Finalize입니다.
- run vaultrun vault (실행 볼트)
- The dated folder of Markdown files (GOAL, PLAN, QA, R-LOOP, Z) that records a code run start to finish.코드 작업의 처음부터 끝까지를 기록하는, 날짜가 붙은 Markdown 파일 폴더(GOAL, PLAN, QA, R-LOOP, Z).
- worktreeworktree
- A separate git working copy on its own branch, so a run edits code without disturbing your main checkout.자체 브랜치에서 동작하는 별도의 git 작업 사본. 덕분에 메인 체크아웃을 건드리지 않고 작업할 수 있습니다.
- red-green / test-firstred-green / 테스트 우선
- Write a test that fails first (red), then the smallest change that makes it pass (green). For bugs, the failing test also reproduces the bug.먼저 실패하는 테스트(red)를 쓰고, 그것을 통과시키는 가장 작은 변경(green)을 만드는 방식. 버그의 경우 실패 테스트가 버그 재현도 겸합니다.
- Before/After EvalBefore/After Eval
- Capture the state before, define the target after, and prove the delta with trusted commands - so the final claim shows the change, not just "tests passed."이전 상태를 기록하고 이후 목표를 정한 뒤, 신뢰할 수 있는 명령으로 그 차이를 증명하는 것. 그래서 마무리 보고가 "테스트 통과"가 아니라 실제 변화를 보여 줍니다.
- frontier slicefrontier slice (프런티어 조각)
- For a broad new build, the one vertical slice chosen to deliver first, so a foggy request becomes a shippable piece instead of everything at once.넓은 새 작업에서 가장 먼저 완성하기로 고른 하나의 수직 조각. 막연한 요청을 한꺼번에 처리하는 대신, 출시 가능한 한 조각으로 만듭니다.
- Impact MatrixImpact Matrix (영향 매트릭스)
- In QA-ONLY, a map of everything a feature can affect - screens, data paths, roles, before/during/after actions, and failure cases - plus what was not covered.QA-ONLY 모드에서, 기능이 영향을 줄 수 있는 모든 것(화면, 데이터 경로, 권한, 전/중/후 액션, 실패 케이스)과 확인하지 못한 범위까지 담은 지도.
- harnessharness
- Any scaffolding wrapped around a model to steer it (supergoal is one). HARNESS-EVAL mode measures whether a given harness actually helps.모델을 원하는 방향으로 이끌려고 덧씌우는 보조 장치 일체(supergoal도 그중 하나). HARNESS-EVAL 모드는 특정 harness가 실제로 도움이 되는지 측정합니다.
- conductorconductor (컨덕터)
- The top-level role that reads your objective, picks the mode, and dispatches the builder/tester/auditor. It stays lean and delegates the heavy reading to each phase's role.목표를 읽고 모드를 고르며 빌더/테스터/감사자를 파견하는 최상위 역할. 가볍게 유지하고, 무거운 읽기 작업은 각 단계의 역할에 맡깁니다.