Files
clean-architecture-frontend…/docs/work
DongHyeonka 50d623c40e
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Canceled after 0s
frontend-quality-gates / merge / static checks (pull_request) Canceled after 0s
frontend-quality-gates / merge / tests (pull_request) Canceled after 0s
frontend-quality-gates / merge / browser tests (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Canceled after 0s
frontend-quality-gates / external-vulnerability-provider (pull_request) Canceled after 0s
frontend-quality-gates / external-provenance-provider (pull_request) Canceled after 0s
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Canceled after 0s
frontend-quality-gates / deploy-promoted-release (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Canceled after 0s
frontend-quality-gates / main / self-tests and removal drills (pull_request) Canceled after 0s
Merge remote-tracking branch 'origin/main' into fix/r9-living-docs-sync
# Conflicts:
#	AGENTS.md
#	docs/work/reference/decisions.md
2026-11-13 04:30:07 +09:00
..

작업 매뉴얼

이 폴더는 이 repo에서 하는 모든 일의 절차서다. 사람과 AI 세션이 같은 절차를 쓴다. 읽는 순서는 하나다: 루트 AGENTS.md(지도) → 이 README → 맡은 일의 playbook 하나. Claude Code 세션에서는 루트 CLAUDE.md가 AGENTS.md를 가져온다. 규칙의 정본은 AGENTS.md, .dependency-cruiser.json, config/ci/gates.json이다. 이 폴더는 규칙을 다시 쓰지 않고, 일하는 순서를 정한다.

1. 어떤 playbook인가

맡은 일 playbook
새 기능을 만든다(create:feature) new-feature.md
있는 코드를 리뷰·수정·리팩터링·최적화한다. 구조·테스트 구조를 바꾼다 improve.md
바꾸기 전에 대안을 비교하고 소유자 결정을 받는다 research-design.md
매뉴얼·안내 문서를 쓰거나 고친다 docs-writing.md
게이트를 돌린다, 릴리스한다, 파생 프로젝트에 템플릿 변경을 넘긴다 operate.md
큰 일을 나눠 다른 세션에 맡긴다 delegate.md

둘에 걸리면 이렇게 고른다. 결정이 먼저 필요하면 research-design이다. 동작이 바뀌는 코드가 있으면 new-feature나 improve다. 문서만 바뀌면 docs-writing이다.

2. 크기 정하기

  • 크기는 작음·중간·큼 셋이다. 정의와 크기별로 할 단계는 design-docs(이 repo 옆 checkout desktop-server-git/design-docs) conventions/work-thinking-order.md 2절이 정본이다.
  • 요약: 작음은 파일 몇 개·새 결정 없음·되돌리기 쉬움, 중간은 경계 하나(adapter 그룹, 기능 폴더, 문서 폴더) 안의 여러 파일이나 소유자 없이 정할 작은 결정 하나, 큼은 새 체계·아키텍처·공개 계약·소유자 결정이 필요한 일이다.
  • brief(작업 지시문)에 크기가 있으면 그대로 한다. 올릴 수는 있고 내릴 수는 없다. 올리면 이유를 보고에 쓴다. brief가 없으면 스스로 정한다. 망설여지면 큰 쪽이다.
  • 아래는 파일이 하나여도 큼이다: import 규칙(.dependency-cruiser.json), 최상위 src/ 폴더, adapter 배럴의 공개 표면, 게이트 단계·기준(config/ci/gates.json, config/performance/budgets.json), 짝 백엔드와 맞춘 계약(config/contracts/), 런타임 설정 키, 파생 프로젝트가 따라 고쳐야 하는 변경, 보안 정책.
  • 큰 일은 만들기 전에 멈추고 소유자 검토를 받는다(research-design.md). 소유자가 그 변경을 이미 정했으면(결정 색인 행, 소유자 원문) 그 결정이 소유자 검토다. 출처와 시각을 보고에 적고 만든다. 결정이 다루지 않은 범위만 멈추고 묻는다.

3. 모든 작업의 공통 단계

  1. 기준 커밋을 고정한다. git rev-parse HEAD를 산출물과 보고에 적는다.
  2. 이미 정한 것을 읽는다: reference/decisions.md, docs/reviews/에서 가장 최근 리뷰 README의 「결정이 필요한 것」「조치」「미검증」 절. 정한 것은 다시 묻지 않는다.
  3. 바뀌는 경계를 찾고 가장 가까운 src/<계층>/AGENTS.md를 읽는다. 위험은 파일 수가 아니라 경계로 정한다: 사용자 데이터(결과 불명 쓰기, 브라우저 저장소), 공개 포트·배럴, merge 게이트, 짝 백엔드 계약을 건드리면 높다.
  4. 스킬을 고른다. playbook 3절에 작업별 스킬이 있고, 이 repo의 스킬은 .claude/skills/다(new-feature, desktop-gates, 분야 지식 fe-*). 여러 분야에 걸치면 experts.md의 명단·렌즈표로 고른다. 파일을 바꾸는 일은 직접 하거나 하위 세션에 맡기고, 결과만 받는 일은 서브에이전트에 맡겨도 된다(delegate.md 4.3절).
  5. 자기 worktree와 자기 브랜치에서 일한다. 다른 세션과 같은 checkout을 쓰지 않는다.
  6. 무거운 실행(pnpm, 게이트, 브라우저, 빌드)은 operate.md 「실행 위치」대로 scripts/verify.sh로 한다.
  7. 일이 다른 경계나 brief 범위를 넘어야 하면 거기서 멈추고 묻는다(5절).
  8. 완료를 말하기 전에 검증한다(superpowers:verification-before-completion). 돌리지 못한 검증은 못 돌렸다고, 이유와 함께 쓴다(꼭 지킬 것 5).

4. 커밋

  • 커밋·push는 brief가 허용한 것만 그 작업의 자기 브랜치에 한다. 커밋과 push는 따로 허용된다. 커밋만 허용됐으면 push하지 않는다(desktop 검증은 scripts/verify.sh가 패치로 옮긴다).
  • main 병합, main·다른 브랜치 push, force push, PR 병합은 하지 않는다. 그것은 소유자(또는 소유자가 정한 총괄)가 한다.
  • 메시지 형식은 design-docs conventions/commit-and-pr.md를 따른다. AI 꼬리말과 자리표시자(TBD, TODO, 채우지 않은 칸)를 넣지 않는다. 결함 수정은 꼬리말 Refs:에 발견 ID를 적는다(형식은 reference/review-criteria.md 11절).
  • 커밋 하나에 논리 변경 하나다. 동작 변경을 위한 리팩터링은 앞 커밋으로 나눈다. 그 작업이 바꾼 파일만 stage한다.

5. 막혔을 때

  • 소유자만 정할 수 있는 것(공개 계약, 파생 프로젝트 동작, 보안 정책, 게이트 기준, 되돌리기 비싼 선택)은 근거와 권하는 안을 붙여 한 번 묻고, 그 항목만 멈춘다.
  • brief를 준 쪽이 있으면 그쪽에 묻는다. 없으면 소유자에게 묻는다. 형식: 항목 · 선택지 · 권하는 안과 이유 · 정할 사람.

6. 보고

  • 맨 앞에 결과(완료 / 부분 / 못 함)와 브랜치·커밋을 쓴다. 그다음 변경, 확인(명령 · 실행 위치 · rc · 로그 경로), 범위 밖에서 본 것(고치지 않음), 남은 문제를 쓴다. 남은 문제를 숨기지 않는다.
  • 보고는 쉬운 한국어로 쓴다. 코드·명령·로그 인용만 원문 그대로 둔다. 숫자(테스트 수, 실패 수, 시간)는 로그에서 옮긴다.
  • 착수할 때 예측(p30·p50·p80과 근거)을, 끝 보고 직전에 실측을 docs/ledger/estimates.jsonl에 한 줄씩 더한다(형식 docs/ledger/README.md).
  • 사고 순서 흔적 칸(목적·선행 사례·방법·필요한 정보·격차·만들고 시험 여섯 줄, 생략한 단계는 이유)을 둔다(design-docs conventions/work-thinking-order.md 5절). 다른 세션이 맡긴 일이면 design-docs conventions/delegation-loop.md 5절 양식을 쓴다.

7. 필요할 때만 읽는 문서

문서 내용
reference/gates.md scripts/verify.sh, 언제 무엇을 돌리나, merge 가능 판정, CI env, 문서 검사 범위
reference/review-criteria.md 결함 정의, 등급, 증거, 28개 관점마다 볼 곳, 리뷰 문서 양식
reference/structure.md 폴더·모듈·코드 구조 기준, 바꿀 때 같이 고칠 것
reference/testing.md 테스트 위치, 검출력 확인, 가끔 떨어지는 테스트
reference/performance.md 예산 세 맥락, 측정 조건, 숫자를 고칠 때
reference/defect-patterns.md 반복해서 나온 결함의 모양과 막는 기준
reference/decisions.md 이미 정한 결정의 색인, 결정 대기 쓰는 법
evidence.md 이 매뉴얼의 규칙이 나온 사건과 지난 리뷰 ID

8. 이 폴더를 고칠 때

  • 분량 상한이 있다: 지도(루트 AGENTS.md), 루트 CLAUDE.md, 폴더 지역 규칙(src/**/AGENTS.md, 옆에 @AGENTS.md 한 줄 CLAUDE.md), 이 README, playbook, 진입 경로(지도 + 루트 CLAUDE.md + README + playbook 하나). 줄 수의 정본은 scripts/check-work-docs.py의 상수이고, 넘으면 그 검사가 상한과 함께 알린다. reference/는 상한이 없다.
  • 본문에 지난 리뷰 ID·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 evidence.md로 옮긴다. 루트 AGENTS.md·CLAUDE.md, src/**/AGENTS.md, .claude/ 아래 문서도 같다. reference/decisions.md·reference/defect-patterns.md와 리뷰 문서는 ID를 둔다.
  • 고친 뒤 scripts/verify.sh docs(노트북)와 desktop scripts/verify.sh script verify:documentation이 통과해야 한다. 절차는 docs-writing.md다.