evidentloop/sopify

Resumable, traceable AI coding — plans, handoffs, and evidence stay with the repo across hosts.

Sopify – 재개 가능하고, 계획을 우선하는 AI 코딩

무엇인가요 – Sopify는 기존 AI 코딩 어시스턴트(GitHub Codex, Anthropic Claude, Qoder, GitHub Copilot) 위에 가벼운 프로토콜 계층을 제공하는 도구입니다. 요구사항이 명확하지 않을 경우 어시스턴트가 정지되며, 계획을 기록하도록 강제하고, 그 계획과 검증 증거를 Git으로 추적되는 숨겨진 .sopify/ 폴더에 저장합니다. 나중에 동일한 리포지토리를 지원되는 어떤 호스트에서도 열면 ~go 명령어를 입력하여 저장된 워크플로우를 다음 미완료 작업부터 자동으로 재개할 수 있습니다.

왜 중요한가요 – 많은 AI 코딩 도구는 코드 생성에 바로 뛰어들기 때문에 다음과 같은 문제가 발생합니다:

사실이 확인되기 전에 조기 변경이 발생함
머신이나 LLM 호스트를 전환할 때 컨텍스트가 손실됨
설계 결정이 문서화되지 않음 Sopify는 계획 및 의사결정 단계를 프로젝트 아티팩트로 전환하여 리포지토리와 함께 이동하게 함으로써 이러한 문제를 해결합니다.

핵심 개념

개념	기능
관리되는 워크플로우	호스트가 명확화를 요청하고, 설계를 생성하며, 작업을 태스크로 분할하고, 계획을 `.sopify/plan/`에 기록합니다. 명시적으로 승인하지 않으면 코드는 생성되지 않습니다.
재개 포인터	Git 외부의 작은 로컬 파일이 어느 단계까지 진행되었는지 기억합니다. 어떤 호스트에서든 `~go`를 입력하면 계획을 읽고 다음 태스크부터 계속 진행합니다.
추적 가능성	모든 요구사항, 설계 선택, 검토 내용은 `.sopify/`에 평문/JSON 파일로 저장됩니다. 나중에 특정 코드 라인이 왜 존재하는지 확인할 수 있습니다.
호스트 독립성	동일한 `.sopify/` 파일은 Codex, Claude, Qoder, (제한적으로) Copilot에서 모두 이해되므로 팀은 어시스턴트를 전환해도 프로세스가 깨지지 않습니다.

빠른 시작 (README에서)

# 특정 호스트(Codex, 미국 영어)에 Sopify 계층만 설치
curl -fsSL https://github.com/evidentloop/sopify/releases/latest/download/install.sh \
  | bash -s -- --target codex:en-US

Python 3.11 이상 필요.

설치 후, 이미 .sopify/ 폴더를 포함한 리포지토리(또는 새 리포지토리)를 열고 다음을 실행:

~go            # 전체 워크플로우 시작 또는 재개
~go plan       # 계획만 생성, 아직 코드는 생성하지 않음
~go finalize   # 제공 증거가 준비되면 활성 계획 종료

설치 스크립트는 실행 전 검토 가능 (`curl … -o install.sh && less install.sh`). Windows 사용자는 동등한 PowerShell 스크립트를 사용할 수 있습니다.

구성 (예시)

# 리포지토리 루트에 위치하는 sopify.config.yaml
brand: auto
language: en-US
workflow:
  mode: adaptive   # strict | adaptive | minimal
  require_score: 7 # 호스트가 자동으로 진행하기 전에 필요한 최소 신뢰 점수

구성 파일은 코드와 함께 있으며, 자체적으로 버전 관리됩니다.

디렉터리 구조 (관련 부분)

.sopify/
├─ blueprint/   # 기준 설계 사양, 감소 목표
├─ plan/        # 활성 계획 + 검증 증거
└─ history/     # 아카이브된(완료된) 계획

다른 소스 파일(`sopify_writer/`, `skills/` 등)은 프로토콜을 구현하지만, 최종 사용자가 편집할 필요는 없습니다.

일반적인 워크플로우

요청 – 기능 요청 (예: 캐시 레이어 추가)
계획 – Sopify가 호스트에게 요구사항 분석, 설계 생성, 작업 분할을 요청. 계획은 .sopify/plan/에 저장됨
승인 – 계획을 승인하면 호스트가 코드 생성을 시작함
코드 생성 – 호스트가 코드를 작성하며, 각 변경 사항에 대해 원본 태스크로 연결되는 증거를 첨부함
재개 – 기능 중간에 중단해도 로컬 재개 포인터가 마지막 완료된 태스크를 기억함. 다른 호스트에서 리포지토리를 열고 ~go 입력 시 태스크 N+1에서 재개됨
완료 – 기능이 완료되면 ~go finalize로 계획과 증거를 .sopify/history/에 아카이브함

사용 사례

팀 인수인계 – 개발자가 Codex에서 기능을 시작하고, 팀원이 Claude로 인수하면 컨텍스트를 재설명하지 않고도 재개 가능
감사 가능성 – 관리자는 .sopify/plan/ 파일을 검토하여 특정 구현 결정이 왜 내려졌는지 확인 가능
다중 언어 프로젝트 – 프로토콜 파일이 언어에 독립적이므로, Python, JavaScript 등 호스트가 지원하는 언어라면 동일한 워크플로우가 적용 가능

아키텍처 스냅샷 (README에 설명됨)

프로토콜 커널 – ~go 명령어를 해석하고 재개 포인터를 관리하는 핵심 로직
기본 워크플로우 – 호스트가 명확화를 요청해야 하는 시점을 규정하는 규칙 세트 (점수 임계값, 적응 모드 등)
지식 레이어 – 계획, 설계 블루프린트, 검증 증거를 저장하는 .sopify/ 파일. Git 리포지토리와 함께 이동됨

라이선스

코드 및 구성 – Apache 2.0
문서 – Creative Commons BY 4.0

결론

Sopify는 LLM을 대체하지 않습니다. 계획을 강제하고, 결정을 보존하며, 어떤 지원되는 AI 코딩 호스트라도 이전 세션의 마지막 지점에서 정확히 재개할 수 있도록, Git으로 추적 가능한 엄격한 프로세스를 추가합니다. AI 어시스턴트에 의존하면서도 재현성과 감사 추적을 필요로 하는 팀에게 Sopify는 저오버헤드, 호스트 독립적인 솔루션을 제공합니다.