huisezhiyin/sdd-riper

Lightweight AI Agent Harness for agentic coding: let strong models explore while humans steer with minimal specs, checkpoints, approval, validation, and reverse sync.

SDD‑RIPER Light – 코드 에이전트를 위한 제어 플레인

무엇인가요 – 대규모 언어 모델(LLM) 코드 에이전트가 실제 코드베이스에서 작업할 수 있도록 해주는 매우 작고 리포지토리 내재형 프레임워크입니다. 인간이 목표, 경계, 승인, 증거를 관리하는 역할을 유지합니다. 이는 프롬프트를 대체하려는 것이 아니라, 에이전트의 워크플로우를 명확한 체크포인트, 사양, 검증 단계, 프로젝트로의 되돌릴 수 있는 동기화로 구조화하는 경량한 '하네스'를 추가합니다.

왜 중요한가요 – 현대의 LLM은 이제 파일을 수정하고 도구를 실행하며 결과를 검증할 수 있습니다. 버블넥은 코드 작성에서 활동 제어로 이동했습니다. 작업이 관찰 가능하고, 복구 가능하며, 감사 가능하도록 유지하기 위한 것입니다. SDD‑RIPER는 무거운 사양 중심 프로세스를 강제하지 않고도 그 제어를 제공합니다.

핵심 개념

개념	역할
인간이 소유	목표, 경계, 권한, 체크포인트, 수용 기준, 완료 증거
에이전트가 소유	탐색, 구현, 반복, 도구 사용
프로젝트가 보존	사양, 컨텍스트 인덱스, 검증 증거, 복구 상태, 재사용 가능한 지식

이 프레임워크는 LLM이 호출할 수 있는 4가지 '스킬'(작고 자가 완결형 스크립트 또는 프롬프트)을 중심으로 구성됩니다:

sdd‑riper‑one‑light – 일상적인 코딩, 문서 편집, 버그 수정, 일반적인 리팩터링을 위한 기본적인 저부하 하네스입니다. 동일한 핵심 규칙(작업 재제시, 사양 요구, 승인 대기, 완료 증명)을 적용하지만, 최소한의 게이트로 실행됩니다.
sdd‑riper‑one – 고위험 작업, 다중 파일 리팩터링, 감사 대응 추적, 또는 훈련 데이터 수집을 위한 엄격한 버전입니다. 더 풍부한 사양과 밀도 높은 아티팩트를 추가합니다.
codemap – 익숙하지 않거나 대규모 코드베이스를 위한 코드 지형 인덱스를 생성합니다. 에이전트는 엔트리 포인트, 호출 체인, 리스크 지점, 다음에 읽을 최소 코드 조각을 특징화하는 지도를 생성합니다.
new‑chat‑ready – 다른 엔지니어나 LLM으로의 인수인계, 장기간 중단, 또는 새로운 채팅 세션을 위한 간결한 '레주메 팩'을 패키징합니다. 보호된 브랜치에서 리포지토리를 스냅샷하고, 민감한 데이터를 정제하며, 선택적으로 직접 Codex 스레드를 생성합니다.

일반적인 세션의 흐름

컨텍스트 읽기 – 에이전트는 현재 루프에 필요한 최소한의 리포지토리 슬라이스를 로드합니다.
목표 및 리스크 재제시 – 에이전트는 작업을 반복하고, 핵심 목표를 식별하며, 최소 사양과 '완료 계약'(무엇이 완료로 간주되며, 어떻게 증명할지)을 제시합니다.
체크포인트 – 인간은 재제시, 사양, 검증 계획을 검토하고, 파일 변경 전에 명시적으로 승인해야 합니다.
실행 – 에이전트는 변경 사항을 적용하고, 도구/테스트를 실행하며, 증거를 수집합니다.
검증 – 증거(테스트, 로그, 스크린샷, 수동 검사)가 '완료 계약'과 비교됩니다.
역동기화 – 검증된 결론은 사양, 인수인계 문서, 또는 프로젝트 메모리에 다시 기록됩니다.

모든 단계에서 활성 컨텍스트는 작게 유지되고, 채팅 외부에 내구성 있는 상태를 보존함으로써 복구성과 감사 가능성을 보장합니다.

빠른 시작 프롬프트 (일상적인 작업용)

이 작업에는 sdd-riper-one-light를 사용하세요.
파일 변경은 아직 하지 마세요.

먼저 다음을 알려주세요:
- 작업에 대한 이해
- 이 루프의 핵심 목표
- 최소 사양 / 요약
- 완료 계약: 무엇이 완료로 간주되며, 무엇이 그것을 증명하는가
- 다음 행동
- 리스크
- 검증 방법

실행 전에 승인을 기다리세요.

다른 스킬에도 동일한 패턴이 적용되며, 스킬 이름만 바꾸고 요청을 조정하면 됩니다 (예: codemap에게 코드 지형 인덱스 생성을 요청).

리포지토리 구조 (모든 프로젝트에 추가해야 할 사항)

<repo>/
  AGENTS.md                # 프로젝트 고유의 에이전트 규칙
  skills/
    codemap/
    new-chat-ready/
    sdd-riper-one-light/
    sdd-riper-one/

AGENTS.md는 리포지토리 내부에 로컬로 보관하거나, 시스템 전체 템플릿(examples/global-agents.md)으로 사용할 수 있습니다.
네 가지 스킬 디렉터리는 LLM이 필요로 하는 프롬프트, 템플릿, 참조 문서가 포함되어 있습니다.

어떤 스킬을 언제 사용할지

스킬	이상적인 시나리오
`sdd‑riper‑one‑light`	일상적인 코딩, 문서 작업, 버그 수정, 저위험 리팩터링
`sdd‑riper‑one`	고위험 작업, 다중 파일 변경, 감사 또는 훈련 데이터 수집
`codemap`	대규모 또는 레거시 코드베이스에서 처음 작업할 때
`new‑chat‑ready`	다른 엔지니어나 LLM으로 인수인계, 장기간 중단, 컨텍스트 리셋

안전성 및 위생 규칙 (README에서)

사양 없음 → 코드 없음 – 어떤 구현도 수행하기 전에 최소한의 진실 원천이 존재해야 합니다.
승인 없음 → 실행 없음 – 각 체크포인트마다 인간이 명시적으로 승인해야 합니다.
증거 기반 완료 – '완료'를 증명하려면 테스트, 로그, 스크린샷, 수동 검사가 필요합니다.
역동기화 – 검증된 결과는 사양이나 프로젝트 메모리에 다시 기록됩니다.
런타임 데이터, 시크릿, 개인 로그를 커밋하지 마세요 – .agent-memory/, .expcap/, .env 등을 .gitignore에 포함하세요.
캡처된 세션을 커밋하기 전에 예제를 정제하세요.

누가 이득을 볼 수 있을까?

실제 코드 변경에 LLM을 활용하면서도 통제력을 유지하고 싶은 개인 개발자.
감사 기록과 명확한 인수인계 프로토콜이 필요한 팀에서 내부 '코딩 에이전트'를 구축하는 사람.
무거운 사양 중심 파이프라인을 도입하지 않고도 AI 보조 개발 워크플로우를 체계화하고 싶은 조직.

시작하기

리포지토리를 클론하고 skills/ 폴더를 자신의 프로젝트에 복사합니다.
AGENTS.md를 생성하거나 제공된 템플릿을 사용하여 프로젝트 고유의 규칙을 정의합니다.
LLM(예: Claude, Codex, GPT‑4)과 함께 빠른 시작 프롬프트를 실행하고 체크포인트 루프를 따릅니다.
익숙하지 않은 코드베이스의 경우 먼저 codemap을 호출하세요. 인수인계의 경우 new‑chat‑ready를 호출하세요.

더 알아보기

skills/sdd-riper-one-light/README.md – 작동하는 하네스로 가는 가장 짧은 길.
docs/code-is-cheap.md – 프레임워크의 철학적 동기.
docs/ai-coding-harness-guide.md – 작업 분할, 검증, 복구에 대한 자세한 가이드.
docs/general-purpose-agents-are-a-trap.md – 왜 특화되고 제어된 에이전트가 일반적인 '일반 목적' 봇보다 종종 더 나은가.

결론

SDD‑RIPER Light는 새로운 LLM 모델이 아닙니다. 기존의 코딩 에이전트가 실제 리포지토리에서 안전하고 투명하게 작동할 수 있도록 해주는 제어 플레인입니다. 명시적인 목표, 사양, 승인, 증거를 강제함으로써, 엔지니어링의 가치는 순수한 코드 생성에서 AI 기반 작업의 오케스트레이션으로 전환됩니다.