Files
clean-architecture-frontend…/docs/work/new-feature.md
T
DongHyeonka ba72b86595
frontend-quality-gates / merge / static checks (pull_request) Successful in 2m7s
frontend-quality-gates / merge / tests (pull_request) Successful in 20m56s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 6m56s
frontend-quality-gates / FE-GATE-014 / config-compatibility (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-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-019 / hosting-header (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-023 / runbook-api-degradation (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-018 / field-web-vitals (pull_request) Skipped
frontend-quality-gates / main / checker self-tests (pull_request) Skipped
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
chore(merge): FE-GATE-013 판정·시험 timeout PR들이 들어간 main을 받는다
main(5250ff95)의 PR #17·#18·#20·#21·#22를 받는다. 충돌 정리:
- tests/setup.ts: main의 자식 프로세스 timeout 감시를 그대로 두고, Testing
  Library는 DOM이 있는 파일에만 불러오는 이 브랜치의 방식을 남긴다.
- tests/system/ci-runner/ci-artifact-contract.test.ts: main이 같은 결함
  (.claude 추적 파일 ENOENT)을 저장소 배치 등록부의 provider-fixture-skip
  집합으로 이미 고쳤다. main 쪽을 받고 이 브랜치의 f90ffb6c 고침은 버린다.
  CHANGELOG의 그 행도 지운다.
- 작업 매뉴얼·스킬(gates.md 3절, operate·improve·new-feature, evidence,
  desktop-gates·fe-testing 스킬): 기본은 시스템 컨테이너 경로, main의 D8
  판정(사전 점검의 userns 제한 하나뿐이고 뒤 명령 모두 rc=0이면 merge
  판정에서 뺀다)은 컨테이너를 띄울 수 없는 호스트에 쓴다.
- 그 호스트에서 D8 절차를 그대로 돌릴 수 있게 scripts/verify.sh에
  VERIFY_HOST_ENVIRONMENT=off(hostEnvironment 게이트를 이 호스트에서 바로
  돈다)를 더하고 원격 실행에도 넘긴다. 시험 하나를 더한다.
- decisions.md는 main 그대로(D8이 2.2절에 있어 이 브랜치의 O-21 행은 겹친다).

검증(노트북): python3 -m unittest discover -s scripts/tests 73개 통과,
scripts/verify.sh docs rc=0. desktop merge 단계는 이 커밋에서 다시 돈다.
2026-11-12 20:00:50 +09:00

8.1 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. 절차

  1. docs/manual/README.md와 docs/manual/01-add-a-feature.md 0단계(경계와 소속)를 읽고 크기를 정한다.
  2. 뼈대: 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절).
  3. 출력의 Next: 목록을 보고에 옮긴다. 그 목록이 돌릴 명령과 다시 쓸 기록(초기 JS 기록 등)이다.
  4. 매뉴얼 01장 2~10단계로 뼈대를 실제 기능으로 바꾼다. 막히면 02장 결정표(context 경계, 계약 출처, 재시도 의미, 결과 불명, 인증, 페이지 템플릿, 파일 업로드), 폴더 밖 파일은 03장, 짝 백엔드 인증은 04장.
  5. import는 기능 폴더 안 계층 규칙과 꼭 지킬 것 1~3을 지킨다. 편집 훅의 경계 알림(N3)이 나오면 그 자리에서 고친다. 다른 기능을 import하지 않는다. adapter는 기능의 adapters/나 배럴로만 닿는다.
  6. 테스트는 tests/features/<id>/에 둔다(기능과 함께 지워진다). 결과 불명 쓰기와 재전송 입구는 docs/manual/02-decision-tables.md 3·4절 기준으로 테스트한다.
  7. 기준선과 증거: 초기 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).
  8. 제거 확인: 매뉴얼 01장 11단계. 기능을 지운 사본이 게이트를 통과해야 한다: scripts/verify.sh script test:sample-removal -- --feature=<id>. merge 단계의 FE-GATE-020은 목록에 적은 기능과 새로 생성한 기능만 지우므로 이 기능의 제거를 대신 보여 주지 않는다.
  9. 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도 통과했다(컨테이너를 띄울 수 없는 호스트의 FE-GATE-013은 reference/gates.md 3절 조건과 문구로 적었다).
  • 이 기능을 지운 사본이 통과한다(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로 돌린다.
  • 매뉴얼 예시 기능 이름을 그대로 써서 템플릿 테스트의 글자와 부딪친다. 제품 이름을 쓴다.