원문 캡처 · github.com
원문 캡처 · github.com

SPIDER는 AI 코딩 에이전트가 불필요한 구조를 만들거나 기존 기능을 깨뜨리는 일을 줄이도록, 작업을 8개 역할로 나누고 별도 검증 절차를 두는 저장소 기반 프로토콜이다. Codex, Claude Code, OpenCode, Gemini·Antigravity 환경에 설치할 수 있으며 Python 3.10 이상이 필요하다.

SPIDER의 작업 방식

SPIDER는 한 번의 프롬프트로 코드를 만드는 에이전트가 첫 버전 이후의 반복 작업에서 과도한 설계, 대화 기록에 의존한 맥락 상실, 자기 작업을 스스로 채점하는 문제, 버그 수정 중 발생하는 회귀를 일으킬 수 있다고 설명한다. 이에 따라 S.P.I.D.E.R.의 6개 단계(Specify, Plan, Implement, Document, Evaluate, Review)와 8개 전문 역할을 두고, 변경 사항과 판단을 저장소 안의 Markdown·YAML 파일에 기록한다.

작업은 먼저 spider-orchestrator가 요청을 확인하고 최소 변경 기준을 제안하는 것으로 시작한다. 사용자가 확인한 뒤 requirements.md에 REQ-N을 기록한다. 기존 구성 요소 하나 안에서 끝나는 국소적이고 테스트된 변경은 빠른 경로로 planner에게 전달한다. 그 밖의 변경은 architect가 영향 범위, 계획의 최신성, UI 설계 필요 여부를 검토한 뒤 계획 단계로 넘긴다. UI 설계가 필요하면 ui-designer가 features/<slug>/design.html을 작성한다.

planner는 불필요하게 복잡한 설계를 동료 관점에서 문제 삼고, 서로 연결된 작업을 가능한 한 적은 단위로 나눈다. 각 작업에는 재개할 수 있는 유형 지정 STEPS를 둔다. 실행자는 승인된 단계 안에서만 코드를 수정하고 상태를 Pending → Active → Ready for validation으로 진행한다. 한 번에 Active 상태가 될 수 있는 작업은 하나다.

실행자는 자신이 한 작업을 Done으로 표시하지 못한다. 독립적인 task-validator가 요구사항과 단계의 연결, Git diff, 프로젝트의 회귀 테스트 전체를 확인한 뒤에만 완료로 표시한다. 검증에서 기계적인 단계 오류가 발견되면 실행자에게, 결함이나 회귀가 발견되면 debugger에게, 작업 계획의 누락이면 planner에게, 설계 경계의 문제면 architect에게 되돌린다. 복구와 검토 과정에는 오케스트레이터와 사람이 참여하며, 요구사항을 닫기 전 결정·반복 점검 지점을 둔다.

저장소의 기억은 코드와 함께 커밋하는 사람이 읽을 수 있는 파일에 둔다. project.md와 requirements.md는 프로젝트 상태와 요구사항의 중심 허브 역할을 한다. 기능별 작업 파일은 허브에서 갈라지는 작업 단위이며, ## LOG에는 반복 기록을 남긴다. decisions.md와 Git 이력은 변경을 추적하고 복구할 수 있도록 결정과 변경의 흔적을 보존한다. 완료된 작업 기록을 정리할 때도 요구사항의 승인 근거, task-index.yaml의 단조 증가형 tombstone, 변경할 수 없는 결정 기록은 유지한다.

SPIDER는 첫 세대 명세 기반 개발(SDD) 도구가 비구조적인 바이브 코딩보다 명세를 앞세웠지만, 기존 코드가 있는 저장소에서 작은 수정에도 절차가 무거워지거나 AI가 만든 과도한 구조를 그대로 받아들이고 실행 주체가 스스로 결과를 채점하는 문제가 생길 수 있다고 지적한다. SPIDER는 이를 줄이기 위해 사전 최소 변경 기준, 설계자와 기획자 사이의 KISS 검토, 엄격한 작업 단계, 독립 검증을 결합했다고 설명한다. 새 파일·클래스·의존성을 추가하려면 사용자의 명시적 승인이 필요하다. 실행 단계는 [create], [modify], [delete], 읽기 전용 [reference], [run]으로 구분한다.

역할과 저장소 기록

8개 역할은 다음 책임을 맡는다.

  • spider-orchestrator는 요청 사전 확인, 최소 변경 기준에 대한 승인, REQ-N의 생애주기, 초기 분류, 정확한 작업 지정, 복구 루프와 사용자 확인 지점을 관리한다.
  • architect는 구조적 영향, 계획의 최신성, UI 설계 필요성을 따로 평가한다. 구조 경계에 관한 결정, build-plan.md, blast-radius-summary.md를 맡는다.
  • ui-designer는 작업 계획 전에 사용자 흐름, 화면 상태, 상호작용 조건을 담은 독립형 접근성 고려 UX/UI 명세를 features/<slug>/design.html에 작성한다.
  • planner는 KISS 원칙에 따라 불필요한 복잡성을 문제 삼고, 필요한 작업 수를 줄이며, features/<slug>/tasks/tN-*.md에 유형 지정 STEPS를 기록한다.
  • task-executor는 정확히 지정된 작업의 승인 범위 안에서 구현한다. 상태를 Pending → Active → Ready for validation으로 바꾸지만 스스로 Done 처리하지 않는다.
  • task-validator는 상위 계약 전체, Git diff, 회귀 테스트를 감사하고 features/<slug>/validation/tN-validation.json을 작성한다. 배포 작업을 Done으로 표시할 수 있는 유일한 역할이다.
  • debugger는 검증 실패나 사용자가 보고한 버그를 가설 검증으로 조사한다. features/<slug>/defects/에 결함 기록을 남기고 승인된 국소 수정만 적용한다.
  • doc-cleanup은 완료된 작업 파일과 오래된 자료를 정리하되 요구사항 승인 근거, task-index.yaml의 tombstone, 변경 불가 결정 기록을 보존한다.

프로젝트 초기화 시 생성되는 주요 상태 파일은 다음과 같다.

  • project.md: 프로젝트 개요, 현재 상태, 진행 중·완료 작업 표
  • requirements.md: 오케스트레이터가 관리하는 요구사항·인수 기준 등록부와 검증 이력
  • decisions.md: D1, D2 등의 순차적 구조 결정 기록
  • task-index.yaml: 작업 상태, 요구사항 추적, 단조 증가형 high-water mark
  • architecture/architecture.md와 architecture/flows.md: 시스템 구조와 주요 실행·프로토콜 흐름
  • features/<feature-slug>/requirements.md: 상세 요구사항 계약과 확인된 최소 변경 기준
  • features/<feature-slug>/blast-radius-summary.md: 아키텍처 영향 검토와 분류 정보
  • 구조 변경이 있을 때의 features/<feature-slug>/build-plan.md, UI 설계가 필요할 때의 features/<feature-slug>/design.html
  • features/<feature-slug>/tasks/t1-<slug>.md: 목표, 유형 지정 단계, 현재 상태, 로그를 담은 작업 계약
  • features/<feature-slug>/validation/t1-validation.json: 구조화된 검증 보고서
  • features/<feature-slug>/defects/bug-req-N-<slug>.md: 디버거의 근본 원인 분석 기록

SPIDER 저장소는 이 프로토콜을 첫 세대 도구와 비교하며, BMAD-METHOD의 에이전트 페르소나 방식, GitHub Spec Kit의 명령 파이프라인, Superpowers의 조합형 기술, OpenSpec·GSD의 기존 코드 변경 명세와 차이를 제시한다. SPIDER는 최소 변경 기준과 기획자의 설계 검토, 전용 디버거, 작업 후 검증을 특징으로 든다. 이는 저장소가 설명하는 비교이며 독립적인 성능 평가 결과는 제시되지 않았다.

설치와 사용

설치 프로그램과 SHA-256 검증기는 외부 패키지 없이 Python 3.10 이상에서 실행된다. 먼저 저장소를 복제한다.

bash
git clone https://github.com/Algoza-Solutions/spider-protocol.git
cd spider-protocol

Codex는 ~/.codex/skills, Claude Code는 ~/.claude/agents, OpenCode는 ~/.config/opencode/skills, Gemini·Antigravity는 ~/.gemini/config/skills에 설치할 수 있다. 지원되는 환경 전체에 설치하거나 하나를 지정하려면 다음 명령을 사용한다.

bash
# Install into all supported environments (Codex, OpenCode, Gemini/Antigravity, Claude Code)
python scripts/install.py --target all

# Or install into a specific environment:
python scripts/install.py --target codex
python scripts/install.py --target claude
python scripts/install.py --target opencode
python scripts/install.py --target gemini

기존 프로젝트나 새 프로젝트에 상태 파일을 초기화한다.

bash
python scripts/install.py --init-project /path/to/your/project

프로젝트를 코딩 에이전트에서 열고 spider-orchestrator를 호출한다. Claude Code에서는 @orchestrator를 사용할 수 있다. 저장소가 제시하는 요청 예시는 다음과 같다.

text
"Use spider-orchestrator: Add rate limiting to the `/api/login` endpoint using our existing Redis client."

오케스트레이터는 코드베이스를 읽기 전용으로 살펴 최소 직접 변경 기준을 제안하고, 새 파일이나 구조가 필요한지 밝힌다. 사용자 확인 전에는 requirements.md에 REQ-1을 기록하지 않는다. 확인 뒤에는 빠른 경로나 Architect에서 Planner로 이어지는 경로를 택해 작업을 실행하고, 검증기가 diff와 테스트 모음을 확인한다.

역할 계약 묶음은 spider-orchestrator에 포함된 검증기가 확인한다. 이 검증기는 manifest 버전, 역할 디렉터리 구조, frontmatter, 7개 전문 기술 파일 전체의 줄바꿈 정규화 SHA-256 다이제스트를 검사한다. 저장소는 동작 회귀 테스트 22개도 제공한다.

bash
# Verify the repository skill bundle
python skills/spider-orchestrator/scripts/verify_specialist_skills.py --codex-home .

# Run the 22-test behavioral regression suite
python -m unittest discover -s skills/spider-orchestrator/scripts -v

구조와 역할 경계는 프로토콜 아키텍처 문서, 빠른 경로와 복구 흐름은 라우팅·복구 문서, 용어 설명은 SPIDER 용어 문서, 역할 계약과 manifest 해시 갱신 방법은 기여 안내에서 확인할 수 있다.

SPIDER는 MIT License로 배포된다. 저장소에서 설치와 문서를 확인할 수 있다.