pua-loop

pua-loop 스킬 개요

pua-loop는 무엇에 쓰는 스킬인가

pua-loop는 길고 여러 단계로 이어지는 구현 작업에서, 에이전트가 중간중간 질문을 멈추고 묻지 않도록 반복 실행하게 만드는 루프 실행 스킬입니다. 자율 재시도 루프와 저장소의 pua:pua 동작 규칙을 결합해, 에이전트가 완료를 선언할 수 있을 때까지 작업을 점검하고, 검증하고, 수정하고, 다시 실행하도록 설계되어 있습니다.

pua-loop가 가장 잘 맞는 경우

pua-loop skill은 로컬에서 검증 가능한 코딩 작업이나 워크플로 작업을 하는 사용자에게 가장 잘 맞습니다. 예를 들면 버그 수정, 리팩터링, 기능 마무리, 테스트 복구, 반복적인 정리 작업 같은 경우입니다. 특히 pua-loop for Workflow Automation은 몇 가지 불완전한 가정을 감수하더라도, 작업 중단 비용이 더 큰 상황에서 유용합니다.

사용자가 실제로 해결하고 싶은 일

대부분의 사용자가 원하는 것은 “똑똑한 프롬프트” 자체가 아니라, 범위가 정해진 작업을 넘겨두고 몇 분마다 에이전트를 지켜보지 않아도 되는 방식입니다. pua-loop는 바로 그 위임을 위해 만들어졌습니다. 핵심 약속은 자율 반복입니다. 현재 상태를 확인하고, 변경을 가하고, 검증을 실행하고, 실패를 진단하고, 다시 계속합니다.

pua-loop가 다른 점

pua-loop의 가장 큰 차별점은 지속성에 대한 강한 전제입니다. 이 스킬은 루프 모드 중 사용자에게 질문하는 것을 명시적으로 금지하고, 포기하기 전에 가능한 대안을 충분히 소진할 것을 요구합니다. 또한 로컬 파일로 루프 상태를 유지하므로, 일반적인 일회성 프롬프트보다 컨텍스트 압축 이후에도 동작이 더 잘 이어집니다.

도입 전 꼭 알아둘 점

이 스킬은 범용적인 “코딩을 더 잘하게 해주는” 도구가 아닙니다. pua-loop는 성공 조건이 명확하고, 이를 확인할 수 있는 검증 수단이 있을 때 가장 강합니다. 반대로 작업이 모호하거나, 제품 판단이 자주 필요하거나, 외부 승인에 의존한다면 일반적인 대화형 프롬프팅이 대체로 더 안전합니다.

pua-loop 스킬 사용 방법

본격적으로 쓰기 전에 설치 맥락부터 확인하기

제공된 저장소 발췌에는 SKILL.md만 보이지만, 이 스킬은 setup 스크립트 경로와 pua:pua 핵심 스킬 동작을 포함한 더 넓은 tanweai/pua 저장소의 지원을 전제로 합니다. 실사용에 들어가기 전에는 저장소 루트를 확인하고, 언급된 루프 스크립트와 코어 스킬이 실제 설치된 환경에 존재하는지 먼저 검증하세요.

pua-loop는 어떻게 실행되는가

문서에 나온 공식 트리거는 /pua:pua-loop "task description"입니다. 설명에는 loop mode, 自动循环, 一直跑 같은 자연어 트리거도 함께 나오지만, pua-loop usage를 안정적으로 호출하려면 슬래시 명령이 가장 모호함이 적습니다.

실행 후 어떤 일이 벌어지는가

스킬이 시작되면 setup 명령이 실행되어 .claude/pua-loop.local.md 파일을 생성합니다. 이 파일에는 작업 내용과 루프 프로토콜이 저장됩니다. 이후 stop hook이 이 파일을 사용해 매 반복마다 에이전트에게 같은 지시를 다시 공급합니다. 실제 사용 관점에서는, 매번 워크플로를 다시 설명하지 않아도 에이전트가 동일한 작업 패턴을 반복해서 이어갈 수 있다는 뜻입니다.

pua-loop가 잘 작동하려면 처음에 무엇을 줘야 하나

pua-loop를 시작할 때는 아래 네 가지를 한 번에 주는 것이 좋습니다.

1. 원하는 작업 결과
2. 저장소 또는 폴더 범위
3. 검증 명령
4. 반드시 지켜야 할 제약

약한 입력 예:

• “Fix the app.”

강한 입력 예:

• “Use pua-loop to fix the failing login flow in apps/web. Success means pnpm test --filter web passes and the OAuth callback no longer throws a 500. Do not change the database schema. Prefer the smallest safe fix.”

이처럼 더 강한 입력은 어디서 작업해야 하는지, 무엇으로 검증해야 하는지, 무엇은 건드리면 안 되는지를 에이전트가 알 수 있게 해 주므로 불필요한 반복을 줄여줍니다.

거친 목표를 완전한 pua-loop 프롬프트로 바꾸는 법

실전적인 pua-loop guide 패턴은 다음과 같습니다.

• Task: 무엇을 만들거나 고쳐야 하는지
• Scope: 파일, 패키지, 서비스 경계
• Verification: 테스트, lint, build, 스모크 체크
• Constraints: 스키마 변경 금지, 새 의존성 추가 금지, API 안정성 유지
• Priority: 가장 빠른 안전한 수정 우선인지, 더 깊은 리팩터링 우선인지

예시:

• /pua:pua-loop "Resolve TypeScript errors in packages/api only. Run pnpm --filter api build after each meaningful fix. Do not modify public endpoint contracts. Stop only when build passes and no new lint errors are introduced."

먼저 읽어야 할 저장소 파일

우선 다음부터 보세요.

• skills/pua-loop/SKILL.md

그다음 부모 저장소에서 아래 항목을 확인하세요.

• pua:pua 코어 스킬 정의
• scripts/setup-pua-loop.sh 같은 스크립트
• hook 문서 또는 Claude 플러그인 설정 파일

이 순서가 중요한 이유는, pua-loop install을 판단할 때 설명 문구보다 실제 로컬 환경이 setup 스크립트와 stop-hook 기반 루프를 지원하는지가 더 중요하기 때문입니다.

각 반복에서 실제로 하는 일

이 스킬의 핵심 규칙은 단순합니다.

• pua:pua 동작을 로드한다
• 사용자에게 질문하지 않는다
• “cannot solve” 같은 식으로 일찍 멈추지 않는다
• 각 변경 후 검증하고, 문제를 찾고, 수정한 다음 다시 검증한다

그래서 pua-loop는 일반적인 어시스턴트 대화라기보다 자율 복구 사이클에 더 가깝습니다.

일반 프롬프트 대신 pua-loop를 써야 하는 경우

다음과 같은 경우 pua-loop가 적합합니다.

• 성공 여부를 자동으로 확인할 수 있을 때
• 수정과 검증을 여러 번 반복할 가능성이 높을 때
• 중간 개입을 줄이고 싶을 때
• 저장소에 실행 가능한 명령이 있을 때

반대로 아래 상황이라면 피하는 편이 좋습니다.

• 매 단계마다 제품 판단이 필요한 작업
• 에이전트가 테스트나 런타임 검증에 접근할 수 없는 경우
• 잘못된 가정의 비용이 큰 경우

처음 쓰는 사람을 위한 실전 워크플로

처음 실행할 때는 아래처럼 시작하는 것이 안전합니다.

1. 큰 개편이 아니라 범위가 제한된 한 가지 이슈부터 시작합니다.
2. 정확한 검증 명령을 포함합니다.
3. 범위를 하나의 패키지나 기능으로 좁힙니다.
4. 루프를 돌립니다.
5. 최종 변경 사항을 검토한 뒤에만 적용 범위를 넓힙니다.

이 방식은 도입 시 가장 큰 위험, 즉 명세가 부족한 작업에서 지나치게 자신감 있는 자율 수정이 발생하는 문제를 줄여줍니다.

취소 방법과 안전 경계

이 스킬은 두 가지 중단 경로를 문서화하고 있습니다. /cancel-pua-loop를 사용하거나 .claude/pua-loop.local.md를 삭제하는 방식입니다. 자율 반복을 켜기 전에 이것은 반드시 알아야 할 운영 지식으로 봐야 합니다. 현재 환경에서 해당 파일을 쉽게 확인하거나 삭제할 수 없다면, pua-loop skill은 당신의 셋업에 잘 맞지 않을 수 있습니다.

pua-loop 스킬 FAQ

pua-loop는 초보자에게도 좋은가

그렇지만 범위가 잘 정해진 작업에 한해서입니다. 초보자는 자동화의 도움을 크게 받을 수 있지만, 동시에 지시를 모호하게 줄 가능성도 더 높습니다. 처음이라면 열린 구조 설계 요청보다, 실패하는 테스트나 빌드 오류를 대상으로 시작하는 편이 좋습니다.

pua-loop가 일반 프롬프팅을 대체하나

아니요. pua-loop는 실행 루프에 더 적합하지, 함께 탐색하는 작업에 더 적합한 도구는 아닙니다. 아직 접근 방식을 정해야 하거나, 여러 옵션을 비교해야 하거나, 요구사항을 명확히 해야 한다면 먼저 일반 프롬프트를 쓰고, 계획이 정리된 뒤 pua-loop로 전환하세요.

pua-loop install이 잘 안 되는 가장 큰 이유는 무엇인가

대개는 환경 불일치입니다. 이 스킬은 setup 스크립트와 stop-hook 기반 루프를 전제로 합니다. 로컬 Claude/플러그인 설정에 이런 구성 요소가 없다면, markdown 파일만으로는 의도한 자율 동작이 나오지 않습니다.

테스트 없이도 pua-loop를 쓸 수 있나

가능은 하지만 품질은 떨어집니다. 테스트, build 명령, 스모크 체크가 없으면 에이전트는 각 반복이 실제로 개선인지 판단할 신호가 부족합니다. 이 경우 pua-loop usage는 추측 의존도가 높아지고 신뢰성은 낮아집니다.

그냥 “계속 시도해”라고 말하는 것과 뭐가 다른가

일반 프롬프트로도 집요함을 요구할 수는 있습니다. 하지만 pua-loop는 보다 구체적인 운영 패턴을 더합니다. 로컬 파일을 통한 상태 유지, 반복 검증, 명시적인 무질문 모드, 완료 신호가 그것입니다. 실제로 설치할 이유가 되는 것은 바로 이 구조입니다.

언제 pua-loop for Workflow Automation을 쓰면 안 되나

워크플로가 사람의 승인 단계, 외부 자격 증명, 모호한 비즈니스 규칙, 혹은 “완료” 기준이 주관적인 작업에 의존한다면 pua-loop for Workflow Automation은 쓰지 마세요. 자율 루프는 완료 여부를 확인할 수 있을 때만 도움이 됩니다.

pua-loop 스킬 개선 방법

pua-loop에 측정 가능한 종료 조건을 주기

pua-loop 결과를 가장 빠르게 개선하는 방법은 완료 조건을 기계적으로 확인 가능한 형태로 정의하는 것입니다. “잘 되게 만들어”는 약합니다. “모든 auth 테스트 통과, 빌드 성공, /login/callback이 200 반환”은 강합니다. 이 스킬은 반복을 중심으로 설계되어 있기 때문에, 스스로 검증할 수 있는 목표가 필요합니다.

잘못된 자율 판단을 줄이려면 범위를 좁히기

pua-loop는 후속 질문을 하지 않기 때문에 작업 범위가 넓을수록 불필요한 위험이 커집니다. “결제 리팩터링”이라고 하지 말고, “services/payments/retry.ts에서 중복 재시도 처리만 수정하되 webhook payload는 바꾸지 말 것”처럼 쓰세요. 범위를 좁히면 속도와 안전성이 모두 좋아집니다.

파괴적인 수정을 막는 제약을 명시하기

좋은 제약은 부가 설명이 아니라, 루프가 엉뚱한 문제를 풀지 않도록 막아주는 장치입니다. 유용한 예시는 다음과 같습니다.

• 의존성 추가 금지
• 스키마 변경 금지
• API 응답의 하위 호환성 유지
• 전면 재작성보다 최소 수정 선호

이런 제약은 pua-loop 출력 품질을 직접적으로 끌어올립니다.

가능한 한 가장 강한 검증 명령을 사용하기

검증 수단이 여러 개라면 가장 시끄러운 것을 고르지 말고, 가장 관련성 높은 것을 고르세요. UI 버그라면 모노레포 전체 실행보다 해당 문제를 겨냥한 테스트 스위트가 낫습니다. 타입 오류라면 광범위한 lint보다 영향 받는 패키지의 tsc가 더 적합할 수 있습니다. 검증이 좋아질수록 루프의 판단도 좋아집니다.

컨텍스트 부족에서 오는 실패 패턴을 예상하기

흔한 pua-loop 실패 유형은 어느 정도 예측 가능합니다.

• 모호한 작업 설명
• 누락된 저장소 경로 또는 모듈 범위
• 검증 명령 부재
• 드러나지 않은 비기술적 요구사항
• 잘못된 패키지에서의 자율 변경

이들 대부분은 같은 입력으로 다시 돌린다고 해결되지 않고, 초기 프롬프트를 더 정확하게 고치면 해결됩니다.

첫 실행 뒤에는 더 날카로운 지시로 다시 반복하기

첫 번째 pua-loop 실행이 거의 맞았지만 완전히 해결하지 못했다면, 단순히 “다시 해봐”라고 하지 마세요. 부족했던 신호를 추가해야 합니다.

• 무엇이 아직 실패하는지
• 어떤 파일을 잘못 건드렸는지
• 어떤 트레이드오프를 우선해야 하는지
• 어떤 검증 결과를 가장 중요하게 볼지

이렇게 해야 두 번째 실행이 무작정 같은 루프를 반복하는 것이 아니라, 수정 방향이 있는 보정 실행이 됩니다.

신뢰도를 높이려면 코어 의존성부터 읽기

pua-loop는 pua:pua의 동작을 상속하므로, 고급 사용자는 도입 전에 이 코어 스킬을 직접 살펴보는 것이 좋습니다. 그 압박감 있는 스타일이나 판단 규칙이 마음에 들지 않는다면, 이 루프 래퍼 자체가 맞지 않을 수도 있습니다. 설치 여부를 제대로 판단하려면 이 단계가 가장 중요한 저장소 확인 포인트 중 하나입니다.

제한된 자동화부터 시작해서 점진적으로 넓히기

대부분의 팀에게 가장 좋은 pua-loop guide는 점진적 도입입니다. 먼저 검증이 명확한 복구 작업에 적용하고, 그다음 작은 기능 마무리에 써 보고, 더 큰 자동화 흐름은 그 이후로 미루세요. 이런 순서라면 루프 동작이 현재 저장소와 팀의 위험 허용 수준에 맞는지 차분하게 검증할 수 있습니다.