OpenSpec: 코딩 에이전트와 스펙을 맞추는 가벼운 스펙 프레임워크

Who Should Read

Claude Code·Codex 같은 코딩 에이전트로 큰 기능을 만들면서 요구사항이 흩어져 고민인 개발자

Core Mechanics

• 스펙을 중심에 두는 프레임워크
  • OpenSpec은 만들 것을 스펙으로 적어 팀과 코딩 에이전트의 방향을 맞추는 도구다.
  • 요구사항을 다듬고, 맞는 내용인지 검증하고, 구현이 스펙과 일치하는지 확인하는 것이 목표다.
• 슬래시 명령 5단계 워크플로
  • /opsx:explore로 문제와 코드베이스를 파악한다.
  • /opsx:propose로 proposal.md, specs/, design.md, tasks.md 초안을 만든다.
  • /opsx:apply로 구현하고, /opsx:verify로 스펙 일치를 확인하고, /opsx:archive로 끝난 변경을 보관한다.
• 설치는 npm 한 줄
• npm install -g @fission-ai/openspec@latest 로 설치한다.
  • npm, pnpm, bun, yarn, nix를 지원한다고 적혀 있다.
• 여러 에이전트 도구와 호환
  • Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode 등이 호환 목록에 있다.
  • 목록에 없는 33개 도구가 더 있다고 적혀 있다.
• 사용 규모는 원문 자체 주장
  • GitHub 스타 72.1k, 월 개발자 265,000명 이상이라고 쓰여 있다.

Community Reactions

• 스펙은 썩고 코드가 진짜 스펙이라는 경험
  • 대형 프로젝트 두 개를 6~9개월 혼자 만들며 OpenSpec을 써 봤다는 댓글이 있다.
  • LLM으로 스펙↔코드 일치를 양방향 점검했더니 둘 다 크게 어긋났고, 스펙 부분은 버렸다고 한다.
  • 제안→리뷰→구현→코드 리뷰 흐름과 ADR, 불변식 로그는 유지했다고 한다.
• 문서가 너무 많아 리뷰가 안 된다는 반론
  • 회사에서 도입했는데 변경마다 AI 티 나는 마크다운이 여러 개 생겨 리뷰 부담이 크다는 의견이 있다.
  • 사람이 쓴 짧은 스펙이 더 효과적이라는 의견이다.
  • 다른 댓글도 산출물이 많아 요구사항이 제대로 반영됐는지 알기 어렵다고 했다.
• 좋았다는 경험과 대안 도구들
  • 내부 평가에서 점수가 좋았고 의식(절차)이 적당하다는 호평 댓글이 있다.
  • 에이전트 하네스의 플래너가 OpenSpec으로 계획을 만들게 했더니 SpecKit보다 가볍게 잘 돌았다는 경험도 있다.
  • GSD는 토큰을 약 4배 쓰지만 추적성을 얻는다는 댓글이 있다.
• 최신 모델엔 불필요하다는 의견과 근거 요구
  • Codex나 Claude Code를 쓴다면 굳이 필요 없다는 의견이 있다.
  • 어떻게, 왜 동작하는지 벤치마크로 보여 달라는 요구도 있었다.

How to Apply

• 작은 기능 하나로 propose 돌려 보기
  • 오늘 작은 기능 하나를 골라 npm으로 설치하고 /opsx:propose를 실행하라.
  • 생성된 proposal.md와 tasks.md가 요구사항과 맞는지 직접 읽어 보라.
• apply 뒤 verify로 스펙 어긋남 측정하기
  • /opsx:apply로 구현한 다음 /opsx:verify를 돌려라.
  • 어긋난 항목 수를 기록해 스펙이 얼마나 빨리 낡는지 확인하라.
• 변경 크기별로 절차 나누기
  • 10줄짜리 수정에는 스펙 없이 에이전트 기본 plan 기능을 써라.
  • 큰 기능에만 proposal 흐름을 적용하라.
• 스펙 문서는 사람이 먼저 훑어 줄이기
  • 생성된 스펙 파일은 병합 전에 핵심 요구사항만 남기고 줄여라.
  • 리뷰할 파일 수를 팀 합의로 제한하라.

Try It

# Claude Code 터미널에서 실행 (설치 후 프로젝트 루트에서)

npm install -g @fission-ai/openspec@latest

# Claude Code 안에서 슬래시 명령을 순서대로 입력
/opsx:explore
/opsx:propose {{만들 기능 설명}}

# proposal.md, specs/, design.md, tasks.md를 읽고 수정한 뒤
/opsx:apply
/opsx:verify

# 이어서 해 볼 것: 끝나면 /opsx:archive 로 보관하고, verify에서 나온 불일치 개수를 기록해 보세요

Terminology

관련 논문

• 같은 시뮬레이션, 다른 근거: 도구 출력을 파일로 넘기면 LLM 에이전트 정확도가 어디서 깎이나

  긴 툴 출력을 파일로 넘기자 GPT-5.1은 정확도 11.3%p 하락, 정식 출력 지정하니 회복

• 가짜 뉴스가 진짜 폭락을: LLM 트레이딩 에이전트 대상 정보 주입 공격

  가짜 헤드라인 한 줄로 LLM 트레이딩 에이전트 62%를 조종했다(프롬프트 주입은 14%)

• Harness Engineering 101: LLM은 뇌, harness는 몸

  에이전트는 JSON 배열을 관리하는 루프이고, 16개 챕터로 직접 만들어 본다

• Harness²: 에이전트 harness를 스스로 고쳐 쓰는 재귀 최적화 프레임워크

  모델은 고정하고 harness를 재귀로 고쳤더니 벤치마크 점수가 최대 11.8%p 올랐다

• 해고된 Savannah 경찰관, ICE 요원 남편에게 Flock 계정 공유

  경찰관이 Flock 계정을 남편(ICE 요원)에게 공유했고, 감사에서 983건 검색이 드러나 해고됐다

• tmux와 Claude Code: 세션, send-keys, 그리고 한계선

  tmux로 Claude Code 여러 개를 돌리면 편하지만 에이전트 4개쯤에서 한계가 온다

• Hybrid Reasoning Agents: 잠재 공간에서 생각하고 텍스트로 행동하는 LLM 에이전트

  잠재 공간 추론과 텍스트 도구 호출을 섞었더니 성능 10.4%↑, 토큰 최대 54.7%↓

Related Resources

• https://openspec.dev/
• https://github.com/Fission-AI/OpenSpec
• https://github.com/spekk-ai/spekk-cli
• https://github.com/nutthouse/tutti
• https://www.shipsmooth.net/
• https://specks.nicotejera.com
• https://jaisenmathai.com/articles/sojourn-for-ios-was-45-one...