gangjaeyu/harness-loop-fullstack

docs/PRD.md와 docs/TRD.md를 읽고 프로젝트 전체 아키텍처를 docs/ARCHITECTURE/ 아래에 작성한다. overview.md에 시스템 구성·경계·핵심 흐름을 담고, frontend.md·backend.md·database.md·auth.md·security.md 등 영역별 문서로 나눠 기록하며, 무엇보다 PRD·TRD와 충돌하는 설계가 있는지 검토해 봉합하지 않고 드러낸다. 사용자가 "아키텍처 설계해줘", "구조 잡아줘", "설계 문서 써줘", "테이블 설계해줘", "API 설계해줘", "폴더 구조 어떻게 나눌지 정해줘"라고 하거나, TRD 검토를 마치고 다음 단계로 넘어갈 때 반드시 이 스킬을 사용한다. 요구사항과 기술 스택은 정해졌는데 구조가 문서로 없는 상태에서 개발 계획을 세우거나 코드를 짜기 시작하려 할 때도 이 스킬로 먼저 설계를 고정한다.

완료된 프로젝트(plan_setup·harness_setup·loop_setup/LOOP.md 가 있고 STATE.md 의 Phase Overview 에 in_progress 가 없는 상태)에서 실제 사용 중에 발견된 문제 하나를 고친다. "xx 가 안 돼" 로 시작하는 신고를 받아 버그인지 요구 변경인지 먼저 가르고(문서·OQ 근거), 재현 절차와 기대 동작을 LOG.md 에 "### BUG-NN" 한 줄로 먼저 적고, 원인을 확인하고, 그 버그를 잡는 회귀 검사를 harness-update 로 게이트에 즉시 활성으로 넣고(고치기 전 실패를 실제로 확인), 코드를 고치고, 게이트 넷을 통과시키고(task_validation 은 분리 세션이 그 재현 줄을 수용 기준으로 판정), 커밋 1회(메시지에 BUG-NN) 한다. 문서·플랜·phase·STATE.md 는 건드리지 않는다. 사용자가 "필터가 안 돼", "저장했는데 사라져", "이 버튼 누르면 에러 나", "쓰다 보니 이상한 게 있어", "배포한 앱에서 xx 가 이상하게 나와", "사용자한테 버그 신고 들어왔어", "이 버그 고쳐줘" 처럼 다 만든 앱을 쓰다가 발견한 문제를 고쳐 달라고 할 때 반드시 이 스킬을 사용한다. 코드를 바로 고치지 말고 이 스킬로 먼저 기록과 회귀 검사를 세운다. 다만 개발 루프 안에서 게이트가 실패한 것은 이 스킬을 부를 이유가 아니다 — 그건 LOOP.md 의 실패 분류와 재시도 3회가 다룬다. 이 스킬은 루프 밖에서(Phase Overview 에 in_progress 없음), 실제 사용 중에 발견된 문제를 받는다. 문서에 적힌 대로 동작하는데 바꾸고 싶은 것은 feature-add, docs/PRD.md 가 없는 코드는 code-to-docs 가 먼저다.

문서 없이 만들어진 코드베이스(바이브 코딩 프로젝트, 인수받은 레거시, README 한 줄뿐인 앱)를 읽고 "이렇게 만들자"가 아니라 "지금 이렇게 되어 있다"를 적은 as-is 문서 셋 — docs/PRD.md·docs/TRD.md·docs/ARCHITECTURE/ — 를 만든 뒤, plan-generator(phase-01 현행 고정 — as-is 동작을 붙잡는 테스트 태스크만) → harness-setup → loop-setup 을 원래 순서대로 불러 그 프로젝트를 하네스-루프 풀스택 플러그인으로 만든 프로젝트와 같은 상태로 올린다. 사용자가 "이 코드 문서화해줘", "문서 없는 프로젝트인데 이 플러그인에 올리고 싶어", "바이브 코딩으로 만든 건데 정리해줘", "기존 코드 읽고 PRD/TRD 뽑아줘", "레거시 코드에 테스트부터 붙이자", "이 저장소 현재 상태를 문서로 남겨줘"라고 하거나, docs/PRD.md 가 없는 코드베이스에서 리팩토링·기능 추가·버그 수정·하네스 세팅을 시작하려 할 때 반드시 이 스킬을 먼저 사용한다. 코드는 있는데 PRD·TRD·아키텍처·플랜·하네스·LOOP.md 가 하나도 없는 상태에서 refactor-plan·feature-add·bug-fix·harness-setup 을 부르려 하면 그 대신 이 스킬이 먼저다. 이미 docs/PRD.md 가 있는 프로젝트에는 쓰지 않는다 — 그건 feature-add·refactor-plan 의 몫이다.

docs/PRD.md·docs/TRD.md·docs/ARCHITECTURE/·plan_setup/(PLAN.md·phase·task) 을 읽고 프로젝트의 검증 하네스를 harness_setup/ 아래에 세운다. quality_gates/ 에 lint·unit·e2e·task_validation 네 게이트의 정의서(무엇을 검사하고 어떤 명령으로 돌며 무엇이 통과인가, 언제부터 활성인가)를 만들고, scripts/ 에 사용자 OS에 맞는 local-dev 스크립트(DB·API·앱 서버·Redis 같은 의존 서비스를 한 명령으로 준비)를 만들며, task_validation 이 구현 세션과 분리된 독립 세션에서 돌도록 절차를 고정한다. 사용자가 "하네스 세팅해줘", "품질 게이트 만들어줘", "테스트 파이프라인 구성해줘", "검증 환경 세팅해줘", "로컬 개발 환경 세팅해줘", "lint/테스트 어떻게 돌릴지 정해줘", "E2E 붙여줘"라고 하거나, 마스터 플랜 검토를 마치고 다음 단계로 넘어갈 때 반드시 이 스킬을 사용한다. 태스크 문서의 verification 이 [lint, unit, e2e, task_validation] 인데 그 게이트를 실제로 무엇으로 돌지가 문서로 없는 상태에서 구현을 시작하거나 개발 루프(loop-setup)를 세우려 할 때도 이 스킬로 먼저 하네스를 고정한다.

이미 있는 harness_setup/ 을 프로젝트 진행에 맞춰 갱신한다. 활성 시점에 도달한 게이트를 미활성에서 활성으로 올리고, 대기 중이던 E2E 흐름과 필수 커버 영역을 활성화하며, 차단(OQ·CF)이 풀린 태스크를 검증 대상에 넣고, 새로 생긴 의존 서비스(Redis·API 서버 등)를 구성 요소 표와 local-dev 스크립트에 더하고, 게이트 명령이 실제와 어긋난 곳을 맞춘다. 사용자가 "하네스 업데이트해줘", "게이트 갱신해줘", "이 흐름도 E2E에 넣어줘", "Redis 추가됐으니 local-dev 고쳐줘", "테스트가 계속 깨지는데 하네스 좀 봐줘", "차단 풀렸으니 검증 대상에 넣어줘"라고 하거나, 개발 루프가 태스크·phase 를 완료한 뒤 하네스가 실제와 맞지 않는다고 판단했을 때 반드시 이 스킬을 사용한다. 게이트가 실패하는데 그 원인이 코드가 아니라 하네스 쪽(낡은 흐름 정의, 준비되지 않는 개발 환경)일 때도 이 스킬로 고친다. harness_setup/ 이 아직 없으면 이 스킬이 아니라 harness-setup 을 쓴다.

아직 모호한 제품/서비스 아이디어를 역질문과 선택지 제안으로 구체화해서, 다음 단계(PRD 작성)에 바로 쓸 수 있는 docs/IDEA.md 초안을 만든다. 사용자가 "앱 하나 만들고 싶은데", "이런 서비스 어때?", "아이디어 좀 같이 정리하자", "뭘 만들지 고민 중", "브레인스토밍" 같은 말을 하거나, 무엇을 만들지가 확정되지 않은 상태에서 기획/PRD/개발을 요청할 때 반드시 이 스킬을 먼저 사용한다. 요구사항이 흐릿한데 곧바로 코드나 문서를 쓰려는 상황이면 이 스킬로 먼저 범위를 좁힌다.

plan_setup/(PLAN.md·phase·task·STATE.md·LOG.md) 과 harness_setup/(HARNESS.md·quality_gates/) 을 읽고 이 프로젝트의 개발 루프를 loop_setup/LOOP.md 한 문서로 고정한다. 다음 태스크를 어떻게 고르고, 태스크의 verification 값으로 어느 게이트를 어떤 순서로 돌리며, 실패를 진짜 결함·낡은 스펙·환경 문제로 어떻게 분류하고, 재수정 사이클을 최대 3회로 세다가 언제 멈춰 사용자에게 보고하며, task_validation 을 구현 세션과 어떻게 분리하고, STATE.md·LOG.md 를 언제 갱신하고 언제 커밋하며, 차단이 풀린 태스크를 어떻게 여는지, 태스크마다 새 세션을 누가 어떻게 여는지(스크립트 구동·오르카·서브에이전트), 병렬 운용(기본)을 위해 태스크 단위 DAG 를 머메이드로 그리고 자원 충돌을 사전 검사하며 코디네이터·슬롯 워크트리를 어떻게 운용하는지, 오르카 구동이 진행할 수 있는데 멈춘 상태(잠든 워커·죽은 스크립트·사람 프롬프트)를 어떻게 감시하는지를 정한다. 사용자가 "개발 루프 세팅해줘", "이제 구현 시작하자", "루프 만들어줘", "LOOP.md 만들어줘", "태스크 어떤 순서로 진행할지 정해줘", "실패하면 몇 번까지 재시도할지 정해줘"라고 하거나, 하네스 검토를 마치고 다음 단계로 넘어갈 때 반드시 이 스킬을 사용한다. 멀티 에이전트·병렬 운용을 실제로 켜는 요청은 LOOP.md 가 이미 있으면 loop-update 의 몫이다. 플랜과 하네스는 있는데 "그래서 지금 무엇부터 하면 되는가"가 문서로 없는 상태에서 첫 태스크 구현을 시작하려 할 때도 이 스킬로 먼저 루프를 고정한다. loop_setup/LOOP.md 가 이미 있으면 이 스킬이 아니라 loop-update 를 쓴다.

이미 있는 loop_setup/LOOP.md 를 프로젝트 진행에 맞춰 갱신한다. 세팅 때 껐던 병렬을 켤 때 슬롯 간 DB·포트 격리 미결을 닫고 STATE.md 의 절 형식을 넓혀 에이전트끼리 기록을 덮어쓰지 않게 하고, 동시 에이전트 수·슬롯·격리 방식·구동기 모드가 바뀐 것을 반영하고, local-dev 옵션이나 task_validation 분리 수단이 바뀐 것을 규칙에 반영하고, 태스크가 추가되어 달라진 DAG.md 를 스크립트로 다시 만들고 자원 충돌 표·병렬 폭을 다시 재고, 루프가 같은 자리에서 반복해 멈출 때 규칙이 현실과 어긋난 곳을 고치며, 1.10.0 이전 loop-setup 이 만든 LOOP.md(상주 코디네이터·알림이 쌓이기만 하는 구조)를 구동 스크립트·반복 판정·알림 만료 구조로 옮기고, 옛 구동 스크립트에 정지 감시(분리 실행·잠들거나 죽은 워커·자식 실패·질문 재알림과 답하기 탭)를 넣는다. 사용자가 "루프 업데이트해줘", "LOOP.md 고쳐줘", "이제 에이전트 여러 개로 병렬로 돌리자", "워크트리 격리 방식 정하자", "태스크 추가됐으니 루프 다시 봐줘", "루프가 자꾸 같은 데서 멈춰", "코디네이터가 토큰을 너무 많이 써", "알림이 계속 쌓이기만 해", "루프가 살아 있는지 안 보여", "코디네이터가 어디 있는지 모르겠어", "질문 하나 때문에 다 놀고 있어", "질문 알림을 놓쳤어", "워커가 죽은 걸 몰랐어", "같은 테스트가 계속 흔들려", "루프가 멈춘 걸 한참 뒤에 알았어", "워커가 답을 받고도 잠들어 있어", "선행이 끝났는데 배정이 안 되고 슬롯이 놀아"라고 하거나, 개발 루프를 돌다 LOOP.md 의 규칙이 실제와 맞지 않는다고 판단했을 때 반드시 이 스킬을 사용한다. 다만 게이트가 실패한 것은 이 스킬을 부를 이유가 아니다 — 그건 루프를 도는 일이고, 코드·하네스·태스크 문서 중 어디로 갈지는 LOOP.md 의 실패 분류가 이미 정해 두었다. loop_setup/LOOP.md 가 아직 없으면 이 스킬이 아니라 loop-setup 을 쓴다.

docs/PRD.md·docs/TRD.md·docs/ARCHITECTURE/ 를 읽고 프로젝트 전체 마스터 플랜을 plan_setup/ 아래에 만든다. PLAN.md(전체 지도), phase-NN/phase-NN-<이름>.md(검증 가능한 단계), phase-NN-tasks/phase-NN-task-MM.md(YAML frontmatter를 가진 실제 작업 단위), STATE.md(지금 어디인가), LOG.md(무슨 일이 있었는가)를 생성하고, PRD 추적표의 '담당 태스크' 열을 채우며, 차단 미결·미해소 충돌에 걸린 태스크를 blocked 로 표시한다. 사용자가 "개발 계획 세워줘", "태스크 나눠줘", "플랜 짜줘", "phase 구성해줘", "뭐부터 만들지 정해줘", "작업 목록 만들어줘", "마스터 플랜 만들어줘"라고 하거나, 아키텍처 검토를 마치고 다음 단계로 넘어갈 때 반드시 이 스킬을 사용한다. 설계 문서는 있는데 무엇부터 구현할지가 문서로 없는 상태에서 코드를 짜기 시작하거나 하네스·개발 루프를 세우려 할 때도 이 스킬로 먼저 플랜을 고정한다. plan_setup/ 이 이미 있고 루프가 "수용 기준을 다시 써야 한다", "태스크를 추가해야 한다", "판정 불가"로 돌려보냈을 때도 이 스킬(10단계 부분 갱신)이다.

아이디어나 docs/IDEA.md를 받아 "무엇을 만들 것인가"를 정의하는 PRD(docs/PRD.md)를 작성한다. 요구사항마다 고유 ID와 검증 가능한 수용 기준을 붙여, 이후 아키텍처·플랜·태스크·품질 게이트가 그대로 참조할 수 있게 만든다. 사용자가 "PRD 써줘", "요구사항 정리해줘", "기획서 만들어줘", "제품 스펙 문서", "유저 스토리 정리"라고 하거나, 아이디어 브레인스토밍을 마치고 다음 단계로 넘어갈 때 반드시 이 스킬을 사용한다. 무엇을 만들지는 정해졌는데 기능 목록과 수용 기준이 문서로 없는 상태에서 개발이나 설계를 시작하려 할 때도 이 스킬로 먼저 요구사항을 고정한다.

docs/PRD.md를 받아 "어떤 기술로 만들 것인가"를 정의하는 TRD(docs/TRD.md)를 작성한다. 스택·데이터·API·인증·보안·테스트·배포를 결정 단위로 확정하고, 각 결정에 근거가 된 요구사항과 검증 방법·되돌리기 비용을 붙여 아키텍처와 하네스가 그대로 참조할 수 있게 만든다. 사용자가 "TRD 써줘", "기술 스택 정해줘", "어떤 기술로 만들지 정리해줘", "기술 명세서", "DB 뭐 쓸지 정해줘", "배포는 어떻게 할지 정리해줘"라고 하거나, PRD 작성을 마치고 다음 단계로 넘어갈 때 반드시 이 스킬을 사용한다. 요구사항은 정해졌는데 기술 선택이 문서로 없는 상태에서 아키텍처 설계나 개발을 시작하려 할 때도 이 스킬로 먼저 기술 결정을 고정한다.