| name | guardrails-learning-loop |
| description | 같은 체크가 같은 방식으로 두 번 실패하면 그 실패를 `.ralph/guardrails.md`에 '가드레일 사인'으로 적어 두고, 다음 반복부터는 똑같은 실수를 되풀이하지 않게 만드는 학습형 자동화 루프입니다. 매 반복마다 가드레일을 먼저 읽고 → 체크(`npm test && npm run lint`)를 돌리고 → 실패가 반복되면 사인을 추가하고 → 그 사인을 지키며 고칩니다. 사용자가 "같은 실패 반복하지 말고 기록하면서 고쳐줘", "가드레일에 적어가며 학습하는 루프", "실패 패턴 메모하고 피해가게", "두 번 깨진 건 다시 안 깨지게", "guardrails learning loop", "append a guardrail sign", "learn from repeated failures and stop repeating them"처럼 요청하거나, 반복되는 실패를 디스크에 남겨 다음 회차가 피하도록 하고 싶을 때 사용하세요. (구분: 디버깅 회고를 디스크에 적어 같은 오답을 피하는 건 looping:reflexion-debug-loop, prd.json 스토리를 .ralph 상태로 하나씩 실행하는 건 looping:ralph-story-executor, 그냥 테스트만 green까지 돌리는 건 looping:test-until-green, lint+typecheck만 정리하는 건 looping:lint-typecheck-fix) |
가드레일 학습 루프 (Guardrails Learning Loop)
체크가 같은 방식으로 두 번 실패하면 .ralph/guardrails.md에 가드레일 사인을 적어, 다음 반복이 같은 실수를 되풀이하지 않게 한다.
| 항목 | 값 |
|---|
| 카테고리 | 자동화(Automation) |
| 트리거 | 수동(manual) — 사람이 직접 시작 |
| 종료 조건(Exit) | 모든 체크(테스트 + lint)가 통과하고, 반복되는 실패 패턴이 남아 있지 않을 때 |
| 반복 한도(Max iterations) | 12 |
| 매 반복 체크 명령 | npm test && npm run lint |
| 설치 파일 | 있음 — .ralph/guardrails.md 스캐폴딩(선택) |
| 가드레일 | 강화됨(Hardened) |
| 지원 에이전트 | Claude Code · Cursor · Codex |
이 루프는 언제 쓰나
에이전트가 자동으로 고치다 보면 같은 실패를 다른 회차에서 또 만드는 일이 생깁니다. 한 번 무너진 자리에서 똑같은 잘못된 접근을 반복하는 거죠. 이 루프는 그 망각을 막습니다. 같은 에러가 두 번째로 나오면, "무엇이 실패했고 어떻게 피하는지"를 한 줄짜리 가드레일 사인으로 .ralph/guardrails.md에 적어 두고, 이후 모든 반복은 그 사인을 하드 제약으로 취급합니다. 메모리는 채팅 히스토리가 아니라 디스크에 쌓이므로, 컨텍스트가 바뀌어도 학습이 살아남습니다.
핵심은 기록 → 준수입니다. 실패를 단순히 다시 고치는 게 아니라, 같은 함정을 다음 회차가 자동으로 피하도록 누적된 규칙으로 굳혀 갑니다.
루프 흐름
수동 시작 → 가드레일 읽기 → 체크 실행 → 실패 사인 기록 → 가드레일대로 수정 →〔피드백 게이트〕
체크 통과 & 반복 실패 패턴 없음?
↑ │ 아니오: 다음 반복
└──────────────────────────┘
│ 예
종료
매 반복(pass)마다 하는 일
- 가드레일 읽기 — 어떤 작업이든 시작하기 전에
.ralph/guardrails.md를 먼저 읽습니다. 거기 적힌 사인 하나하나를 하드 제약으로 취급합니다.
- 체크 실행 — 프로젝트의 backpressure 명령을 돌립니다.
npm test && npm run lint
- 실패 사인 기록 — 같은 에러가 이전에도 났던 거라면, 간결한 사인을
guardrails.md에 덧붙입니다: 무엇이 실패했고 어떻게 피하는지.
- 가드레일대로 수정 — 모든 가드레일 사인을 존중하는 방식으로 고칩니다. 이전에 실패했던 접근을 반복하지 않습니다.
가드레일 (점수 조작 방지 규칙)
종료 조건을 "가짜로" 통과시키지 못하게 막는 규칙입니다. 에이전트는 반드시 지켜야 합니다.
- 체크 명령이나 종료 기준을 고쳐서 억지로 성공시키지 않는다.
- 체크를 건너뛰거나 비활성화·우회해서 종료 조건을 통과시키지 않는다.
- 여러 번 반복해도 막히면, 지표를 조작하지 말고 멈추고 블로커를 보고한다.
Claude Code에서 실행하기
이 루프는 수동(manual) 트리거입니다. 가장 간단합니다. 아래 kickoff 프롬프트를 그대로 붙여넣으면 에이전트가 스스로 반복합니다.
"가드레일 학습 루프(Guardrails Learning Loop)" 루프를 시작합니다.
목표: 이전 실패 패턴을 반복하지 않으면서 테스트와 lint를 통과시키기
최대 반복: 12
매 반복 사이 실행: npm test && npm run lint
종료 조건: 모든 체크가 통과할 때
1단계: .ralph/guardrails.md를 읽고 체크를 실행한다. 실패가 반복되면 고치기 전에 사인을 추가한다.
이 루프를 스스로 페이싱(self-pace)하라. 매 반복 후 체크 명령을 실행하고 출력을 읽어, 종료
조건이 충족되지 않았을 때만 계속한다. 종료 조건이 통과하거나 최대 반복에 도달하면 멈춘다.
매 회차마다 한 줄 상태 업데이트를 남긴다.
준비 — 가드레일 파일: 이 루프는 .ralph/guardrails.md에 사인을 누적합니다. 원본 사이트는 이 파일을 미리 깔아 주는 install files(zip)를 제공하지만, Claude Code에서는 굳이 받을 필요 없이 빈 파일 하나(mkdir -p .ralph && touch .ralph/guardrails.md)만 만들어 두거나, 파일이 없으면 에이전트가 첫 회차에 만들게 해도 충분합니다.
팁 / 변형
- 체크 명령 교체:
npm test && npm run lint는 예시입니다. 프로젝트에 맞게 pytest && ruff check, go test ./... && go vet ./..., cargo test && cargo clippy 등으로 바꾸세요.
- 사인은 짧게: 가드레일 사인은 "무엇이 실패했고 어떻게 피하는지" 한 줄로 간결하게. 길어지면 다음 회차가 제약을 놓칩니다.
- 막힐 때: 같은 실패가 두 번 나면 사인을 추가하지만, 사인을 더해도 안 풀리면 가드레일대로 멈추고 가설과 함께 사람에게 보고하게 하세요 — 지표를 조작하지 말고.
- 연관 루프: 디버깅 회고를 디스크에 적어 같은 오답을 피하는 건
looping:reflexion-debug-loop, prd.json 스토리를 fresh-context로 하나씩 실행하는 건 looping:ralph-story-executor, 전체 스위트를 green까지만 돌리는 건 looping:test-until-green.
원본 영어 kickoff (loops.elorm.xyz 원문)
Start the "Guardrails Learning Loop" loop.
Goal: tests and lint pass without repeating prior failure patterns
Max iterations: 12
Between iterations run: npm test && npm run lint
Exit when: all checks pass
Step 1: Read .ralph/guardrails.md, run checks, and if a failure repeats, add a sign before fixing.
Self-pace this loop. After each iteration, run the check command, read the output, and only continue if the exit condition is not met. Stop when the exit condition passes or max iterations is reached. Give a short status update each pass.
출처: https://loops.elorm.xyz/loops/guardrails-learning-loop
