이 페이지는 레포 루트 AGENTS.md를 빌드 시점에 그대로 포함해 렌더링한다. 정본은 루트 파일이다.

Barbelic 공통 작업 규칙

작업 전 필독 — 2026-09-14 사용자 결정

모든 Barbelic 작업 세션은 새 작업·인수인계·중단 후 재개·컨텍스트 복구 때 앱 저장소 최상위 AGENTS.md의 작업 지침을 반드시 읽고 시작한다. 앱·문서·관리자·랜딩 작업에 공통으로 적용한다. 아래 23개 원칙 원문도 해결안 선택과 완료 판단에 적용한다. 최신 사용자 지시를 우선하며 자동 재로딩이나 실제 준수를 파일 게시만으로 확인했다고 보고하지 않는다.

아래는 설계·작업 원칙 문서의 원문이다. 변경할 때는 이 문서·별도 원칙 문서·앱 최상위 AGENTS.md의 원칙 본문을 동일하게 갱신한다. 2026-09-14 사용자 지시에 따라 앱의 기존 링크 전용 안내를 원문을 포함한 작업 지침으로 바꾼다.

<!-- design-principles-verbatim-20260914:start --> 2026-09-14 사용자 결정. 각 원칙은 충족해야 할 조건과 판단 기준을 제시하며, 구체적인 해결 방법은 요구사항과 근거에 따라 선택한다.

1. 작업 전 맥락과 지침 확인

   작업의 목적과 적용되는 지침·계약을 이해한 뒤 시작한다. 이어받거나 재개할 때도 최신 결정과 남은 과제를 확인한다.

2. 사용자 목표 보존

   사용자가 요청한 최종 결과와 전체 범위를 유지하고, 명시적인 요청 변경에 따라 갱신한다. 목표를 임의로 축소하거나 무관한 일로 확대하지 않으며, 목표를 달성할 방법은 열어둔다.

3. 끝까지 수행하고 완료 대조

   승인된 작업은 요청한 결과가 갖춰질 때까지 수행한다. 완료 보고 전에 요구사항 전체를 실제 산출물·검증·반영 상태와 대조하고, 필요한 잔여가 있으면 미완료로 밝힌다.

4. 구조적 원인 해결

   증상·확인된 원인·추정을 구분하고, 문제가 발생하는 원리와 지속되는 조건을 해결한다. 당장의 성공만으로 수리의 충분성을 판단하지 않으며, 임시 완화의 효과와 한계를 구분한다.

5. 대안 탐색과 실험

   기존 구현과 익숙한 방식을 정답으로 가정하지 않고 더 나은 대안을 탐색한다. 핵심 불확실성은 작고 되돌릴 수 있는 실험으로 확인하며, 기존안과 새 안을 요구 충족·성능·복잡도·위험·운영 비용이라는 동일한 기준으로 평가한다.

6. 전체 복잡도를 줄이는 단순성

   정확성·데이터 보호·예상 규모·복구 요구를 충족하는 대안 중 전체 수명에 걸친 복잡도가 낮은 구조를 선택한다. 필요한 구조를 과잉 설계로 배제하지 않고, 추상화와 일반화는 제공하는 가치에 비례해 도입한다.

7. S — 단일 책임 (Single Responsibility)

   모듈은 응집된 책임과 일관된 변경 이유를 갖는다. 함께 바뀌어야 하는 것은 모으고, 서로 다른 이유로 바뀌는 책임은 구분한다.

8. O — 개방·폐쇄 (Open/Closed)

   필요한 변화가 안정된 부분에 미치는 영향을 줄이도록 설계한다. 확장 가능성은 실제 변화의 성격에 맞춰 확보하고, 기존 구조도 더 나은 설계를 위해 재검토할 수 있게 한다.

9. L — 리스코프 치환 (Liskov Substitution)

   같은 계약을 따르는 구현은 서로 교체해도 호출자가 의존하는 동작과 보장을 유지한다. 입력의 전제조건을 강화하거나 결과의 보장을 약화하지 않는다.

10. I — 인터페이스 분리 (Interface Segregation)

    소비자는 자신의 역할에 필요한 계약에만 의존한다. 계약의 경계는 소비자의 실제 필요와 변경의 응집성을 기준으로 정한다.

11. D — 의존 역전 (Dependency Inversion)

    상위 정책과 구현 세부사항은 안정된 추상 계약을 통해 연결한다. 정책의 의미가 특정 기술이나 입출력 방식에 불필요하게 종속되지 않도록 의존 방향을 설계한다.

12. 명확한 계약과 경계

    입력·출력·책임·실패의 의미를 명확히 하고, 각 경계에서 그 계약이 성립하는지 확인한다. 계약의 변경과 위반을 드러내어 서로 다른 가정이 조용히 섞이지 않게 한다.

13. 데이터와 의미 보존

    사용자 데이터의 무결성과 합의된 제품 의미를 보존한다. 이를 바꾸는 작업은 명시적인 요구와 승인 범위에 따르며, 설계 개선의 효과와 의미 변경을 구분한다.

14. 확장성

    데이터 규모·분포·동시 사용이 변할 때 비용과 동작이 어떻게 달라지는지 고려한다. 예상 운영 범위에서 요구를 충족하도록 설계하고, 검증한 범위를 넘어선 보장은 단정하지 않는다.

15. 자원 사용의 예측 가능성

    작업량에 따른 자원 소비와 자원 수명을 이해하고, 시스템이 감당할 수 있는 범위 안에서 동작하게 한다. 한계에 도달했을 때의 동작도 정의하며, 자원 제어 방식은 작업의 성격과 측정 근거로 선택한다.

16. 전체 비용의 효율성

    요구를 충족하는 데 드는 계산·입출력·저장·관리의 전체 비용을 줄인다. 특정 최적화 기법을 기본값으로 삼지 않고, 실제 규모와 변경 패턴에서 얻는 이득을 추가 복잡도와 함께 평가한다.

17. 멱등성

    동일한 논리적 작업이 반복 전달되거나 재실행될 수 있는 경계에서는 반복으로 인한 의도하지 않은 추가 효과를 방지한다. 새로운 작업과 같은 작업의 반복을 구분하고, 반복 처리의 의미를 명확히 한다.

18. 복구 가능성

    실패와 중단을 고려하여 요구되는 데이터 보존과 복구 수준을 충족한다. 복구 방법은 작업의 특성·재실행 비용·허용 중단 시간을 근거로 선택한다.

19. 일관성과 원자성

    함께 성립해야 하는 조건과 사용자에게 허용되는 중간 상태를 명확히 한다. 필요한 일관성과 원자성을 보장하면서 처리·저장·공개의 경계를 설계한다.

20. 동시성 안전

    작업의 중첩과 실행 순서 변화가 합의된 결과와 데이터 무결성을 깨뜨리지 않게 한다. 충돌과 오래된 결과의 처리 기준을 명확히 하고, 조정 방식은 요구되는 보장과 부하에 맞춰 선택한다.

21. 재현성

    결과와 실패를 다시 설명하고 확인할 수 있도록 입력·환경·변동 요인을 식별한다. 결정적 동작은 같은 조건에서 재현하고, 비결정적 동작은 변동의 범위와 판단 기준을 명확히 한다.

22. 독립적인 정확성 검증

    구현 자체의 가정을 반복하지 않는 독립된 기준으로 요구 충족 여부를 확인한다. 검증 범위는 영향과 위험에 비례해 정하고, 중요한 불확실성을 드러내며 통과를 위해 요구 수준을 낮추지 않는다.

23. 근거에 따른 판단과 정직한 보고

    판단 기준을 결과 평가 전에 명확히 하고, 관측·측정·추정·미검증을 구분한다. 새로운 근거가 나오면 가정과 선택을 재검토하되, 완료 범위나 성공 기준을 결과에 맞춰 임의로 바꾸지 않는다. <!-- design-principles-verbatim-20260914:end -->

2026-09-11 사용자 결정 — Codex·Claude 공통: Full CI를 반복 디버깅에 사용하지 않는다. 실패 하나 수정 후 전체를 다시 돌리지 말고, 이전 실행의 실패 전체를 수집해 로컬에서 해당 검사 묶음을 수리·검증한 뒤 필요한 원격 검증을 실행한다. 수동 재실행뿐 아니라 승격 PR head 갱신의 자동 Full에도 적용한다. 필수 실패 수리 절차와 재실행 근거를 따른다. 기존 precheck/Merge Check·최종 후보 검증은 유지하며, 지침 추가를 자동 차단 구현 완료로 보고하지 않는다.

이 저장소 dekerd/Barbelic-docs는 관리자 프론트엔드와 정책·계약·운영 절차·업데이트·버그 보고·약관을 포함한 모든 문서를 소유한다. 앱·공통 백엔드·SQL·마이그레이션은 dekerd/Barbelic이 소유한다. 2026-09-14 사용자 결정 #1591로 기존 앱 Full CI 테스트·fixture·helper·검사 전용 실행기의 소유권은 비공개 dekerd/Barbelic-QA1로 이관한다. 앱은 고정한 QA1 버전을 호출하며 QA2는 별도 독립 검증으로 유지한다. 2026-09-15 사용자 지시 #1604로 QA2도 앱이 qa2.lock.json으로 고정해 호출하는 승격 CI 필수 검사가 되었다(QA2 승격 게이트). QA1 운영·이관 상태를 확인하고, 문서 변경만으로 이관이나 운영 검증이 완료됐다고 보고하지 않는다. 같은 날 사용자 예외로 앱 최상위 AGENTS.md에도 설계·작업 원칙 원문과 필독 지시를 유지하며, 상세 문서의 소유권은 이 저장소에 둔다. 안내 파일을 검사하는 앱 CI를 만들지 않는다. 제품명은 Barbelic으로 쓴다.

최신 사용자 결정과 승인된 이슈 범위가 과거 문서보다 우선한다. 저장소 경계, 문서·관리자 운영, 공통 구현·보고 규칙, 세션 제목을 따른다. #1463의 대상 앱 릴리스는 v0.17.7이며 코드 준비·원격 연결·운영 반영을 구분해 보고한다.

2026-09-09 후속 사용자 결정: 랜딩 코드·자산·전용 CI·배포 설정은 dekerd/Barbelic-landing이 소유한다. 랜딩만 변경하면 해당 저장소의 검사·배포로 끝내며 앱 release 큐·전체 CI·DB·앱 배포를 호출하지 않는다. 랜딩의 문서·지침은 이 저장소의 실행·배포 안내를 따른다. 앱의 최초 경로 연결 및 v0.18.0 도메인 이전은 실제 앱 변경 범위에서 별도로 검증한다.

착수·문서 갱신

1. 작업할 저장소·브랜치·dirty 상태·담당 이슈를 확인한다. 위 필독 문서와 문서 저장소 최신 상태, 해당 작업의 정책·설계·운영 문서를 읽고 코드와 문서의 적용 버전을 확인한다. 사용자의 최종 목표·전체 범위·완료 조건을 기존 작업 기록에 유지한다.
2. 구현 전에 원인·성공 기준·Phase 계획을 정하고 승인된 go 범위 안에서 작업한다. 이미 받은 go를 다시 묻지 않는다. 가정과 미실측을 밝히고 무관한 파일은 변경하지 않는다.
3. 정책·계약·설계·운영 방식이 바뀌면 이 저장소의 관련 문서를 갱신한다. 버그 보고는 bug-report/, 작업 기록은 docs/updates/에 작성하고 인덱스·사이드바에 등록한다. 앱에 기록용 문서 커밋·PR을 만들지 않는다.
4. 코드와 문서의 PR·커밋을 연결하고 적용 릴리스를 적는다. 미출시 변경을 운영 반영 완료로 쓰지 않는다. 기존 버전 약관이나 정책 스냅샷의 내용을 이관 편의로 바꾸지 않는다.
5. 작업 제목은 #번호 [진행중 n/m] 오너 이슈 제목처럼 현재 Phase/전체 Phase를 쓴다. 이슈를 맡은 턴에 바로 설정하고, Phase 완료 보고 때 다음 현재 번호로 갱신한다. CI·병합은 전체 Phase 수에 넣지 않는다. 전체 상태 토큰은 세션 제목 규칙을 따른다. 2026-09-10 #1416 사용자 정정: 구현 뒤 세션 상태는 [Precheck] → [Merge Check] → [vX.Y.Z 반영완료]다. precheck 단계에 들어가면 즉시 제목을 바꾸고, Merge Check 요청·대기·실행을 거쳐 실제 목적 release 병합 확인 즉시 반영완료로 바꾼다. 완료 응답 전에 제목 변경 도구 성공까지 확인한다. 세션의 반영완료는 release 병합이며 Production 성공·이슈 종결 조건은 별도로 유지한다. 2026-09-10 HQ 인계 요청: 직접 선행/앞 스텝의 완료·검증·목적 release 반영을 기다리면 #번호·[리팩터링 N-M]을 유지한 [선행대기]를 쓴다. 조건 충족 시 실제 조사/구현 상태로 전환하며 자기 Precheck/Merge Check 대기·GitHub 이슈 제목은 구분한다. 상세 규칙을 따른다.

코드·데이터 경계

• 역할은 모델 이름이 아니라 책임이다. 디자인은 화면 구성·스타일을, 기능 구현은 상태·인증·저장·데이터 로딩·타입·계산·API 연결을 맡는다. 승인되지 않은 시각 재설계를 기능 배선에 섞지 않는다.
• 관리자 코드는 admin/ 안에서 독립 설치·검사·빌드한다. 앱 checkout·submodule·앱 내부 소스 import로 관리자 빌드를 연결하지 않는다. 관리자에서 필요한 서버 기능은 배포된 인증 API/RPC의 계약으로 호출한다.
• 공통 백엔드와 마이그레이션 소유자는 앱 저장소 한 곳이다. 문서·관리자 작업을 이유로 DB나 사용자 데이터를 옮기지 않는다. 원본 등급 데이터 수리는 별도 이슈·손실 감사·사용자 승인·수리 티켓 절차를 따른다.
• 앱 CI는 Markdown 문구·문서용 JSON/CSV·보고서·문서 생성물에 의존하지 않는다. 실제 동작·타입·권한·DB 불변식으로 제품 요구사항을 검증한다. 문서 게시만으로 실행 정책을 바꾸지 않는다.
• 2026-09-09 사용자 결정: 테스트케이스 품질관리 기준 15개를 개별 CASE의 필수 승인 조건으로 적용한다. 위반·증거 누락은 적합으로 인정하지 않으며, 자동 강제 구현 여부와 CASE별 검증 상태를 구분한다.
• 2026-09-10 최신 사용자 결정: #1478에서 와드업·관리자 관련 CASE·단위·컴포넌트·DB 검사를 모두 자동 실행 대상에서 제외한다. 현재75건 범위를 따른다. 일반 사용자 fixture의 Auth Admin 사용은 제외 사유가 아니다. 관리자 타입·빌드는 유지하고 이전 판정은 보존한다.
• TypeScript suppression을 임의로 추가하지 않는다. 외부 입력과 응답은 경계에서 검증한다. 비밀키나 서비스 역할 자격증명을 클라이언트에 넣지 않는다.
• 날짜 테스트는 일반 실행 날짜를 사용할 수 있다. 특정 고정 연도가 언제나 과거라는 전제 등을 고치되, 실제 E2E의 날짜 선택·앱의 원본 요청·DB 저장·재조회 단언을 보존한다. 요청 날짜를 덮어쓰거나 브라우저 시계를 고정해 통과시키지 않는다. 실행 날짜와 달력 전제를 따르며 날짜 정리를 이유로 이미 통과한 전체 CI를 반복하지 않는다.

이 저장소의 검사·게시

• 문서: npm ci --prefix docs, npm run check, npm run build:docs, npm run check:docs-artifact.
• 관리자: npm ci --prefix admin, npm run check:admin, BARBELIC_TARGET=local을 명시한 npm run build:admin. 배포 빌드는 해당 환경의 target과 공개 API 설정을 명시한다.
• npm run build는 문서만 빌드한다. 문서만 바꾸면 관리자·앱 CI나 빌드를 실행하지 않는다. CI는 변경 경로에 따라 docs/admin을 각각 선택하고 verify로 결과를 모은다.
• 문서와 관리자 변경은 이 저장소의 작업 PR에서 검증한다. main은 운영, staging은 검증 환경이며 앱 release 큐에 문서·관리자 PR을 넣지 않는다. 관리자 서버 계약 변경은 앱의 호환 가능한 백엔드가 먼저 배포되어야 한다.
• 배포는 별도 Docs Deploy와 Admin Deploy가 담당한다. 관리자는 별도 프로젝트의 자체 주소 https://admin.barbelic.com/(2026-09-15 #1666)이고 문서 도메인(https://docs.barbelic.com)의 /admin은 그리로 308 이동하며, /legal/**, /account/delete.html은 이 저장소의 원문을 공개 웹용으로 게시한다. 앱 origin(app.barbelic.com)의 같은 주소는 2026-09-15 사용자 결정 #1643(앱 v0.19.3)부터 앱이 자체 사본(public/legal/, public/account/)으로 직접 제공하며 문서 사이트로 rewrite하지 않는다. 새 약관 버전은 이 저장소 게시 → 사본을 복사한 앱 릴리스 → 서버 요구 버전 전환 순서다. 현재 활성화 상태는 운영 문서에 기록한다.
• 다른 작업자가 맡은 PR·브랜치·큐 요청·배포를 변경하지 않는다. 권한·Production·비용·되돌릴 수 없는 변경은 기존 승인 범위와 실제 권한을 확인한다.
• 앱 작업→release 통합 명령은 npm run merge:request -- --pr <N>이다. #1460의 v0.17.6 main 도달 이후, docs 부재 후보를 처리하는 최소 큐 호환 변경도 앱 PR #1487 / main 65a122746에 반영됐다. 해당 선행 수정의 한정된 사용자 승인과 #1463 전체 운영 전환은 구분하며 전환 상태를 확인한다. 이 문서 저장소 PR을 앱 큐에 보내지 않는다.

앱 CI·릴리스 통합 — 2026-09-15 개정(3단계) · 2026-09-10 승인 정책

2026-09-10 오너 용어 지정: 일반 release 큐의 병합 직전 검사 명칭은 Merge Check로 통일한다. 이 프로젝트에서는 충돌·migration 순서/위험·PR head/base·후보 tree와 조건부 push 확인을 포함하며, GitHub의 기본 충돌 판정보다 범위가 넓다. 사전검증(precheck)·전체 검증(full CI)과 구분해 작업 보고에도 같은 명칭을 쓴다.

2026-09-15 개정(오너 지시, #1661·#1659) — 승격 검사 3단계, QA1 완전 퇴역. 오너 지시 원문: "release에 병합할 때는 precheck 없이 merge check만, release→stage 올릴 때 병합된 release 기준으로 precheck만 한 번, stage→main 올릴 때 QA2. QA1은 이번 배포(v0.19.3)부터 완전히 deprecated(워크플로에서 자동 실행되지 않도록)". 앱 반영 = PR #1663·#1664(release/v0.19.3), 정본 = 릴리스 프로세스·QA2 승격 게이트. 아래 2026-09-10 항목 중 이와 다른 서술(PR 전 precheck 필수, release→staging full CI, staging→main tree 재사용, dry-run full)은 폐기됐다.

• ① 작업 PR → release/vX.Y.Z: 큐(npm run merge:request -- --pr <N>)의 Merge Check만. 세션은 PR 전 precheck를 돌리지 않는다(Phase마다 npm run check = 정적 검사). 세션 제목은 [진행중 n/m] → [Merge Check] → [vX.Y.Z 반영완료].
• ② release → staging 승격 PR: GitHub Full CI의 precheck 레인 — static-checks(정적 검사·미사용 ratchet·빌드·산출물) + migration-smoke(빈 DB에 마이그레이션 전체 재적용·schema.sql 대조). 브라우저·단위·pgTAP 없음.
• ③ staging → main 릴리스 PR: GitHub Full CI의 QA2 레인(qa2-product-contracts)만. main 병합 tree = 배포된 staging tree, staging 배포 3잡(database·functions·frontend) 성공은 scope 잡이 확인. 같은 tree 성공 기록 재사용은 폐기.
• QA1(dekerd/Barbelic-QA1)은 어느 워크플로도 준비·실행하지 않는다(단위·pgTAP·브라우저·화면 정합성·배포 뒤 smoke·수동 smoke·소셜 로그인 가정 로그인 검사 모두 자동 경로에서 제거). 큐 --dry-run은 같은 Merge Check를 하고 push만 하지 않는다. QA1 저장소는 동결한다.

#1491, v0.17.8 대상. 여러 작업을 합칠 때마다 full CI를 반복하던 대기를 줄이도록 오너가 승인했다. 앱 main 6afe58ec에 설치됐으며 정상 큐의 실제 실행 시간과 운영 배포 성공은 아직 확인 전이다. 상세 상태는 적용 기록에서 구분한다.

• 작업 PR 전에는 npm run ci:precheck-local -- --release origin/release/vX.Y.Z로 최신 release를 반영하고 정적·단위·빌드 검사와 서버 변경 시 DB 검사를 수행한다. 브라우저·viewport는 실행하지 않는다.
• 작업→release는 기존 merge:request 큐로 순차 병합한다. 최신 base 병합·충돌·migration 순서/위험·PR head/base·후보 tree·조건부 push를 확인하고, full CI를 실행하거나 full 성공 기록을 만들지 않는다. 추가 precheck 장부나 승인 게이트를 만들지 않는다.
• release→staging은 최종 병합 후보에서 full CI를 실행한다. staging→main은 같은 tree의 유효한 full 성공 기록과 현재 staging 배포·smoke 증거를 확인한 뒤 재사용하며, 기록이 없거나 무효이면 full CI를 실행한다. 환경별 배포·smoke는 유지한다.
• 명시적 npm run merge:request -- --pr <N> --dry-run은 진단용 full 검사 후 병합하지 않는 실행이다. ci:full-local -- --only <단계> 부분 재현을 유지하며 일반 작업 세션에서 full을 중복 실행하지 않는다.

기존 문서 해석

분리 전 AGENTS와 과거 업데이트는 당시 기록이다. 기존 docs/ 경로는 이 저장소를 가리킨다. 앱의 작업 → release → staging → main 및 데이터 보호 규칙은 유지하지만, 과거 docs/admin 결합 빌드·앱 main 문서 직행·문서 문자열 게이트는 #1463 전환으로 대체된다. 모든 작업자는 변경된 공통 지침을 참조해야 하며 실행 중 세션의 자동 재로딩을 가정하지 않는다.

완료 범위 — 2026-09-10 오너 정정

구현이 끝나면 최신 목적 release 반영·자기 PR의 Merge Check·실제 release 병합까지 이어서 처리한다(PR 전 precheck는 2026-09-15 폐기). Draft PR이나 선택 검증에서 멈추고 오너에게 다음 실행을 재요청하지 않는다. 이미 승인된 정책의 미반영은 자기 작업에 필요한 최소 변경으로 해결하며 다른 담당자의 브랜치·큐는 조작하지 않는다. 상세 승인 경계와 완료 기준은 공통 지침을 따른다.