SpecOps가 AI 코딩 에이전트에 구현 전 명세 작성을 더한다

SpecOps는 AI 코딩 에이전트가 코드를 바로 작성하기 전에 요구사항과 설계를 정리하도록 돕는 오픈소스 도구다. Claude Code, Cursor, OpenAI Codex, GitHub Copilot, Google Antigravity에서 사용할 수 있으며 명세와 프로젝트별 맥락을 Git에 저장한다.

사용자가 기능을 설명하면 에이전트가 곧장 코드를 작성하고, 첫 단계에서 세운 가정을 나중에 바로잡느라 시간을 쓴다는 것이 SpecOps가 제시하는 문제다. 이 도구는 명령 하나로 코드베이스와 맥락을 파악하고, 요구사항·설계·작업 순서가 담긴 명세를 만든 다음, 그 명세에 따라 구현하고 확인된 인수 기준을 충족했는지 점검하는 4단계 흐름을 제공한다.

• 코드베이스와 맥락 파악
• 요구사항·설계·순서가 정해진 작업 명세 작성
• 가정이 아니라 명세에 따른 구현
• 검증된 인수 기준을 확인해 완료

명세는 Git으로 추적되며 세션이 끝난 뒤에도 남는다. SpecOps는 Claude Code, Cursor, OpenAI Codex, GitHub Copilot, Google Antigravity에서 작동한다고 안내한다.

설치와 사용

Claude Code에서는 플러그인 마켓플레이스를 통해 설치할 수 있다.

/plugin marketplace add sanmak/specops /plugin install specops@specops-marketplace /reload-plugins

다른 플랫폼에서는 한 줄 설치 명령을 사용할 수 있다. 저장소는 실행 전 설치 스크립트를 먼저 살펴보라고 안내한다.

bash <(curl -fsSL https://raw.githubusercontent.com/sanmak/specops/main/scripts/remote-install.sh)
# Inspect the script first: https://github.com/sanmak/specops/blob/main/scripts/remote-install.sh

또는 저장소를 복제한 뒤 설치 스크립트를 실행한다.

git clone https://github.com/sanmak/specops.git && cd specops && bash setup.sh

사용 예시는 /specops Add user authentication with OAuth다. 플랫폼별 설치 안내는 QUICKSTART.md, 전체 명령어 목록은 docs/COMMANDS.md에 있다.

저장소는 설정이 선택 사항이며 기본값을 제공한다고 설명한다. 프로젝트 루트에 .specops.json을 만들면 명세 디렉터리, 분야별 템플릿, 팀 규칙과 검토 필요 여부를 지정할 수 있다.

{
 "specsDir": ".specops",
 "vertical": "backend",
 "team": {
 "conventions": ["Use TypeScript", "Write tests for business logic"],
 "reviewRequired": true
 }
}

설정 예시는 examples/, 전체 스키마는 REFERENCE.md, 작업 방향을 지정하는 파일은 STEERING_GUIDE.md에서 확인할 수 있다.

명세 작성과 구현 관리

저장소의 사용 예시에서 명세 없이 OAuth 인증을 요청하면 에이전트가 질문 없이 JWT를 선택하고, Google만 지원하도록 하드코딩하며, 요청 제한을 빠뜨린 채 파일 6개를 만든다. 이후 GitHub 지원이 필요하다는 점 등을 바로잡는 데 30분이 든다는 시나리오를 든다.

SpecOps를 거치면 예시상 requirements.md에 사용자 스토리 4개와 EARS 표기법으로 쓴 인수 기준 12개가 기록된다. design.md에는 JWT와 세션의 장단점 비교 및 인증 제공자 추상화 계층이, tasks.md에는 의존성과 예상 작업량이 포함된 순서 있는 작업 8개가 담긴다. 에이전트는 이후 검증된 기준에 맞춰 각 작업을 구현한다.

SpecOps는 분야별 템플릿 7종을 제공한다고 설명한다. 대상은 백엔드, 프런트엔드, 인프라, 데이터 파이프라인, 라이브러리·SDK, 풀스택, 빌더다. 인프라 명세에는 롤백 단계와 리소스 정의를, 데이터 파이프라인 명세에는 데이터 계약과 백필 전략을 포함하는 식으로 분야별 내용을 반영한다.

세션이 바뀌어도 명세 파일과 맥락을 복구할 수 있고, 로컬 메모리 계층은 매 세션 자동으로 불러온다. 팀 검토 흐름에는 설정 가능한 승인 단계가 있으며, 명세가 승인되기 전에는 구현을 막는다고 저장소는 설명한다. EARS 표기법은 WHEN [event] THE SYSTEM SHALL [behavior] 형식으로 요구사항을 구체화한다.

구현 뒤 명세와 코드가 달라지는 문제에는 자동 드리프트 검사 5종과 감사·조정 명령을 제공한다. 새 패키지를 설치하기 전에는 범위 적합성, 유지관리 상태, 크기의 적절성, 보안 표면, 라이선스 호환성 등 5개 기준을 평가하는 의존성 도입 관문을 거친다. 저장소는 이 관문이 항상 활성화되며 우회할 수 없다고 설명한다.

에이전트가 자신의 작업을 완료로 표시하는 문제에는 별도의 평가자가 명세와 구현을 정해진 임계값에 따라 평가하는 적대적 평가 방식을 제시한다. 평가자는 2단계에서 명세 품질을, 4단계에서 구현 품질을 살핀다. 명세 검토를 위한 승인 흐름, 체크박스 완료 관문, CI에 통합되는 드리프트 검사도 구현을 통제하는 기능으로 소개한다.

여러 명세와 운영 환경의 학습

여러 범위에 걸친 큰 기능은 자동으로 감지해 서로 조율되는 명세로 나눈다. 저장소의 예시에서 OAuth 인증과 결제를 함께 요청하면 인증과 결제라는 두 범위를 식별한다. 인증 명세는 1차 작업의 기본 골격으로, 결제 명세는 인증에 의존하는 2차 작업으로 제안하며, 두 명세를 추적하는 oauth-payments 이니셔티브를 만든다. 사용자가 승인하면 명세 두 개가 생성되고 specDependencies로 연결된다. /specops initiative oauth-payments를 실행하면 두 작업을 순서대로 진행한다. 의존성 관문과 실행 단계, 이니셔티브 추적 기능이 조정을 맡는다.

운영 환경에서 명세에 빠진 점을 발견하면 /specops learn으로 기록하고 원래 명세에 연결할 수 있다. 관련 코드를 다루는 이후 작업에서는 해당 학습 내용을 자동으로 불러온다. 저장소의 예시는 배치 처리에서 동시 쓰기가 500개 연결을 넘으면 P99가 악화된다는 발견을 기록하고, 쓰기 부하가 큰 작업의 설계 문서에 동시성 한도를 포함하라는 예방 원칙을 연결한다. 자세한 내용은 docs/LEARNINGS.md에 있다.

저장소는 운영 이후의 발견을 원래 명세와 연결하고 이후 작업에 반영하는 기능, 하나의 기준 자료에서 여러 플랫폼으로 명세를 내보내는 기능, 큰 작업의 자동 분해와 의존성 추적을 차별점으로 내세운다. 또 별도 평가자가 품질을 점검하고, 분야별 템플릿이 도메인에 맞는 항목을 포함하며, 승인되지 않은 명세에 따른 구현을 막는다고 설명한다. 모든 자료는 Git으로 추적되는 마크다운 파일로 관리하며, 클라우드 서비스나 계정이 필요 없는 MIT 라이선스 오픈소스라고 밝힌다.

SpecOps 자체의 모든 기능도 SpecOps 작업 흐름으로 명세를 만들고 설계해 구현했다고 저장소는 설명한다. 관련 명세는 공개 저장소의 .specops/에 있으며, 도구를 만드는 과정에서 얻은 교훈 42개를 마찰 로그에 기록했다고 한다. 글쓰기·엔지니어링 원칙은 오웰, 제프 베이조스, 레슬리 램포트, 프레더릭 브룩스, 켄트 벡, 낸시 레브슨의 원칙에서 영감을 얻었다고 소개한다. 모든 요구사항에 ANT 테스트를 적용해, 거짓일 수 없는 문장은 정보가 없다고 보고 다시 쓴다. 세부 내용은 글쓰기 원칙과 엔지니어링 원칙에 공개돼 있다.

플랫폼별 호출 방법과 참고 자료

SpecOps는 Superpowers, Kiro, EPIC/Reload, Spec Kit과의 전체 비교와 계획 모드와 명세 모드의 차이도 문서로 제공한다. 기여 방법은 CONTRIBUTING.md, 라이선스는 MIT에서 확인할 수 있다.