frontend-quality-gates / merge / static checks (pull_request) Successful in 1m49s
frontend-quality-gates / merge / tests (pull_request) Successful in 22m18s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 6m54s
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / main / checker self-tests (pull_request) Skipped
문제: 작업 매뉴얼·루트 지침·스킬이 「desktop의 FE-GATE-013은 호스트 제약
실패로 적고 merge 가능 여부는 소유자가 정한다(결정 대기 D8)」라고 적고
있다. 1d3eb901 뒤로 workflow와 scripts/verify.sh는 이 게이트를
scripts/run-in-system-container.sh 안에서 돌리고, 다른 게이트처럼 rc로
센다. CHANGELOG에는 이 브랜치의 변경이 없다.
고른 방법:
- gates.md 3절 문단을 「시스템 컨테이너 안에서 돈다」로 바꾸고, AGENTS.md
·improve.md·new-feature.md·operate.md·desktop-gates 스킬의 기록법
문구를 그 절을 가리키게 고친다.
- decisions.md: 소유자 결정(2026-11-11, design-docs template-program
README 5절 e)을 2.1절 행으로 더하고 열린 결정 대기 D8을 닫는다.
evidence.md의 근거 행을 새 규칙 이름과 runner 사건으로 고친다.
- docs/operations/ci-quality-gates.md, docs/testing/taxonomy.md,
README.md에 컨테이너 경로와 그 한계(root라 비특권 userns 조건은 증명하지
않음, privileged를 막는 runner에서는 깨짐)를 적는다.
- CHANGELOG 미출시 절에 이 브랜치의 변경을 적는다.
위험·한계: desktop·runner에서 FE-GATE-013이 실제로 초록인지는 이 브랜치
끝의 merge 단계 실행으로 확인한다.
검증: 노트북 scripts/verify.sh docs rc=0. desktop verify:documentation
PASS_SCOPED, 문서를 읽는 시험 넷(changelog-review-ids,
documentation-readiness, template-contract-documents,
deletable-history-documents) 29개 통과.
8.0 KiB
8.0 KiB
새 기능 — 화면과 그 화면이 쓰는 API 호출 만들기
이 템플릿(또는 복사한 프로젝트)에 기능 하나를 더하는 일의 절차다. 만드는 순서와 단계별 판단 기준의 정본은 docs/manual/이다. 이 playbook은 그것을 다시 쓰지 않고, 크기·받을 것·완료 기준·보고만 정한다.
1. 언제 쓰나
- 새 기능 폴더
src/features/<id>/를 만든다(라우트, 페이지, API 계약, application input, HTTP adapter 기여). - 짝 백엔드의
new-feature.sh로 만든 API에 화면을 붙인다. - 있는 기능을 고치는 일은 이 playbook이 아니라 improve.md다. 기능 폴더 밖(플랫폼, adapter, 셸)을 바꿔야 기능을 만들 수 있으면 그 부분은 improve 구조 변경이고 크기가 큼이다.
2. 받아야 할 것
- 기능 ID(케밥 표기, 40자 이하, 기존 기능·context ID와 겹치지 않음)와 속할 context(기존 / 새로).
- 짝 백엔드 쪽 사실: 경로(
<base>의 복수형 규칙은docs/manual/reference/create-feature.md), 작성 API가 있는지(--with-create), 재전송될 수 있는 쓰기인지(--keyed는 백엔드 create가 멱등성 executor 뒤에 있을 때만), 인증 모드. - 계약 패키지 신원(
--package·--digest·--revision). 없으면 자리표시자 신원으로 만들고, 출시 전에 채운다. - 커밋 허용 여부와 브랜치.
3. 크기와 사고 순서
- 생성 명령 출력 그대로 기능 하나를 채우면 중간이다(기능 폴더 하나 안). 생성 명령이 함께 만드는 새 context(
--context없이 생기는<base>-context)도 중간이다. 템플릿에는 context가 없어 첫 기능은 늘 이렇게 시작한다. - 큼: context를 손으로 만들거나 기존 context 경계를 바꾸는 일, 기능 폴더 밖 파일(
docs/manual/03-outside-feature-folder.md)을 생성 명령 밖에서 고치는 일, 짝 백엔드와 새 계약(오류 code, 응답 모양)을 맞추는 일, 초기 JS 예산을 올려야 하는 일. 큰 일은 research-design.md로 소유자 검토를 먼저 받는다. - 선행 사례:
docs/manual/reference/patterns.md(기능 개발 패턴과 예제 위치), 매뉴얼 안의 코드 조각. 템플릿에는 복사해 볼 기능 샘플이 없다. 다른 기능 폴더를 복사해 이름을 바꾸지 않는다. - 스킬:
new-feature(이 절차의 실행 순서표). 매뉴얼 01장이 단계마다 「쓸 스킬」을 적는다. 동작은superpowers:test-driven-development로 테스트를 먼저 쓴다.
4. 절차
docs/manual/README.md와docs/manual/01-add-a-feature.md0단계(경계와 소속)를 읽고 크기를 정한다.- 뼈대:
corepack pnpm create:feature <id>(필요하면--context,--with-create,--keyed). 소유자 환경에서는 pnpm을 노트북에서 돌리지 않으니 desktop에서 만들고 만든 파일을 돌려받는다:scripts/verify.sh script create:feature --apply-back -- <id> --with-create. 노트북 작업 트리에 생긴 파일을git status로 본다(operate.md 4.1절). - 출력의
Next:목록을 보고에 옮긴다. 그 목록이 돌릴 명령과 다시 쓸 기록(초기 JS 기록 등)이다. - 매뉴얼 01장 2~10단계로 뼈대를 실제 기능으로 바꾼다. 막히면 02장 결정표(context 경계, 계약 출처, 재시도 의미, 결과 불명, 인증, 페이지 템플릿, 파일 업로드), 폴더 밖 파일은 03장, 짝 백엔드 인증은 04장.
- import는 기능 폴더 안 계층 규칙과 꼭 지킬 것 1~3을 지킨다. 편집 훅의 경계 알림(N3)이 나오면 그 자리에서 고친다. 다른 기능을 import하지 않는다. adapter는 기능의
adapters/나 배럴로만 닿는다. - 테스트는
tests/features/<id>/에 둔다(기능과 함께 지워진다). 결과 불명 쓰기와 재전송 입구는docs/manual/02-decision-tables.md3·4절 기준으로 테스트한다. - 기준선과 증거: 초기 JS 기록(
config/scale/feature-shape-ceilings.json의initialJavascript)은 생성 출력Next:의 명령으로 다시 쓰고 같은 커밋에 넣는다. 손으로 고치지 않는다. desktop에서 돌려 돌려받는다:scripts/verify.sh exec --apply-back -- node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write. 예산(config/performance/budgets.json)을 넘으면 올리기 전에 멈추고 묻는다(꼭 지킬 것 4). - 제거 확인: 매뉴얼 01장 11단계. 기능을 지운 사본이 게이트를 통과해야 한다:
scripts/verify.sh script test:sample-removal -- --feature=<id>. merge 단계의 FE-GATE-020은 목록에 적은 기능과 새로 생성한 기능만 지우므로 이 기능의 제거를 대신 보여 주지 않는다. - desktop에서 merge 단계와 lab 게이트를 돌린다:
scripts/verify.sh merge,scripts/verify.sh gate FE-GATE-026(새 기능은 lazy 라우트를 더하므로 늘 돌린다). 결과를 보고 싶으면 서브에이전트arch-reviewer(경계 리뷰)와verify-app(desktop에서 앱을 띄워 그 라우트를 연다)에 맡긴다.
5. 완료 기준
- 생성 명령으로 시작했고, 템플릿 소유 파일을 생성 명령 밖에서 고치지 않았다(고쳤으면 큼으로 올려 결정을 받았다).
- 동작마다 테스트가 있고 RED → GREEN을 봤다.
- 초기 JS 기록이 빌드와 맞는다(
test:unit안의 대조). scripts/verify.sh merge가 통과했고 FE-GATE-026도 통과했다.- 이 기능을 지운 사본이 통과한다(
test:sample-removal -- --feature=<id>). - 다운스트림에 보이는 변경(공개 포트, 생성 명령 출력)이 있으면
CHANGELOG.md미출시 절에 적었다.
6. 하지 말 것
- 다른 기능 폴더를 복사해 이름을 바꾸지 않는다. 접두어 없는 전역 ID, 복사된 계약 출처, 기능 밖 테스트 의존으로 막힌다.
- 기능끼리 import하지 않는다. 공용이 필요하면
src/contracts/(공유 어휘)나 kernel로 옮기는 일을 따로 묻는다. - 예산·기준선·기능 모양 상한을 올려 통과시키지 않는다.
- 플랫폼을 지키는 테스트를 기능에 묶지 않는다. 기능 테스트가 지워도 되는 문서(
docs/reviews/등)를 읽지 않는다. - 짝 백엔드 repo를 고치지 않는다. 백엔드가 바꿔야 할 것은 보고에 "백엔드에 넘길 것"으로 적는다.
7. 막혔을 때
- 생성 명령이 거부하면
docs/manual/reference/errors.md에서 메시지를 찾는다. 고칠 파일이 적혀 있다. - 짝 백엔드 응답 모양·오류 code가 문서와 다르면 코드(백엔드 생성기, 이 repo의
src/adapters/http/backend-envelope.ts)까지 따라가 사실을 적고 묻는다. 문서만 보고 판정 표를 정하지 않는다. - 기능 폴더 밖을 고쳐야만 되면 거기서 멈추고 README 5절 형식으로 묻는다.
- brief가 매뉴얼 예시 이름(
invoice-feature등)을 기능 ID로 주면 그대로 만들지 말고 묻는다. 템플릿 시험(tests/unit/manual-code-blocks.test.ts)이 저장소 사본에 그 이름으로 기능을 만든다.
8. 보고 형식
README 6절에 더해 적는다.
| 칸 | 적을 것 |
|---|---|
| 기능 | ID, context, 생성 명령(인자 그대로) |
생성 출력 Next: |
목록과 각 항목을 했는지 |
| 바꾼 기록 | 초기 JS 기록·기능 모양 기록의 전후 숫자와 다시 쓴 명령 |
| 검증 | scripts/verify.sh merge의 게이트별 rc, 로그 경로, 제거 드릴 결과 |
| 백엔드에 넘길 것 | 있으면 |
9. 자주 하는 실수
- 한 테스트 파일을
pnpm exec vitest run <file>로 돌려 생성물 import 오류로 실패한다.node scripts/run-vitest.ts run <file>을 쓴다. - 초기 JS 기록을 다시 쓰지 않아
test:unit이 기록이 낡았다고 실패한다.Next:의 명령으로 다시 쓴다. CI=true없이 돌려 통과하고 CI에서 떨어진다.scripts/verify.sh로 돌린다.- 매뉴얼 예시 기능 이름을 그대로 써서 템플릿 테스트의 글자와 부딪친다. 제품 이름을 쓴다.