Claude Code /loop는 “한 번 더 해줘”를 사람이 계속 누르지 않게 만드는 반복 실행 장치입니다. 특히 설치된 스킬을 하나씩 불러 정밀 점검하고, 수정하고, 빌드와 테스트까지 확인하는 작업처럼 같은 절차를 여러 번 돌려야 할 때 효과가 큽니다.
이번 글은 제가 실제로 쓰는 Claude Code /loop 운용법을 기준으로 정리합니다. 목표는 단순합니다. 현재 프로젝트에 설치된 스킬을 런타임에 발견하고, 한 턴에 스킬 하나만 사용해 코드 전체를 점검한 뒤, 필요한 수정과 검증을 마치고 다음 스킬로 넘어가는 루프를 만드는 것입니다.
앞서 Android Agent Skills 글과 Android Agent 추천 글에서 스킬과 에이전트의 역할을 나눠 봤습니다. 이번에는 그 둘을 묶어 “설치된 스킬을 한 바퀴 돌며 정밀 점검하는 자동 반복 루프”로 운영하는 방법을 다룹니다.
Claude Code /loop 명령어 컨셉
Claude Code 공식 문서 기준으로 /loop는 번들 스킬 중 하나입니다. 고정 로직으로 실행되는 일부 내장 명령과 달리, 번들 스킬은 프롬프트 기반 지침을 Claude에게 제공하고 Claude가 도구를 사용해 작업을 조율하게 합니다. 공식 문서에서도 /doctor, /code-review, /batch, /debug, /loop, /claude-api 같은 번들 스킬을 같은 방식으로 호출한다고 설명합니다.
제가 쓰는 방식은 /loop 뒤에 반복해서 실행할 작업 계약을 길게 붙이는 것입니다. 예를 들어 다음처럼 던집니다.
/loop 전체 코드 정밀 점검 및 수정.이렇게만 쓰면 범위가 너무 넓습니다. 그래서 실제 작업에서는 “매 턴 서브에이전트를 정확히 1회 호출한다”, “한 턴에 다음 미완료 스킬 1개만 처리한다”, “빌드가 깨지면 커밋하지 않는다”, “완료 문구가 나오면 루프를 종료한다”처럼 제약을 붙입니다. 핵심은 반복 자체가 아니라, 반복될 때마다 같은 품질 기준과 같은 중단 조건을 적용하게 만드는 것입니다.
왜 스킬을 한 번에 하나만 돌리나
스킬을 여러 개 설치해 두면 에이전트가 많은 판단 기준을 참고할 수 있습니다. 하지만 한 번에 너무 많은 스킬을 읽고 적용하면 문맥이 흐려지고, 서로 다른 기준이 섞이며, 토큰이 아이스크림처럼 줄줄 녹습니다. 어차피 몇 차례씩 수동으로 루프를 돌릴 작업이라면, 한 턴에 하나씩 진행하고 결과를 확인하면서 다음 턴으로 넘기는 편이 더 안정적입니다.
그래서 루프의 상태는 대화 문맥만 믿지 않고 파일로 남깁니다. 저는 예시에서 skill-sweep.md를 사용합니다. 이 파일에는 설치된 스킬 목록과 완료 여부가 남고, 다시 실행하면 남은 [ ] 항목부터 이어갈 수 있습니다. 처음부터 다시 돌리고 싶으면 이 파일을 삭제한 뒤 실행하면 됩니다.
1단계: 서브에이전트 작성 요청
먼저 Claude Code에게 서브에이전트를 작성하게 합니다. 프로젝트 전용으로 쓰려면 저장소 안의 .claude/agents/에 두는 편이 좋습니다. Claude Code 문서상 프로젝트 서브에이전트는 .claude/agents/, 개인 공용 서브에이전트는 ~/.claude/agents/에 둘 수 있고, Markdown 파일의 YAML frontmatter로 이름·설명·도구·모델 등을 지정합니다.
Claude Code 프로젝트 루트에 .claude/agents/android-skill-sweep.md 서브에이전트를 만들어줘.
목적:
- 현재 설치된 스킬을 런타임에 발견해 skill-sweep.md 체크리스트를 만든다.
- 매 호출마다 체크리스트의 다음 미완료 스킬 1개만 처리한다.
- 해당 스킬의 지침을 사용해 저장소 전체를 정밀 점검하고 필요한 수정만 한다.
- 코드가 바뀌면 빌드와 단위테스트를 통과시킨 뒤 버전/CHANGELOG/commit까지 처리한다.
- 빌드나 테스트가 깨지면 커밋하지 말고 실패 상태를 보고한다.
- 에뮬레이터나 실제 기기 실행, 스크린샷은 하지 않는다.
반환 형식:
skill / findings / fix / build·commit / risk / remaining
중요:
- 스킬명은 하드코딩하지 말 것.
- 한 번 호출될 때 스킬 하나만 처리할 것.
- 완료 시 "skill sweep complete — all N skills done" 문구를 반환할 것.Code language: JavaScript (javascript)위 요청만으로도 대부분 충분하지만, 저는 아래처럼 파일 내용을 직접 넣어 두는 편을 선호합니다. 같은 팀이나 다른 프로젝트에서 재사용하기 쉽고, 루프의 규칙이 대화 중에 흐려질 가능성이 줄어듭니다.
2단계: 복붙용 서브에이전트 파일
아래 내용을 .claude/agents/android-skill-sweep.md로 저장합니다. Android 프로젝트 기준 명령을 넣었지만, 다른 프로젝트라면 빌드·테스트 명령과 버전·CHANGELOG 규칙만 바꾸면 됩니다.
---
name: android-skill-sweep
description: Process exactly one unchecked installed skill from skill-sweep.md, audit the repository with that skill, apply focused fixes, verify, and return a structured report.
tools: Read, Write, Edit, MultiEdit, Glob, Grep, Bash
model: inherit
maxTurns: 40
---
You are android-skill-sweep, a one-skill-per-run repository audit agent.
Mission:
Process exactly one installed skill per invocation. Use that skill to inspect the current repository, make only justified fixes, verify the result, update the sweep state, and return a compact report.
Hard rules:
- Do not hardcode skill names.
- Do not process more than one skill per invocation.
- Do not skip ahead.
- Do not run an emulator, physical device, screenshots, UI automation, or device-only checks. If useful, leave them as recommendations only.
- Do not commit if build or tests fail.
- Do not hide failures. Report the exact failed command and the practical next step.
- Prefer small, local, low-risk fixes over broad refactors.
- Never revert user changes unless explicitly instructed.
State file:
- Use skill-sweep.md in the project root as the persistent checklist.
- If the file does not exist, create skill-sweep.md in the project root and discover installed skills at runtime.
- Discover skills from the current Claude Code environment and accessible skill folders such as project, user, and plugin skill locations. Prefer actual SKILL.md metadata when available.
- Store each skill as an unchecked checklist item. Include the discovered source path or scope when known.
- If installed skills cannot be fully enumerated from files, record the limitation in the state file and continue with the skills visible to the session.
Checklist format:
# Skill Sweep
Generated: YYYY-MM-DD HH:mm local time
Repository: <repo path>
## Skills
- [ ] skill-name — source/scope
- [ ] another-skill — source/scope
## Log
- YYYY-MM-DD HH:mm — initialized N skills
Per invocation workflow:
1. Read skill-sweep.md.
2. Select the first unchecked skill only.
3. Load and apply that skill's instructions. If the skill has supporting references that are directly required, read only the relevant ones.
4. Audit the repository through that skill's lens.
5. If you find no actionable issue, mark that skill complete and return a no-change report.
6. If you find actionable issues, apply focused fixes.
7. When code changes, run:
- ./gradlew testDebugUnitTest
- ./gradlew assembleDebug
8. If the commands pass and code changed, update version/CHANGELOG if this repository's rules require it, then create one focused git commit.
9. If any verification command fails, do not commit. Leave the working tree with the attempted fix only if it helps the user inspect the failure; otherwise explain the safe next step.
10. Mark the skill complete only when the audit for that skill is done and any required verification has passed, or when no actionable issue exists.
11. Update the Log section with the result.
12. Return the report.
Return format:
skill: <processed skill name>
findings:
- <finding or "none">
fix:
- <changed files and summary, or "none">
build·commit:
- <commands run, pass/fail, commit hash if committed, or why no commit>
risk:
- <remaining risk or recommendation>
remaining: <number of unchecked skills left>
Completion:
If there are no unchecked skills left when invoked, return exactly:
skill sweep complete — all N skills done
Code language: PHP (php)
3단계: /loop에 넣을 실제 프롬프트
서브에이전트를 만든 뒤에는 루프 프롬프트를 실행합니다. 아래 프롬프트는 제가 쓰는 형태를 정리한 버전입니다. 핵심은 “매 턴 정확히 1회”, “다음 미완료 스킬 1개”, “빌드·테스트 실패 시 커밋 금지”, “완료 문구가 나오면 종료”입니다.
/loop 매 턴 android-skill-sweep 서브에이전트를 정확히 1회 호출해, 이 저장소의
skill-sweep.md 에 있는 "다음 미완료 스킬 1개"만 처리하게 한다.
규칙:
에이전트는 설치된 스킬을 런타임에 스스로 발견해 순회한다(스킬명 하드코딩 금지).
한 턴에 스킬 하나만 진행한다. 앞서가지 말 것.
에이전트가 반환한 리포트(skill / findings / fix / build·commit / risk / remaining)를 확인하고,
남은 스킬 수(remaining)를 그대로 전달한다.
코드가 바뀌었으면 에이전트가 빌드(assembleDebug)+단위테스트 통과 후 버전/CHANGELOG/commit
까지 마친 상태여야 한다. 빌드가 깨졌으면 커밋하지 말고 실패 상태를 보고한다.
에뮬레이터/기기 실행·스크린샷은 하지 않는다(필요하면 "권장"으로만 남긴다).
종료조건:
에이전트가 "skill sweep complete — all N skills done" 를 반환하면 루프를 종료한다.
재개:
이 프롬프트를 다시 실행하면 skill-sweep.md 의 남은 [ ] 부터 이어간다.
처음부터:
skill-sweep.md 를 삭제하고 실행하면 현재 설치 스킬로 목록을 재생성한다.Code language: JavaScript (javascript)이 프롬프트를 실행하면 첫 턴에서는 체크리스트가 없을 경우 스킬 목록을 만들고, 다음 미완료 스킬 하나를 골라 서브에이전트에게 넘깁니다. 서브에이전트는 해당 스킬의 관점으로 저장소를 점검하고, 수정이 필요하면 고친 뒤 검증합니다. 메인 세션은 리포트의 remaining 값을 보고 다음 턴에서도 같은 규칙을 유지합니다.
/loop 전체 코드 정밀 점검 및 수정은 어떻게 작동하나
/loop 전체 코드 정밀 점검 및 수정이라는 짧은 프롬프트만 던지면 Claude는 반복적으로 코드 점검과 수정을 시도할 수 있습니다. 하지만 이 경우 “어떤 기준으로”, “몇 개의 스킬을”, “언제 멈출지”, “검증 실패 시 커밋할지 말지”가 느슨합니다.
그래서 중급 사용에서는 짧은 명령보다 위의 긴 계약형 프롬프트가 낫습니다. 루프는 반복 엔진이고, 서브에이전트는 작업자이며, skill-sweep.md는 진행표입니다. 이 셋을 분리하면 루프가 길어져도 현재 처리 중인 스킬과 남은 스킬 수를 확인할 수 있습니다.
Codex에서도 같은 방식으로 쓸 수 있나
주석: 2026년 8월 4일 확인 기준으로, 이 글의 /loop 운용은 Claude Code 기준입니다. Claude Code 문서에는 /loop가 번들 스킬로 명시되어 있고, /goal 문서에서도 /loop는 시간 간격이 지나면 다음 턴을 시작하는 방식으로 비교됩니다.
Codex 쪽은 다르게 봐야 합니다. OpenAI의 Codex 문서에는 스킬을 사용할 수 있고, Codex CLI 또는 IDE 확장에서 /skills나 $skill-name으로 스킬을 호출할 수 있다고 되어 있습니다. 또한 Codex에는 큰 작업을 체크포인트와 중단 조건으로 진행하는 /goal 흐름이 문서화되어 있습니다. 하지만 제가 확인한 Codex CLI 도움말과 공식 개발자 명령 목록에는 Claude Code와 같은 의미의 /loop 슬래시 명령이 문서화되어 있지 않았습니다.
따라서 Codex에서 비슷하게 쓰려면 프롬프트를 그대로 복붙하기보다 /goal이나 일반 장기 작업 프롬프트로 바꾸는 편이 안전합니다. 예를 들면 다음처럼 쓸 수 있습니다.
/goal skill-sweep.md의 모든 설치 스킬 항목이 완료될 때까지,
매 체크포인트마다 다음 미완료 스킬 1개만 사용해 저장소를 점검하고,
필요한 수정은 테스트와 빌드로 검증하며,
검증 실패 시 커밋하지 않고 실패 리포트를 남긴다.다만 Codex의 서브에이전트, 스킬 호출 표기, 권한 정책은 Claude Code와 다릅니다. Claude Code용 .claude/agents/android-skill-sweep.md 파일을 Codex가 그대로 같은 의미로 읽는다고 가정하면 안 됩니다. Codex에서는 AGENTS.md, Codex 스킬, /skills, /goal의 조합으로 같은 운영 원칙을 옮기는 식으로 접근하는 것이 맞습니다.
실전에서 조심할 점
첫째, 스킬 목록을 하드코딩하지 않는 것이 중요합니다. 설치된 스킬은 계속 바뀝니다. 새 스킬을 설치한 뒤 처음부터 다시 돌리고 싶다면 skill-sweep.md를 삭제하고 루프를 시작하면 됩니다.
둘째, 커밋 조건을 강하게 잡아야 합니다. 루프가 길어지면 “일단 고쳤다”와 “검증됐다”가 쉽게 섞입니다. 저는 코드가 바뀐 턴에서는 testDebugUnitTest와 assembleDebug를 모두 통과한 뒤에만 커밋하도록 둡니다. 실패하면 커밋하지 않고 실패 리포트를 남기는 쪽이 나중에 복구하기 쉽습니다.
셋째, 에뮬레이터와 실제 기기 실행은 루프에서 빼는 편이 낫습니다. 자동 루프 안에서 기기 실행, 스크린샷, UI 조작까지 허용하면 시간이 길어지고 실패 원인이 복잡해집니다. 필요하면 리포트의 risk에 “추가로 기기 확인 권장” 정도로 남기고, 별도 턴에서 사람이 의식적으로 실행하는 편이 안정적입니다.
정리하면
Claude Code /loop를 스킬 점검 루프로 쓰는 핵심은 자동화 자체가 아닙니다. 반복될 작업을 “한 턴에 하나”, “상태 파일로 재개”, “검증 실패 시 커밋 금지”, “완료 문구로 종료”라는 계약으로 묶는 것입니다. 이렇게 해 두면 여러 스킬을 설치해 놓고도 한 번에 다 녹여 버리지 않고, 필요한 만큼만 차례대로 점검할 수 있습니다.
토큰은 어차피 씁니다. 다만 매번 같은 프롬프트를 손으로 다시 붙여 넣고, 어느 스킬까지 했는지 기억하고, 빌드 실패 후 커밋 여부를 확인하는 피로를 줄일 수 있습니다. 수동으로 몇 바퀴씩 돌리던 정밀 점검 루프라면, 이 정도 자동화는 충분히 값어치가 있습니다.
답글 남기기