shuxueshuxue/Spexcode

해결하는 문제

SpexCode는 AI 코딩 에이전트가 소스 코드를 수정하는 속도가 코드를 설명하는 문서(사양)를 업데이트하는 속도를 뛰어넘는 '사양 이탈(spec drift)' 문제를 해결합니다. 이로 인해 문서가 시스템의 실제 동작을 정확히 반영하지 못하는 상태가 되는 경우가 자주 발생합니다.

작동 방식

SpexCode는 .spec/ 디렉터리에 마크다운 파일로 사양을 저장하는 Git 기반 시스템을 생성합니다. 각 사양은 코드 내 특정 파일이나 함수에 '앵커'로 연결됩니다. Git 커밋을 분석하여, 앵커 범위 내의 코드가 변경되었지만 해당 사양이 업데이트되지 않은 경우를 '앵커 이탈(anchor-drift)'로 식별합니다.

이탈을 해결하기 위해 사용자는 사양을 코드에 맞게 업데이트하거나, 구현 변경이 기존 계약을 여전히 충족함을 명시적으로 승인(ack)해야 합니다.

이 시스템은 세 가지 계층으로 구성됩니다:

1. L0 (사양-코드 그래프): Git에서 사양과 코드 간의 핵심 연결.
2. L1 (에이전트 세션): 각 에이전트에 대해 격리된 worktree와 브랜치를 사용하여 변경 사항이 추적되고, 관련 사양에 연결되도록 합니다.
3. L2 (대시보드): 세션 검토 및 사양 관리를 위한 GUI.

대상 사용자

Claude Code 또는 Codex와 같은 AI 코딩 에이전트를 사용하여 기술 사양과 구현 간의 엄격한 동기화를 유지하고자 하는 개발자.

주요 기능

• 결정론적 이탈 탐지: Git 이력을 사용해 사양이 코드를 더 이상 설명하지 않게 된 정확한 시점을 계산.
• Git 네이티브: 별도의 데이터베이스를 저장하지 않으며, 모든 이탈 및 버전 관리 데이터는 Git 커밋에서 유도.
• 에이전트 격리: tmux를 통해 에이전트를 별도의 브랜치와 worktree에서 실행하여 간섭을 방지.
• 통합: Claude Code 및 Codex용 플러그인, CLI, 전용 대시보드 제공.
• 강제 적용: 앵커 이탈이 감지되면 Git 훅을 통해 커밋을 차단할 수 있음.