Show GN: OpenGoal - 마크다운만으로 AI 코딩 에이전트의 현재 목표를 관리하는 명세 기반 하네스

안녕하세요. AI 코딩 에이전트용 경량 명세 기반 하네스 OpenGoal을 소개합니다.

AI 에이전트로 코딩에 빠졌던 여느 개발자들처럼 저도 동시에 여러 프로젝트들을 미친 듯이 돌리고 있었습니다. 좀 더 체계적인 개발을 위해 OpenSpec, Superpowers를 기반으로 명세 기반 개발을 도입했었습니다. 그런데 명세 기반 개발로는 해결되지 않는 이런 병목이 있었습니다.

"내가 다음에 할 것이 무엇이지?"

당연한 것이지만 명세는 다음에 해야 할 것이 무엇인지 알려주지 않았습니다. 이를 해결하기 위해 노션에 프로젝트별 목표 문서를 만들어 두고 관리했었습니다. 하지만 프로젝트와 분리된 곳이라 매번 챙기기가 번거로웠습니다. 그래서 프로젝트 공간 안에 함께 있는 명세와 상태 관리가 결합된 하네스가 필요했습니다. 그렇게 제가 경험한 명세 기반 하네스들의 단점은 보완하고 장점은 계승하면서 만들었습니다.

OpenGoal은 '질문 하나에 파일 하나'라는 원칙을 기반으로 합니다. 프로젝트에 묻고 싶은 것이 있다면, 그 답은 정확히 한 파일에 있습니다.

ROADMAP.md ───────────── where am I in the big picture?
CONTEXT.md ──────── what is this project?
● GOAL.md ── what do I do now?

이 문서들은 기본적으로 docs 폴더에 유지됩니다. GOAL.md는 "내가 다음에 무엇을 해야 하는지"에 답하는 명세입니다.

주요 특징은 다음과 같습니다.

**순수 마크다운:**CLI나 hook, MCP 서버를 쓰지 않습니다. 런타임에 더해지는 것이 없어서 가볍게 동작하고, 사용되지 않는 도구 정의가 토큰을 차지하지 않습니다.**작업 크기에 맞는 명세:**목표(Goal)만 만들 수도 있고, 목표를 필요한 만큼 태스크로 더 잘게 나눌 수 있습니다. 간단한 작업은 설계 문서를 생략할 수 있습니다. 작은 태스크에도 엄격한 명세를 작성하여 생기는 토큰 낭비를 줄이기 위해서입니다.**아카이브:**목표의 태스크들을 모두 마치면 GOAL.md와 DESIGN.md, 체크포인트를 docs/archive/goals/ 아래로 옮깁니다. 이 문서들은 단순히 보관으로 끝나지 않습니다. 나중에 그 부분을 수정하거나 다음 골을 진행할 때, AI가 당시의 설계와 결정을 아카이브에서 찾아 맥락으로서 참고합니다.**체크포인트:**진행 중인 골의 상태를 저장합니다. 저는 주로 컴팩션에 대비하거나 다른 세션이나 다른 AI 도구로 작업을 넘길 때 씁니다. Claude Code에서 체크포인트를 작성해 두고 Codex로 넘어가서 바로/opgl:go

를 하면 작업이 그대로 이어집니다.**자연어 실행:**커맨드를 매번 입력하지 않아도 됩니다. 맥락이 분명하면 자연어로도 실행됩니다. AI가 권장한 커맨드에 "ok"나 "진행해"라고 답해도 동작합니다. "태스크 6 진행해"라고 하면/opgl:go

가, "진행사항 저장해"라고 하면/opgl:goal checkpoint

가 실행됩니다.**서브에이전트 스킬:**메인 에이전트가 작업의 난이도에 따라 어떤 모델의 서브에이전트에게 맡길지 판단합니다. 다만 위임만 하지는 않습니다. 자료 수집은 서브에이전트가 하되, 분석 자체와 아주 작은 수정은 메인 에이전트가 직접 합니다. 위임 위주의 하네스에서는 서브에이전트가 실패해도 메인이 세부 원인을 모른 채 또다시 위임만 반복하는 악순환을 겪었기 때문입니다.

그 외에도 골 일시중단(suspend)과 재개(resume), 서브 골(sub-goal), 백로그(backlog), 로드맵(roadmap)을 다룹니다. 마크다운만으로 할 수 있는 걸 최대한 쥐어짜냈고 아직도 진행 중입니다.

Claude Code를 비롯해 Cursor, Codex, Antigravity 등 20여 개 도구에 설치할 수 있습니다. 설치는 프로젝트 루트에서 아래 한 줄로 설치할입니다.

npx @opellen/opengoal init

처음에는 /opgl:scout

로 시작하면 됩니다. 코드베이스가 확인되면 CONTEXT.md 작성을 권장합니다. CONTEXT.md는 처음에 만들어도 되지만 골을 몇 개 진행 후 충분히 맥락이 쌓였을 때 작성해도 됩니다.

/opgl:goal init

으로 골을 만들고 /opgl:go

로 진행합니다.

You: /opgl:goal init 인증 모듈을 JWT에서 세션 기반으로 전환
AI: ✓ docs/GOAL.md 생성 완료 (5개 태스크)
You: /opgl:go
AI: Task 1/5: 세션 스토어 설정... ✓ done
Task 2/5: 미들웨어 교체... ✓ done
Task 3/5에서 DB 스키마 변경이 필요합니다. 진행할까요?

사용 전에 알아두실 것들입니다.

• 프로젝트의 각 도구 설정 폴더(Claude Code는
  .claude/

등)에 마크다운 커맨드와 스킬 파일을 생성합니다. - 커맨드 접두사(
opgl

)와 기본 문서 폴더(docs

)는 설치 시 각각--prefix

,--docs

인자로 변경할 수 있습니다. - 도구에 따라 슬래시 커맨드가 아니라 스킬 디렉토리에 설치되기도 합니다. (예: Codex)

• 서브에이전트 스킬은 서브에이전트를 지원하는 도구에서만 의미가 있습니다.

설치나 사용 중 막힌 부분, 또는 궁금한 점이 있으시면 댓글 남겨주세요.