GOAL.md

숫자를 부여하고, 잠자리에 드세요.

AI 에이전트에게 올라가야 할 숫자를 주고, 이를 수행할 루프 (loop)를 부여하세요. 그런 다음 잠자리에 들면 됩니다.

단 하나의 프롬프트. 어떤 에이전트든 가능. 다음 내용을 Claude, Cursor, Windsurf 또는 모든 코딩 에이전트에 붙여넣으세요:

github.com/jmilinovich/goal-md 를 읽어보세요 — 템플릿과 예시를 읽으세요.
그 다음 이 리포지토리(repo)를 위한 GOAL.md를 작성하고 작업을 시작하세요.

2분 설명 영상 시청하기

Karpathy의 autoresearch는 공식을 증명했습니다: 에이전트 (agent) + 적합도 함수 (fitness function) + 루프 (loop) = 하룻밤 사이의 돌파구. 하지만 autoresearch는 이미 스칼라 지표 (scalar metric)를 가지고 있을 때만 작동합니다. 손실 (Loss)은 감소하고, 논문은 더 좋아집니다. 대부분의 소프트웨어는 그렇지 않습니다. 최적화하기 전에 지표를 직접 구축해야 합니다.

GOAL.md는 이를 수행하기 위한 패턴입니다. 리포지토리에 넣기만 하면 코딩 에이전트를 자율적인 개선 도구로 바꿔주는 단 하나의 파일입니다. 이 리포지토리 자체도 에이전트가 소비하도록 설계되었습니다 — 템플릿은 프롬프트 (prompt)이고, 예시는 퓨샷 학습 데이터 (few-shot training data)이며, CLAUDE.md는 에이전트에게 당신의 프로젝트를 위한 좋은 GOAL.md를 작성하는 법을 가르칩니다.

내가 어떻게 이것을 발견하게 되었나

나에게는 라우팅 시스템을 위한 30개의 Playwright 테스트가 있었습니다. 절반은 깨져 있었고, 어떤 것인지 알 방법이 없었습니다. 나는 Claude가 이를 수정하기를 원했지만, 진짜 문제는 "테스트를 수정하는 것"이 아니었습니다. 문제는 이것이었습니다: 테스트 인프라가 신뢰할 수 있는지 어떻게 측정할 것인가? 이를 위한 커버리지 도구 (coverage tool)도, 테스트 러너 (test runner)도 없었습니다. 아무것도 없었습니다. 측정하기 전에 자(ruler)를 먼저 만들어야 했습니다.

═══════════════════════════════════════════
  routing confidence: 47 / 100 (47%)
═══════════════════════════════════════════
...

그래서 나는 지표를 구축했습니다: "라우팅 신뢰도 (routing confidence)"를 정의하는 네 가지 가중치 구성 요소입니다. 그런 다음 Claude에게 다음과 같이 말하는 파일을 작성했습니다: 여기 점수가 있고, 점수를 올리는 방법이 있으며, 언제 멈춰야 하는지 알려줄게. 그리고 잠자리에 들었습니다. 깨어보니 12개의 커밋 (commit)이 있었고, 각각은 원자적 (atomic)이었으며, 각각은 점수를 더 높게 끌어올리고 있었습니다. 47 → 83.

그 파일은 GOAL.md가 되었습니다. 놀라운 점은 루프 (loop) 그 자체가 아니었습니다. 어떤 에이전트 (agent)라도 루프를 돌릴 수는 있으니까요. 진짜 놀라운 점은 에이전트가 무언가를 측정하기 전에 제가 직접 자(ruler)를 제작해야 했다는 사실이었습니다. 일단 숫자가 생기자, 에이전트는 정확히 무엇을 해야 할지 알게 되었습니다.

진짜 시험

Playwright 사례는 이 방식이 작동한다는 확신을 주었습니다. 하지만 테스트는 최소한 어느 정도 측정이 가능합니다. 통과하거나 실패하니까요. 진짜 질문은 이것이 정말로 측정 불가능해 보이는 것들에도 일반화 (generalize)될 수 있는가였습니다.

문서 품질 (Documentation quality). "내 문서가 정말 좋은가?" 이에 대한 테스트 러너 (test runner)는 없습니다. 커버리지 (coverage) 도구도 없습니다. pytest --cov와 같은 대응물도 없습니다. 그저 느낌 (vibes)뿐입니다. docs-quality GOAL.md는 측정 장치 전체를 처음부터 구축해야 했습니다. 속성 정확도 검사기 (prop-accuracy checker), 예제 컴파일러 (example compiler), 교정된 린터 (calibrated linter)까지 말이죠. 존재하지 않았던 세 가지 도구를 사용하여, 존재하지 않았던 점수를 만들어냈으며, 대부분의 팀이 그저 눈대중으로만 판단하는 품질 차원을 측정했습니다.

하지만 저를 놀라게 한 부분은 따로 있었습니다. 에이전트에게는 *이중 점수 체계 (dual scoring system)*가 필요했습니다. 하나는 문서 품질을 위한 점수이고, 다른 하나는 측정 도구 (instrument)의 품질을 위한 점수였습니다. 린터 (linter) 자체가 고장 나 있었기 때문입니다. Vale가 onChange를 철자 오류로 표시하고 있었습니다. 순진한 에이전트라면 린터를 만족시키기 위해 문서를 "수정"하여 오히려 품질을 떨어뜨렸을 것입니다. 그래서 GOAL.md는 측정 도구 자체를 별도로 점수화했습니다: "문서 점수를 얼마나 신뢰할 수 있는가?" 에이전트는 먼저 자신의 망원경을 수리한 다음, 그 망원경을 사용하여 문서를 수정했습니다. 에이전트는 자를 만드는 동시에 그것으로 측정하고 있었으며, 이 이중 점수 패턴 덕분에 스스로를 속이는 일을 방지할 수 있었습니다.

그때 저는 이것이 진짜 패턴임을 깨달았습니다. 만약 자연적인 지표 (metric)가 전혀 없는 문서 품질을 위한 적합도 함수 (fitness function)를 구축할 수 있다면, 그 어떤 것에 대해서도 구축할 수 있습니다.

왜 그냥 좋은 CLAUDE.md를 쓰지 않나요?

CLAUDE.md는 매뉴얼 (manual)입니다. 에이전트에게 당신의 저장소 (repo)에서 어떻게 일해야 하는지를 알려줍니다. 반면 GOAL.md는 보상 함수 (reward function)입니다. 에이전트에게 *

더 어려운 문제는 "더 나은" 상태에 대해 기존의 측정 지표 (metric)가 없을 때입니다. 테스트 커버리지 (test coverage)에는 pytest --cov가 있습니다. 하지만 문서의 품질은 어떨까요? API의 신뢰성 (trustworthiness)은요? 코드의 건강도 (code health)는요? 먼저 측정 지표를 직접 구축해야 합니다. 그것이 바로 GOAL.md가 하는 일입니다. 에이전트에게 자(ruler)와 측정할 대상 (thing to measure)을 모두 제공하는 것입니다.

5가지 요소

1. 적합도 함수 (Fitness function)

느낌 (vibe)이 아니라 숫자입니다. 에이전트에게는 "더 나은" 상태에 대한 계산 가능한 정의가 필요합니다.

./scripts/score.sh    # → 47/100... 그 다음 52... 그 다음 61... 그 다음 83

autoresearch는 읽기 전용 파일에 있는 evaluate_bpb()를 잠급니다 (locks). 손실 (loss)을 최적화할 때는 괜찮습니다. 하지만 대부분의 소프트웨어 지표는 사용자가 직접 만듭니다. 그렇다면 누가 자를 변경할 수 있을까요?

모드 (Mode)	의미
Locked	에이전트가 점수 산정 코드를 건드릴 수 없음. autoresearch가 이 방식을 사용함.
...

Split 모드는 제가 실제로 사용하는 방식입니다. 저는 두 가지 점수를 두었습니다: "라우팅이 작동하는가?" (대상)와 "테스트를 신뢰할 수 있는가?" (도구)입니다. 에이전트는 결과값을 조작 (gaming the outcome)하지 않으면서도 도구를 날카롭게 다듬을 수 있었습니다 (테스트 추가, 탐지 기능 수정). 에이전트가 스스로 망원경을 만들고 있을 때는 이와 같은 이중 점수 (dual-score) 설정이 필요합니다.

2. 개선 루프 (Improvement loop)

측정 → 진단 → 실행 → 검증 → 유지 또는 되돌리기. 모든 반복 (iteration)은 저장소 (repo)를 더 좋게 만들거나 변화가 없어야 하며, 결코 더 나빠져서는 안 됩니다.

repeat:
  1. 적합도 함수 실행
  2. 가장 취약한 구성 요소 찾기
...

이는 autoresearch의 구조 (modify train.py → run → check val_bpb → keep or git reset)와 동일하지만, 이를 학습 실행 (training runs) 범위를 넘어 일반화한 것입니다.

각 반복은 iterations.jsonl에 한 줄을 추가합니다. 여기에는 변경 전/후 점수, 취해진 조치, 그리고 유지되었는지 또는 되돌려졌는지 여부가 기록됩니다. 향후 세션에서는 이 로그를 읽어 실패한 실험을 반복하지 않고, 성공했던 내용을 바탕으로 발전시켜 나갑니다.

3. 액션 카탈로그 (Action catalog)

영향력에 따라 순위가 매겨진 구체적인 동작들의 메뉴입니다. 에이전트에게 어디에 시간을 써야 할지를 알려줍니다.

| 동작 (Action)                          | 영향력 (Impact) | 방법 (How)                       |
|---------------------------------------|-----------------|----------------------------------|
| 실패한 테스트 수정 및 재실행           | +5 pts          | 실패 진단, 수정, 재실행           |
... 

autoresearch는 이를 암시적으로 처리하지만("train.py에 있는 모든 것은 대상이다"), 이는 신경망 (Neural Nets)에는 괜찮습니다. 하지만 소프트웨어의 경우, 명시적으로 지정하는 것은 에이전트가 5점짜리 변화가 바로 옆에 있음에도 불구하고 1점짜리 변화에 연산 자원 (Cycles)을 낭비하는 것을 방지합니다. 점수 추정치는 정밀할 필요가 없습니다. 그것들은 약속이 아니라 우선순위 신호 (Prioritization signals)입니다.

4. 동작 모드 (Operating mode)

리쉬 (Leash, 통제 범위)의 길이는 어느 정도인가? 동일한 에이전트, 다른 자율성 수준.

모드 (Mode)	사용 시점 (When to use)
수렴 (Converge)	기준이 충족되면 중단. "모든 점수를 80점 이상으로 만든 후 보고하라."
...

5. 제약 사항 (Constraints)

에이전트가 넘어서는 안 될 선. 이것들은 제안이 아니라 지탱해야 하는 구조적 규칙입니다.

- 테스트 결과를 절대 조작하지 말 것 — 결과는 오직 테스트 러너 (Test runner)로부터만 가져올 것
- 자격 증명 (Credentials)을 절대 수정하지 말 것
- 항상 전후를 측정할 것 — 점수가 감소해서는 안 됨
... 

autoresearch도 동일한 아이디어를 가지고 있습니다: "prepare.py를 수정하지 마라", "의존성 (Dependencies)을 추가하지 마라", "단순한 것이 더 낫다". 제약 사항이 없다면 에이전트는 당신이 의도하지 않은 방식으로 숫자를 높이기 위한 창의적인 방법들을 반드시 찾아낼 것입니다.

계보 (The lineage)

autoresearch (Karpathy, 2026년 3월)
  program.md + prepare.py + train.py
  단일 스칼라 지표 (Single scalar metric), 불변 평가 (Immutable eval), 무한 루프
... 

참고: Eval-Driven Development (evaldriven.org) — 측정 가능한 정확성 사양 (correctness specs)을 제공하지만, 에이전트용 파일 형식이 아닌 인간을 위한 방법론입니다. AGENTS.md (Google, OpenAI) — 에이전트에게 저장소 수준의 컨텍스트 파일 (context files)이 필요함을 입증했으나, 지시적 (directive, "무엇을 최적화할 것인가")이지 않고 기술적 (descriptive, "우리가 어떻게 일하는가")입니다. Ralph Wiggum (Huntley) — 회로 차단기 (circuit breaker)를 갖춘 지속적인 bash 루프를 제공하지만, 수치적 적합도 함수 (numeric fitness function)는 없습니다. GOAP (게임 AI, 2003) — 전제 조건 (preconditions)과 효과 (effects)를 가진 액션 카탈로그 (action catalogs); LLM 에이전트는 이보다 덜 형식적이어야 하지만 아이디어는 동일합니다. GEPA (Khattab et al.) — 적합도 함수 (fitness functions)를 활용한 다중 목적 프롬프트 진화 (multi-objective prompt evolution); 여기서의 반복 로그 (iteration log) 패턴은 세대(generations)를 거치며 무엇이 효과적이었는지 추적하는 그들의 접근 방식에서 차용했습니다.

이 저장소는 스스로를 테스트합니다 (dogfoods itself)

이 저장소는 자체적인 GOAL.md와 스코어링 스크립트 (scoring script)를 가지고 있습니다:

미래의 Claude 세션은 이 저장소의 GOAL.md를 가져와 점수를 계속해서 높여갈 수 있습니다. 스코어링 스크립트는 단순한 bash와 jq로 작성되어 아주 견고하지는 않지만, 제대로 작동합니다.

GOAL.md가 필요한 경우

작업이 일회성 작업 (one-shot task)이 아니라 최적화 루프 (optimization loop)일 때 필요합니다. "더 나음"을 판단하기 위해 단순히 "테스트 통과"가 아닌, 직접 구축해야 하는 지표 (metric)가 필요할 때 필요합니다. 잠든 사이에 진행 상황이 나타나기를 원할 때 필요합니다.

단일하고 명확하게 정의된 변경 사항("다크 모드 토글 추가")이나 "완료"가 명백한 경우에는 필요하지 않습니다. 좋은 지침이 담긴 CLAUDE.md만으로 충분하다면, 그것으로 충분합니다.

시작하기

가장 빠른 방법: 에이전트를 이 저장소로 지정하고 작업을 맡기세요.

github.com/jmilinovich/goal-md 를 살펴보세요 — 템플릿과 예시를 읽어보세요.
그 다음, 이 저장소를 위한 GOAL.md를 작성하고 작업을 시작하세요.

또는 수동으로 수행하세요:

1. template/GOAL.md를 저장소로 복사합니다.
2. 적합도 함수 (fitness function, 숫자를 출력하는 스크립트)를 정의합니다.
3. 개선 루프 (improvement loop)와 액션 카탈로그 (action catalog)를 채웁니다.
4. 에이전트를 지정하고 실행하게 합니다.

실제 사례

이것들은 단순한 문서가 아닙니다. 에이전트가 사용자의 프로젝트를 위한 GOAL.md를 작성할 때 패턴 매칭 (pattern-match)을 수행하기 위해 사용하는 퓨샷 예시 (few-shot examples)입니다. 각 예시는 서로 다른 도메인 (domain), 지표 스타일 (metric style), 그리고 운영 모드 (operating mode)를 보여줌으로써 에이전트가 일반화 (generalize)할 수 있는 충분한 다양성을 제공합니다.

프로젝트	도메인	지표	모드	링크
docs-quality	React 컴포넌트 라이브러리 문서	이중: 문서 품질 + 도구 품질	분리/수렴 (Split/Converge)	examples/docs-quality.md
...

더 많은 예시를 환영합니다. PR (Pull Request)을 보내주세요. 더 많은 다양성은 모두의 프로젝트를 위한 더 나은 GOAL.md 파일을 의미합니다.

적합도 함수 (fitness function) 작성이 도움이 필요하신가요? 일반적인 도메인 전반에 걸쳐 복사하여 붙여넣을 수 있는 스코어링 스크립트 (scoring script) 레시피는 examples/scoring-scripts.md를 참조하세요.

공유 (Share)

런칭 스레드 (launch thread)를 위한 트윗 이미지를 확인하세요:

문제점	스토리	패턴	CTA

라이선스 (License)

MIT

<sub><details><summary>면책 조항 (Disclaimer)</summary>

goal-md는 오픈 소스 명세 (specification)이며, 암호화폐가 아닙니다. 이 프로젝트와 연관되거나 이 프로젝트에 의해 보증되는 토큰은 없습니다. pump.fun의 $GOAL 밈코인 (memecoin)은 이 저장소를 참조하고 있으며, 저의 개입 없이 생성자 수수료를 저의 GitHub 핸들로 전송했습니다. 그렇게 수령된 모든 토큰은 온체인 (on-chain)에서 소각되었습니다 (tx).

</details></sub>