Speckit Slimmer Planner · Bounded Agent Loop

계획이 길어질수록 현재 작업이 흐려졌다

Agent에게 기능 구현을 맡길 때 계획은 도움이 된다. 요구사항을 먼저 정리하고, 모르는 부분을 조사하고, 구현 순서와 검증 방법을 남기면 다음 turn에서도 같은 방향을 이어갈 수 있다.

하지만 작은 변경에도 전체 프로젝트 수준의 계획을 만들기 시작하면 다른 문제가 생긴다. 지금 수정하려는 버튼 하나보다 architecture와 foundation task가 더 크게 늘어나고, 실제로 구현해야 할 다음 행동은 긴 문서 안에 묻힌다. 계획을 만들었지만 어떤 결정이 확정됐는지, 사용자에게 무엇을 더 물어봐야 하는지, 지금 구현해도 되는지가 오히려 흐려지는 경우가 있었다.

Speckit Slimmer Planner는 이 문제에서 시작했다. GitHub Spec Kit의 단계를 없애는 것이 아니라, 유용한 policy를 한 feature나 request function 단위로 줄여서 agent loop 안에 넣는 실험이다.

공식 Spec Kit을 먼저 직접 실행했다

비교를 위해 GitHub Spec Kit의 현재 source를 reference/github/github/spec-kit에 clone했다. 확인한 commit은 654793b65906417c449d77269407638cdebb6f8a, CLI version은 0.12.15.dev0이었다.

빈 임시 프로젝트에 다음 조건으로 Codex integration을 실제 초기화했다.

specify init <scratch-project> --integration codex --ignore-agent-tools

초기화 결과 .agents/skills/에는 constitution, specify, clarify, plan, tasks, checklist, analyze, implement, taskstoissues, converge의 열 개 skill이 설치됐다. .specify/에는 shell script, spec·plan·tasks template, workflow registry, integration manifest와 constitution memory가 만들어졌다.

공식 Spec Kit은 feature specification lifecycle을 여러 agent와 integration에서 일관되게 실행하기 위한 toolkit이다. CLI와 bundled workflow, template, preset과 extension이 함께 움직이는 구조에는 분명한 장점이 있다. 다만 내가 원한 것은 toolkit 전체를 설치하는 일이 아니라, 평소 Codex 작업에서 한 요청의 범위를 잃지 않도록 만드는 작은 planning loop였다.

남긴 것과 줄인 것

공식 workflow에서 가져온 것은 단계의 이름보다 책임이다.

• 구현 전에 무엇을 만들지 명시한다.
• 모호한 요구사항은 계획에 숨기지 않고 먼저 질문한다.
• 실제 선택지가 있을 때만 조사하고 결정 근거를 남긴다.
• 요구사항과 plan, task가 서로 추적돼야 한다.
• 구현 전에 빠진 조건과 충돌을 확인한다.
• 완료는 코드 작성이 아니라 검증 결과로 판단한다.

대신 full CLI installation, project-wide constitution 생성, 여러 user story를 전제로 한 큰 template, 모든 단계의 무조건적인 실행은 기본 경로에서 제외했다. 기존 repository guidance를 읽고, 지금 요청한 한 work unit에 필요한 artifact만 만든다.

flowchart LR
  Request[한 가지 요청 /spec] --> PRD[Scoped PRD]
  PRD --> Question[한 번에 한 질문]
  Question --> State[Append-only State]
  State --> Gate{더 확장할 이유가 있는가}
  Gate -->|없음| Handoff[현재 상태 전달]
  Gate -->|있음| Research[Research · Plan · Tasks]
  Research --> Analyze[Readiness Check]
  Analyze --> Implement[Implement · Verify]

/spec은 큰 /plan의 축소판이 아니다

<원하는 변경> /spec을 입력하면 먼저 work/<unit-slug>/prd.md를 만든다. 이 문서는 한 feature, bug fix, UI flow, API behavior처럼 독립적으로 확인할 수 있는 작업 하나만 다룬다. In scope와 out of scope, 사용자 scenario, testable requirement, acceptance criteria, edge case와 open question을 남긴다.

모호한 점이 있으면 한 번에 가장 영향이 큰 질문 하나만 묻는다. 여러 질문을 한꺼번에 보내고 사용자가 전체 설계를 다시 작성하게 하지 않는다. 답을 받으면 PRD와 상태를 갱신하고, 다음 결정이 정말 필요한지 다시 판단한다.

기본 흐름은 여기에서 멈출 수 있다. PRD와 합의가 충분한 작은 작업이라면 research, plan, task 문서를 형식적으로 늘리지 않는다. 반대로 dependency, API, persistence, authentication, migration, concurrency, 중요한 UI state처럼 구현 비용이나 위험을 바꾸는 조건이 있으면 필요한 stage로 확장한다.

Prompt가 아니라 파일에 상태를 남긴다

긴 agent 작업이 끊기는 이유 중 하나는 결정이 대화 context에만 남아 있기 때문이다. Slimmer는 runtime state를 두 영역으로 나눈다.

.agent/
├── master-log.md
├── state.md
├── decisions.md
├── ui-state.md
└── references.md

work/<unit-slug>/
├── prd.md
├── research.md
├── plan.md
├── tasks.md
└── checks.md

work/<unit-slug>/는 현재 기능의 산출물이고, .agent/는 저장소 안에서 이어지는 결정과 상태 기록이다. .agent/ entry는 append-only다. 이전 판단을 지우거나 문장을 몰래 고치는 대신, 시간과 stage, work unit, 상태와 근거를 가진 새 entry를 덧붙인다.

UI state와 reference를 별도 파일로 둔 것도 의도적이다. 화면 작업에서 local state와 shared state, persistence와 URL sync 같은 결정은 구현 중 쉽게 바뀐다. 외부 문서나 source를 참고한 경우 어떤 requirement와 decision을 뒷받침했는지 남겨야 다음 agent가 같은 조사를 반복하지 않는다.

Stage는 작은 prompt shard로 나눴다

하나의 거대한 skill prompt에 모든 규칙을 넣으면 현재 단계와 관계없는 instruction이 매번 context를 차지한다. 그래서 SKILL.md는 orchestrator 역할만 하고, specify·clarify·checklist·research·plan·tasks·analyze·implement·taskstoissues는 각각의 reference shard로 분리했다.

각 stage에는 실행 전에 읽어야 할 Load, 수행할 일과 하지 않을 일, 완료 뒤 사용자에게 알릴 Notify User가 있다. Artifact contract, bloat guardrail, state entry template도 필요한 stage에서만 읽는다. 전체 policy를 유지하면서 한 turn이 가져오는 context는 작게 만들기 위한 구조다.

계획이 다시 커지는 지점을 막았다

Bloat guardrail에는 실제로 계획이 부풀기 쉬운 지점을 적었다. /spec 실행 중 새 constitution을 만들지 않고, 하나의 outcome을 여러 story로 불필요하게 쪼개지 않는다. 조사할 수 있다는 이유로 모든 기술을 조사하지 않고, 선택을 바꾸는 unknown만 확인한다.

Plan에는 affected file, interface, UI/data state, implementation path와 validation을 남기되 전체 repository architecture를 다시 쓰지 않는다. Task는 acceptance criteria와 연결하고 가능한 경우 실제 path를 적는다. 새로운 abstraction은 더 단순한 대안과 비교해 정당화한다.

이 규칙의 목적은 문서를 짧게 만드는 것이 아니다. 지금 구현할 작업과 직접 연결되지 않는 문장이 loop의 다음 행동을 가리지 않게 만드는 것이다.

공식 Spec Kit과의 차이

Slimmer가 공식 도구보다 낫다는 결론은 아니다. 해결하려는 범위가 다르다. 여러 팀과 agent에서 표준화된 spec workflow를 운영한다면 공식 Spec Kit의 CLI와 integration이 유리하다. 한 repository에서 작은 변경을 자주 처리하고 현재 결정과 다음 행동을 놓치지 않는 것이 중요하다면 Slimmer의 제한이 더 잘 맞을 수 있다.

아직 확인해야 할 것

이 workflow의 효과를 planning 시간이나 재작업 감소 수치로 증명한 단계는 아니다. 실제 여러 프로젝트에 적용하면서 어느 artifact가 계속 사용되고 어느 규칙이 오히려 마찰을 만드는지 더 확인해야 한다. Append-only log도 기준 없이 늘어나면 새로운 bloat가 될 수 있어, 모든 생각이 아니라 stage transition과 결정만 기록하도록 계속 조정해야 한다.

이 프로젝트의 현재 결과는 완성된 planning framework가 아니라, 공식 workflow를 source와 실행 결과로 분석하고 내 agent 작업에 필요한 policy만 다시 조립한 skill이다.

이 프로젝트에서 남은 것

Agent loop에서 중요한 것은 가장 긴 계획을 만드는 일이 아니었다. 현재 범위를 합의하고, 결정의 근거를 남기고, 다음 행동을 분명하게 만드는 일이었다.

Spec Kit에서 가져온 것은 ceremony가 아니라 단계별 책임이다. Slimmer에서 새로 만든 것은 그 책임이 한 기능의 크기를 넘어가지 않도록 멈추는 규칙이다.

원고 연결

전체 원고: 00_원본 전체 원고 — Speckit Slimmer Planner — 기능 단위 개발 계획 스킬