rstack

무엇인가

rstack은 코딩 에이전트가 변경을 처리하는 전 과정, 즉 브랜치 생성부터 리뷰된 풀 리퀘스트까지의 절차를 파일로 고정하는 스킬 팩이다. 규율하는 영역은 세 가지다. 작업 공간(어디서 편집하는가), 검증(무엇으로 증명하는가), 종료 조건(언제 멈추는가). 저장소는 new-feature, code-structure, evidence-driven-testing, before-and-after, greploop, greploop-apps, unslop 일곱 개의 SKILL.md 폴더와 루트의 AGENTS.md로 구성된다. AGENTS.md는 작업 종류별로 적용할 단계를 고르는 워크플로 문서이고, 각 스킬은 그 단계를 실행하는 절차를 담는다. 읽기 전용 조사나 리뷰는 모든 단계를 건너뛰고, 문서 오타 수정 같은 작은 편집은 격리 브랜치와 내용 검사만 적용한다. 즉 고정된 파이프라인이 아니라 작업 크기에 따라 단계가 켜지고 꺼지는 조건부 절차다. 각 스킬은 독립적으로도 동작하지만, AGENTS.md와 함께 둘 때 단계 순서가 강제된다. 설치 단위는 스킬 폴더별이고, 워크플로는 저장소마다 복사해 쓰는 파일이다.

어떻게 동작하나

이 규칙이 없을 때 나타나는 실패는 대체로 네 가지다. 첫째, 에이전트가 main 브랜치에서 바로 편집하고 커밋해 다른 작업과 충돌한다. 둘째, 요청 범위를 넘어 공용 함수를 뽑아내거나 계층 경계를 새로 만들면서 프로젝트의 기존 아키텍처를 덮어쓴다. 셋째, 런타임 동작을 바꾸면서도 수정 전 실패와 수정 후 성공을 기록하지 않아 "된다"는 서술만 남긴다. 넷째, 리뷰 지적이 남아 있는데도 PR을 완료로 선언한다. rstack은 이 네 지점을 각각 별도 스킬로 분리해, 에이전트가 자기 판단으로 건너뛰지 못하게 만든다. 특히 종료 조건을 "Greptile 5/5, 미해결 지적 없음"처럼 외부에서 측정 가능한 값으로 두는 것이 핵심이다. 증거 없는 완료 선언은 사람이 다시 확인해야 하는 비용으로 돌아오고, 범위를 넘은 리팩터링은 리뷰에서 되돌리는 비용으로 돌아온다. 워크트리 없이 작업하면 같은 저장소를 쓰는 다른 에이전트의 변경과 섞여 어느 커밋이 어느 작업인지 추적할 수 없게 된다. 리뷰 봇 점수를 종료 조건으로 삼는 이유도 같다. 사람이 "충분해 보인다"고 판단하는 기준은 실행마다 달라지지만, 점수와 미해결 지적 수는 커밋 단위로 비교할 수 있다.

무엇과 다른가

각 규칙은 실패를 관찰 가능한 형태로 바꾸는 방식으로 쓰였다. 격리는 "main에서 아무것도 빌드하지 않는다"는 금지 문장과 origin/main 기준 워크트리 생성 절차로 구성된다. 구조는 프로젝트의 기존 아키텍처를 우선하고, 그것이 없을 때만 서비스 레이어 패턴을 기본값으로 삼는다. 이 예외가 없으면 에이전트가 모든 저장소에 같은 구조를 강요한다. 증명은 실패 기록 → 수정 → 성공 기록 순서를 강제해, 사후에 만든 통과 로그를 구분할 수 있게 한다. 리뷰 루프는 반복 상한(--max-iterations, 기본 10)과 타임아웃, 통합 누락을 종료 사유로 명시해 무한 재시도를 막고, 상한에 걸리면 실제 점수를 그대로 보고하게 한다. 하드 제약으로 쓰인 문장은 대부분 부정형이다. "main에 커밋하지 않는다", "요청 없이 병합하지 않는다", "자기 브랜치가 아니면 force push하지 않는다". 부정형이 필요한 이유는 에이전트가 긍정형 지침을 상황에 맞게 해석해 완화하기 때문이다. 예외는 두 곳에만 둔다. 아키텍처가 없는 저장소에는 기본 패턴을 허용하고, 읽기 전용 작업에는 단계를 면제한다.

어떻게 쓰나

발동은 두 층으로 나뉜다. 스킬 층은 각 폴더의 SKILL.md이고, 에이전트가 description을 읽고 작업에 맞는 스킬을 스스로 고른다. Claude Code에서는 /new-feature, /greploop처럼 슬래시 명령으로 직접 호출할 수도 있다. 워크플로 층은 저장소 루트의 AGENTS.md이며, Cursor와 Codex는 이 파일을 루트에서 읽는다. Claude Code는 CLAUDE.md를 읽으므로 @AGENTS.md 한 줄을 담은 CLAUDE.md를 추가해 연결한다. AGENTS.md에는 다중 에이전트 규칙도 들어간다. 작업과 에이전트마다 워크트리와 브랜치를 하나씩, main 커밋 금지, --force-with-lease는 자기 브랜치에만, 요청이 없으면 병합 금지. unslop은 사람이 읽는 텍스트(커밋 메시지, PR 제목과 본문, 문서, 코드 주석)에 적용되고, 업스트림과 달리 disable-model-invocation 플래그를 제거해 슬래시 명령 없이도 자동 적용된다. 설치 후 첫 사용에서는 AGENTS.md의 "Checks in this repo" 절을 해당 저장소의 검사 명령으로 교체했는지 확인한다. 설치는 npx skills add로 하거나 스킬 폴더를 ~/.claude/skills/에 복사한다.

전제와 한계

내부 구성은 스킬별 폴더와 실행 스크립트로 나뉜다. new-feature, code-structure, greploop-apps, unslop은 SKILL.md 하나에 절차만 담고, 나머지는 보조 스크립트를 동봉한다. evidence-driven-testing은 scripts/evidence.py와 scripts/run-playwright.sh, scripts/playwright/를 두고, recorder는 doctor·start·annotate·stop 네 명령으로 동작해 evidence.mp4, report.md, manifest.json을 남긴다. before-and-after는 scripts/upload-and-copy.sh와 scripts/adapters/로 @vercel/before-and-after CLI를 감싸고, greploop은 scripts/github_review.py와 references/를 둔다. 각 폴더에는 LICENSE가 따로 붙고, tests/에는 recorder와 리뷰 헬퍼, Playwright 러너를 검증하는 pytest 스위트가 있다. AGENTS.md는 단계 이름과 다중 에이전트 규칙을 담은 워크플로 문서로, 스킬 폴더 밖 저장소 루트에 놓인다.

프롬프트를 매번 직접 쓰는 방식과의 차이는 재사용 단위다. rstack은 절차를 SKILL.md 폴더로 쪼개 두고 에이전트가 description으로 골라 쓰게 하므로, 같은 지시를 대화마다 다시 입력하지 않는다. 단일 CLAUDE.md에 모든 규칙을 몰아넣는 방식과도 다르다. 규칙 본문은 스킬에 남기고 워크플로만 AGENTS.md로 분리해, 다른 저장소에는 AGENTS.md 한 장과 검사 항목만 바꿔 끼우면 된다. 플러그인과 비교하면 배포 형식이 파일 묶음이다. 설치 CLI가 붙어 있지만 실행 코드는 Python과 Bash 스크립트로 저장소 안에 들어 있고, pytest 스위트가 함께 온다. 선언만 하는 규칙 파일이 아니라 검사 가능한 도구를 포함한 스킬 팩이다. unslop은 업스트림 본문을 그대로 두고 frontmatter에서 disable-model-invocation을 빼 자동 적용 범위를 넓힌 점이 다르다.

설치는 npx skills add michaelshimeles/rstack 한 줄로 끝난다. --list는 설치 없이 목록만 보고, -s는 스킬을, -a는 에이전트(claude-code, cursor, codex)를 고르며, -g는 프로젝트가 아니라 사용자 레벨에 넣는다. 수동 설치는 저장소를 클론한 뒤 mkdir -p ~/.claude/skills/로 디렉터리를 만들고 일곱 폴더를 cp -r로 복사한다. greploop-apps는 greploop 옆에 함께 설치해야 동작한다. 워크플로를 쓰려면 AGENTS.md를 대상 저장소 루트에 복사하고 "Checks in this repo" 절을 그 저장소의 검사 명령으로 바꾼다. Claude Code는 CLAUDE.md를 읽으므로 @AGENTS.md 한 줄을 담은 CLAUDE.md를 추가한다. 첫 사용에서는 스킬 폴더에서 python3 scripts/evidence.py doctor를 돌려 ffmpeg 구성과 libx264, ass 필터를 확인하고, greploop을 쓸 저장소라면 gh 인증과 Greptile 설치 여부를 먼저 점검한다.

의존성은 스킬마다 다르다. evidence-driven-testing의 recorder는 Python 3와 libx264, ass 필터를 포함한 ffmpeg/ffprobe를 요구하고 Linux, macOS, Windows에서 돈다. headless 헬퍼 run-playwright.sh는 Node 20+와 npm이 필요하며, 프로젝트 밖 임시 디렉터리에 고정 버전 Playwright를 설치한다. greploop은 저장소에 Greptile이 설치되어 있고 gh, glab, p4 중 하나가 인증되어 있어야 하며, github_review.py는 Python 3.10+를 요구한다. before-and-after는 npm i -g @vercel/before-and-after agent-browser로 설치하고, 기본 업로드 호스트 0x0.st가 공개이므로 민감한 자료에는 --upload-url을 넘겨야 한다. greploop-apps는 자체 구현이 없어 greploop 없이는 쓸 수 없다. 테스트는 합성 입력과 로컬 API 픽스처를 쓰므로 실제 업로드, 모든 네이티브 캡처 백엔드, 라이브 Greptile 리뷰는 검증하지 않는다.

선택 기준은 저장소 상태로 갈린다. Greptile이 붙어 있고 gh 인증이 되어 있으면 greploop을 종료 조건으로 쓰고, 둘 중 하나가 없으면 리뷰 루프를 빼고 사람 리뷰로 대체한다. 런타임 동작이 바뀌는 변경이면 evidence-driven-testing을 적용하고, 문서나 주석만 바뀌면 격리 브랜치와 내용 검사로 줄인다. 프로젝트에 이미 계층 경계가 있으면 code-structure는 그 구조를 따르게 하고, 아키텍처가 없는 저장소에서만 서비스 레이어를 기본값으로 쓴다. 에이전트 하나가 작은 작업을 할 때는 스킬만 설치해도 되고, 여러 에이전트가 같은 저장소를 공유하면 AGENTS.md의 워크트리·브랜치 규칙을 함께 둔다. 화면 변화가 리뷰 판단에 영향을 주면 before-and-after를, 사람이 읽는 텍스트가 산출물이면 unslop을 붙인다.