에이전트 공통 작업 규칙 (Claude·Codex 공용)
착수 전 필독·최종 목표 보존 — 2026-09-14 사용자 결정
모든 Barbelic 작업 세션은 새 작업·인수인계·재개·컨텍스트 복구 때 앱 저장소 최상위 AGENTS.md의 작업 지침을 반드시 읽고 시작한다. 이 저장소의 최상위 AGENTS.md와 설계·작업 원칙도 따른다. 실행 중 변경을 전달받으면 다음 실질 작업 전에 다시 읽는다. SOLID 전체와 데이터 증가에 따른 실행 한계·정확성 기준을 요청 범위에 적용한다.
사용자의 최종 결과와 전체 적용 범위를 기존 작업 기록에 유지한다. Phase·시범 사례·일부 검사로 범위를 줄이지 않는다. 완료 직전에 요청과 실제 산출물·전체 적용 대상·검증·반영 상태를 완료 대조 기준로 확인한다. 승인된 잔여 작업은 계속 수행하고, 실제 장애가 있으면 남은 범위와 이유를 밝힌다. 일부 적용이나 정책 기록을 전체 적용 완료로 바꾸지 않는다. 이 결정이 아래의 과거 완료 형식보다 우선하며 원격 CI 등 기존 승인 경계는 유지한다.
Full CI 반복 디버깅 금지 — 2026-09-11 사용자 결정
Codex·Claude를 포함한 모든 작업자는 실패 전체 수집 → CI와 맞춘 로컬 환경에서 해당 테스트·검사 묶음 수리 → 알려진 실패별 검증 근거 정리 → 필요한 원격 재실행을 따른다. 실패 하나를 고칠 때마다 Full CI를 반복하지 않는다. 열린 승격 PR의 head 갱신으로 유발되는 자동 Full도 같은 기준을 적용한다. 같은 후보의 유효한 성공 증거는 유지하고 실패 범위를 우선 재시도하되, 새 후보에 옛 검증을 잘못 적용하거나 필수 검사를 생략하지 않는다. 같은 유형이 반복되면 재현·환경 차이를 진단하며, 테스트를 임의로 완화해 통과시키지 않는다. 기존 go 범위의 작업에 재승인을 추가하지 않는다.
실패 수리 절차·재실행 전 최소 기록이 정본이다. 이번 변경은 지침·절차이며 자동 실행 차단 기능이 아니다. 이전의 포괄적인 “수정 후 재요청”은 이 절차를 충족한 뒤 재요청한다는 뜻으로 해석한다.
#1463 저장소 분리 이후 적용: 아래 앱 release·DB·데이터 보호 규칙은 앱 저장소에 적용한다. 과거 docs/admin 결합 빌드·같은 SHA 배포·앱 main 문서 직행·문서 문자열 검사 설명은 이관 전 기록이다. 모든 문서와 작업 기록은 dekerd/Barbelic-docs에서 관리하며, 현행 저장소 경계와 문서·관리자 독립 운영이 그 부분을 대체한다. 세션 제목은 현재 Phase/전체 Phase 규칙을 따른다. 코드 준비·원격 활성화·실제 배포 성공은 독립 운영 문서의 기록으로 구분한다.
2026-09-09 기준. 오너가 Claude 세션에 내린 지시 중 어느 에이전트가 작업해도 똑같이 적용되는 것만 골라 정리했다. Claude 앱 전용 기능(세션 제목, 세션 간 메시지, 메모리 파일)은 뺐다. 절차의 정본은 릴리스 프로세스·릴리스 랜딩 큐·PR 전 로컬 검증·배포 파이프라인·마이그레이션 랜딩이며, 이 문서와 어긋나면 정본이 이긴다. Codex 의 저장소 지침(
AGENTS.md)과 겹치는 항목은 여기가 요약이고 그쪽이 상세다.
구현 완료 후 release 병합까지 (2026-09-10 · 2026-09-15 개정)
2026-09-15 개정(오너 지시, #1661·#1659) — PR 전
ci:precheck-local은 폐기됐다(QA1 퇴역으로 실행도 불가). 구현 완료 → PR →merge:request(Merge Check) → release 병합 확인이 완료 범위다. 아래의 "precheck" 서술은 그 개정 전 기록이다.
2026-09-11 #1536 오너 재확인: “원래 precheck 끝나면 릴리스 병합”이라는 직접 지시에 따라 이 작업의 자기 앱 PR Merge Check·실제 release 병합과 연결 문서 PR 검사·병합을 추가 질문 없이 완료한다. 일반적인 로컬 검증 지침을 이유로 이미 명시된 동일 범위의 병합을 다시 중단하지 않는다. 다른 작업의 원격 실행·Full CI·승격·Production 승인으로 확대하지 않는다.
계기: #1419에서 구현·선택 검증·Draft PR까지만 마치고 승인된 검사 제외 정책의 release 미반영을 오너에게 넘긴 뒤, 오너가 “끝났으면 precheck에 병합까지 해. 이거 전체 지침에 올려줘”라고 정정했다.
- 구현을 맡은 작업자는 모든 Phase가 끝나면 자기 PR 준비/갱신 →
merge:request→ Merge Check 결과와 실제 release 병합 확인까지 같은 작업의 완료 범위로 처리한다(최신 release 합치기는 큐가 한다; 충돌이면 세션이 합쳐 새 head로 재요청). 이미 받은 구현 go에서 이 절차의 승인을 다시 묻지 않는다. 코드 완료·선택 검사·Draft PR 작성을 최종 완료로 보고하고 멈추지 않는다. - 이미 승인된 실행 정책이 목적 release에 아직 없거나 검증 경로의 호환 차이가 있으면, 현재 요청을 직접 막는 부분만 자기 작업 브랜치에서 반영·충돌 해결·검증한다. 구현 가능한 작업을 담당자 배정이나 오너의 재요청으로 넘기지 않는다. 다른 담당자의 PR·브랜치·큐를 대신 조작하거나 인접 기능·별도 감사·정책 개편으로 확대하지 않는다.
- Merge Check 실패는 원인을 확인하고 자기 변경 범위에서 수정하여 다시 요청한다. 큐 밖 병합·검증 우회·보호 규칙 완화는 허용하지 않는다. 선택 검증을 승격 레인 통과로 대체하지 않는다.
- 외부 권한·계정 설정·사용자 데이터·Production·비용·제품 정책 변경처럼 기존 승인으로 처리할 수 없는 실제 장애만 미완료로 보고하고 필요한 오너 조치를 구체화한다. 해결 가능한 로컬 작업은 먼저 끝낸다.
- 작업 PR의 release 병합과 staging/main 승격·Production 배포는 구분한다. 이 지시는 목적 release 병합까지이며 별도 승인 범위가 없는 승격·배포를 추가하지 않는다. 이슈 종결은 기존 실제 Production 반영 기준을 따른다.
1. 코드를 만지기 전에
- 가정은 밝히고 진행한다. 해석이 갈리면 선택지를 제시한다. 더 단순한 방법이 있으면 말한다. 모르는 것은 모른다고 쓴다.
- 요청한 것만 만든다. 추상화·설정 가능성·있을 수 없는 경우의 예외 처리를 미리 넣지 않는다. 200줄이 50줄이 될 수 있으면 다시 쓴다.
- 바꿔야 할 줄만 바꾼다. 인접 코드 정리·형식 변경·리팩터링은 하지 않는다. 내 변경이 만든 미사용 import·함수만 치운다. 무관한 죽은 코드는 언급만 한다.
- 성공 기준을 먼저 정한다. "버그 수정" = 재현 테스트를 쓰고 통과시키기. 여러 단계면 단계마다 확인 방법을 적는다.
- 요청한 최종 결과 전체가 갖춰져야 완료다. 완료 전 대조를 통과한 경우에만 ‘완료’와 결과를 간결하게 쓴다. 필요한 미적용·미검증·미반영이 남으면 ‘진행 중/미완료’와 잔여·이유를 쓰며, 마지막에 ‘완료’라고 끝내지 않는다. 요청하지 않은 다음 작업이나 추천을 덧붙이지 않는다.
- 문제 해결은 땜질이 아니라 구조 개선으로. 증상 자리만 막는 조건문·특례·타이머 유예·재시도는 원인 수리가 아니다. 계획의 해결 방안 표에는 구조 개선안을 채택안으로, 땜질안은 대안으로 적고 채택하지 않는 이유를 쓴다. 땜질이 불가피하면(장애 대응·릴리스 직전) 땜질임을 말하고 근본 수리 이슈를 같은 턴에 만든다. 자기 검사: "이 수리 뒤 비슷한 문제가 또 나면 같은 자리를 또 고쳐야 하는가."
2. 이슈 작업 절차
- 분석 → 계획 → go. 코드 전에 원인 분석(코드 읽기 + Production 실측: 원격 측정·데이터 프로브)과 Phase 계획을 이슈 댓글과 채팅 양쪽에 올린다. 오너의 명시적 go 뒤에 코드를 시작한다. 이슈 댓글에는 작업 주체를 식별할 정보(에이전트·세션 식별자·작업 위치)를 남긴다.
- Phase 이름은
Phase N, 1부터. 하위 단계는Phase N-M. 글자 접두어(C0/P0/W1)는 쓰지 않는다. 진행률은Phase N/M 완료, M = 마지막 Phase 번호(5개면5/5로 끝난다). - 계획 문서에는 "예상 효과·개선사항" 절. Phase 계획 바로 뒤에 표(개선되는 것 / 체감 대상 / 확인 지표 전→후 / Phase). 부작용·리스크를 같은 절에. 통계를 지어내지 않는다 — 모르면 "확인 지표"만 적는다.
- Phase 보고는 경계마다 즉시. 시작 한 줄(
▶ Phase N 시작 — 무엇을), 완료 블록(아래 형식), 30분 넘으면 중간 한 줄. 보고 없이 다음 Phase 코드를 시작하지 않는다.## 진행 보고 — #1237 Phase 2/5 완료 (14:32) Phase 1 ✅ · Phase 2 ✅ · Phase 3 🔄 · Phase 4 ⬜ · Phase 5 ⬜ · Full CI ⬜ · Merged ⬜ - 이번 Phase에서 한 것: (2~3줄, 쉬운 말) - 검증: npm run check 통과 / pgTAP N개 작성 / 커밋 abc1234 - 작업 중 드러난 것: (없으면 "없음") - 다음: Phase 3 — 무엇을, 예상 소요 - 오너 결정 필요: (없으면 "없음") - 이어받을 때는 "작업 이어받았습니다" 댓글부터. 이어받은 첫 행동으로 이슈에 댓글(작업 주체·이전 작업자·브랜치·작업 위치·시작 지점). 나중에 몰아서 쓰지 않는다.
- 이슈 제목은 오너 문구 그대로, 앞 핵심 한 절만.
핵심 — 부제를 붙이지 않고 세션 제목 규칙을 따른다. 2026-09-10 #1416 사용자 정정(2026-09-15 개정): 구현 후 상태는[Merge Check]→[vX.Y.Z 반영완료]다([Precheck]단계는 2026-09-15 폐기). 각 단계 진입 즉시 제목을 바꾸고 실제 목적 release 병합 확인 후 반영완료로 표시한다. 완료 응답 전 제목 변경 도구 성공까지 확인한다. 이 세션 상태는 release 반영이며 운영 배포 성공과 구분한다. 이슈 제목은 Production 성공 전까지 유지하고, 성공 확인 후[vX.Y.Z 반영완료]를 붙여 닫는다. 취소는[취소됨]으로 닫는다. 2026-09-10 HQ 인계 요청: 선행 완료·검증·목적 release 반영 대기는 세션 상태[선행대기]로 통일한다.#번호·[리팩터링 N-M]을 유지하고 조건 충족 시 실제 조사/구현 상태로 전환한다. 자기[Merge Check]대기와 GitHub 이슈 제목은 바꾸지 않는다. 상세 적용 조건을 따른다. - 실기기 확인을 오너에게 묻지 않는다. 검증 = 자동 증거(단위·pgTAP·e2e·마이그레이션 postcheck·Production 프로브). 사람 눈으로만 판단할 것(시각·감각 품질)은 정보로 적되 요청·게이트로 만들지 않는다.
3. 오너에게 묻기
- 묻는 것은 셋뿐. ① 오너 손이 아니면 할 수 없는 일(GitHub·Vercel·Supabase·앱스토어 설정, 결제, 계정 권한) ② 되돌릴 수 없거나 유저 데이터·Production·비용에 영향을 주는 일 ③ 오너가 정한 제품 정책을 바꾸는 일. 나머지는 권장안을 골라 "전제:" 한 줄로 적고 진행한다. 계획당 결정 항목 0~1개. ①은 질문이 아니라 산출물 끝의 "오너 손이 필요한 것" 목록.
- 물을 때는 배경 → 선택지별 결과(보이는 것·작업량·위험·되돌리기) → 권장안 순서로, 오너가 코드·이전 대화를 다시 열지 않고 답할 수 있게.
- 이미 문서·이슈·이전 결정에 답이 있으면 묻지 않는다. "확인 부탁"류 금지.
4. 오너에게 쓰는 말
- 자기가 만든 용어·영어 직역 금지("발사", "취소 표면", "실체화", "왕복 소실"). 정규 업무 용어를 쓰고 첫 등장에 짧게 풀이한다(예: "타이머(예약된 자동 실행)").
- 코드는 내부 이름이 아니라 동작으로 설명한다("취소하는 방법이 flush() 하나뿐").
- 유저에게 보이는 동작은 유저 A·B 예시를 먼저, 메커니즘은 나중에.
- 보내기 전 자기 검사: 코드를 안 읽은 오너가 증상 → 원인 → 조치를 이 글만으로 이해하는가.
5. 검증·CI·릴리스 (2026-09-10 개정판 · 2026-09-15 개정)
2026-09-15 개정(오너 지시, #1661·#1659) — 승격 검사 3단계, QA1 완전 퇴역. ① 작업→release = 큐 Merge Check만(PR 전 precheck 없음) ② release→staging = GitHub Full CI precheck 레인(
static-checks+migration-smoke) ③ staging→main = QA2 레인(qa2-product-contracts)만. QA1(단위·pgTAP·브라우저·화면 정합성·배포 뒤 smoke·수동 smoke·소셜 로그인 가정 로그인)은 어느 워크플로도 실행하지 않고npm run check는 정적 검사만이다. 아래 2026-09-10 배너·표의 "precheck·full·재사용" 서술은 그 개정 전 기록이다. 정본 = 릴리스 프로세스.
2026-09-10 승인 정책 (#1491, v0.17.8 대상): 작업 세션은
ci:precheck-local, 작업→release 큐는 Merge Check만 수행한다. 최종 release→staging 후보에서 full CI를 실행하고, staging→main은 동일 tree의 유효한 full 성공 기록과 현재 staging 배포·smoke 증거를 확인해 재사용한다. 명시적merge:request --dry-run은 진단용 full 실행을 유지한다. 앱 main6afe58ec에 설치됐으며 정상 큐의 실제 실행 시간과 운영 배포 성공은 아직 확인 전이다. 상세 상태는 적용 기록에서 구분한다. 아래 과거 전환 기록보다 이 절차가 우선한다.
개별 CASE의 품질 승인: 테스트케이스 품질관리 기준 15개는 필수 조건이다(2026-09-09 사용자 결정). 실행 통과와 기준 적합성을 구분하고, 위반·증거 누락을 재시도 성공이나 다른 항목 점수로 상쇄하지 않는다. 실행 강제는 앱 코드·동작 검사·기존 증거 집계에서 구현하며 문서 문자열 검사로 대체하지 않는다. 실제 적용 상태는 해당 기준 문서의 기록을 따른다.
브랜치와 큐
- 릴리스 경로는 작업 브랜치 →
release/vX.Y.Z→staging→main(Production). 작업 브랜치는 목적 release 에서 분기하고 PR base 도 그 release. main 에서 분기하지 않는다(순수 문서 예외만). - 릴리스 배정:
release/v0.18.0은 리팩터링 캠페인 트랙([리팩터링 N-M]) 전용. 그 외 모든 작업(수리·테스트·인프라·기능)은 다음0.17.n패치 릴리스. 최신release/v0.17.x가 없으면 main 에서 만든다(release/* 생성은 보호 규칙 밖). - 앱 작업 PR은 큐로만 들어간다. 사전검증 후
npm run merge:request -- --pr <N>을 사용한다. 실행 중 취소·PR push는 하지 않는다. 큐 runner는 최신 release와 합친 후보의 충돌·migration 순서/위험·PR head/base·후보 tree를 검사하고, 예상 base일 때만 그 커밋을 반영한다. 일반 병합 요청은 full CI를 실행하거나 full 성공 기록을 만들지 않는다. Merge Check 실패는 수정 후 새 head로 다시 요청한다. - 큐 밖 병합 금지, 보호 규칙 완화 금지. 일반
release/*통합은 큐 runner의 전용 키로 갱신한다. 오너가 2026-09-10 추가한 관리자 bypass 권한과 이번 #1491 예외는 적용 기록으로 구분하며 후속 일반 작업은 큐를 사용한다. "규칙을 잠깐 풀고 손으로 머지한 뒤 다시 켜자"는 하지 않는다 — 검증한 커밋 = 머지된 커밋이 깨진다. 09-09 실측: 큐 밖으로 들어온 #1455·#1459·#1461 이 release 브랜치에 깨진 단위 테스트와 스냅샷 불일치를 남겨 뒤따르는 모든 PR 의 큐 CI 가 막혔다. #1491 이후에도 순차 병합·조건부 push는 유지하며, 개별 사전검증 후 조합에서 생긴 기능 문제는 최종 release→staging full에서 확인한다. - 다른 에이전트가 맡은 PR·브랜치·큐 요청은 손대지 않는다. 요청·취소·댓글·base 변경·push 전부. 그 PR 때문에 내 작업이 막혀도 오너에게 "담당자가 할 절차"를 말로 전달하는 데서 멈춘다. 남의 브랜치에 고칠 것이 있으면 댓글로 제안한다.
- 선행 PR 을 기다릴 때 확인 주기는 5분. 큐 대기 자체는 GitHub·runner 가 이벤트로 처리하므로 주기 확인이 필요 없다 — 결과는
npm run ci:wait -- --pr <N>또는gh run watch.
검증 명령
| 명령 | 누가·언제 | 하는 일 |
|---|---|---|
npm run check | Phase 완료마다 | 정적 검사(타입·린트·계약·렌더 규칙·배포 파이프라인). 단위 테스트는 QA1 퇴역(2026-09-15)으로 없다. 커밋으로 누적 |
(폐기) ci:precheck-local·ci:full-local | — | 2026-09-15 QA1 퇴역으로 실행 불가·명령 삭제. PR 전 precheck 없음, 전체 검증은 승격 PR의 레인이 한다 |
| 마이그레이션 변경 시 | Phase 완료마다 | 로컬 스택에서 supabase db reset --local --no-seed → npm run schema:snapshot -- --check(승격 ① migration-smoke 잡과 같은 검사) |
| QA2 부분 실행 | 제품 동작 확인이 필요할 때 | Barbelic-QA2 체크아웃에서 npm run qa:ci -- --app <앱 checkout> --revision <sha> --mode focused --risk <이름> |
npm run ci:wait -- --pr <N> | 결과 확인 | base 가 release/* 면 큐 실행을, staging/main 이면 GitHub Full CI 를 추적. 무한대기 방지(상한·gh 실패·취소 판정) |
- PR·CI·머지는 트랙의 모든 Phase 완료 후 1회. Phase 마다 PR 을 열지 않는다. 예외: 오너가 특정 Phase 선행 배포를 지시, 순수 문서 PR.
- hosted CI(
GitHub Full CI)는 두 승격 PR에서 시작한다(2026-09-15 개정).release → staging은 precheck 레인(static-checks+migration-smoke),staging → main은 QA2 레인(qa2-product-contracts)만 돈다. 같은 tree 성공 기록 재사용은 폐기. 일반 작업 PR과 staging/main push에는 hosted CI를 돌리지 않는다. 문서·관리자·랜딩은 각 저장소의 독립 검사·배포를 따른다. - CI 가 빨간불이면 "로컬로 재현 가능했는가"로 분류해 작업 기록에 남긴다(재현 가능했는데 놓쳤으면
사전 검증 누락). - 마이그레이션: 번호는 목적 release 장부 꼬리 뒤(개발 중 번호는 임시, 예측·선점 금지). 위험 헤더(
npm run migrations:risk -- --write), level=high 는 populated upgrade 증거. DB 적용은 승격 후 각 환경 Deploy 가 한다 — staging/Production DB 에 직접 push 금지. 파일 잠금(landing:lock)·db:preflight는 폐기. - 유저 기록 원본은 불변. 마이그레이션·트리거·함수·관리자 코드가 원본 등급 컬럼을 UPDATE/DELETE 하지 않는다. 수리가 정말 필요하면 이슈 +
npm run db:loss-audit+ 오너 승인 + 수리 티켓(set_config('lift_guild.repair_ticket', 'issue#NNNN', true)). 새 컬럼은 같은 PR 에서 등급 목록(supabase/contracts/user-fact-columns.json)에 등재. "이 값은 자리표시자다"는 판단을 사람이 하지 않는다.
워크플로 이름 (Actions 목록)
| 이름 | 역할 | 자동 실행 |
|---|---|---|
1-Production Deploy | main 머지 → Production 배포(DB → Edge → 프론트·docs → smoke → 브라우저 여정 → 태그) | main push |
2-Staging Deploy | staging 머지 → staging 배포 | staging push |
3-Release Merge Request | 작업 PR 을 release 에 넣는 큐. 제목 [#이슈 → 대상] 이슈 제목 · PR #N | merge:request |
GitHub Full CI | release→staging = precheck 레인(static-checks + migration-smoke), staging→main = QA2 레인. 실행 이름 [vX.Y.Z] Release -> Stage Merge / Stage -> Main Merge | 승격 PR 열기·push |
(삭제) Production smoke (manual)·Social login daily check | QA1 e2e 기반이라 2026-09-15 QA1 퇴역과 함께 삭제(#1663). 소셜 제공자 설정 점검(앱 스크립트) 복원 여부는 오너 결정 | — |
Daily data backup | 유저 원본 매일 백업 | 매일 |
위 새 이름은 #1460을 포함한 앱 main df394f77a에서 확인했다. Landing queue·Repository checks·Deploy는 이전 실행 기록의 이름이다. 이 목록은 앱 파이프라인이며 문서·관리자·랜딩 저장소의 독립 CI/배포를 대신하지 않는다. #1463 큐 호환의 활성화 여부는 개명 완료와 구분한다.
릴리스 PR
- 제목
[Release vX.Y.Z] 한 줄 요약, 버전은 점 없는v0.10.0(v.0.10.0은 태그가 조용히 건너뛰어진다). 수정만 = patch, 기능·화면 = minor. 머지는 merge commit 만. 포함 내용은 제품(앱·DB·엣지) 변경만 — 문서·관리자 패널 변경은 뺀다.
6. 기록
- 버그리포트: 오너 보고·관측 결함의 수리 PR 이 머지되면 같은 턴에
bug-report/bug-NNN-YYYYMMDD.md(형식 =bug-report/README.md). - 작업 기록: 트랙의 마지막 PR 이 머지되면 같은 턴에
docs/updates/YYYY-MM-DD-slug.md(형식 =docs/updates/README.md) + 등록 2곳(docs/.vitepress/config.mts사이드바,docs/README.md표). 수치는 전 → 후, 미검증은 숨기지 않고 적는다. 오너의 "업데이트 리포트" = 이 문서. main 직행 순수 문서 PR 은.vitepress를 못 만진다(2026-09-09 PR #1462 실측: 사이드바 한 줄 때문에GitHub Full CIscope 실패) — 그 경우 사이드바 등록은 해당 release 를 base 로 한 다음 큐 PR 에 싣고, README 표 등록만 문서 PR 에 넣는다. - 문서 링크는 파일이 실제로 있는 곳을 가리킨다. 머지 전 워크트리 파일은 절대 경로나 브랜치 GitHub URL, 머지 후에는 기본 체크아웃을 fast-forward 한 뒤 상대 링크.
7. 이 문서의 유지
오너 지시가 새로 나오면 지시를 받은 에이전트가 같은 턴에 이 문서(순수 문서 PR → main 직행)와 자기 쪽 지침을 함께 고친다. 항목마다 지시 날짜와 계기가 된 이슈 번호를 남긴다.