Files
clean-architecture-frontend…/docs/work/new-feature.md
T
DongHyeonka bdda84f844 docs(work): desktop FE-GATE-013을 조건부로 merge 판정에서 빼기로 정한다
문제: FE-GATE-013을 멈춤 기준에서 어떻게 셀지가 결정 대기라, desktop에서
merge 판정을 하면 매번 「merge 가능 여부는 소유자가 정한다」로 끝났다.
desktop의 ssh 셸은 비특권 user namespace를 막아 test:system 사전 점검이
호스트 원인으로 실패한다.

고른 방법: 소유자 결정(2026-11-11, 「그 조건이 되는 실행 환경을 찾아
초록으로」)에 따라 총괄이 권하는 안으로 정했다(2026-11-12).
- merge 판정에서 빼는 조건 둘: 실패가 사전 점검의 user namespace 제한
  하나뿐이고, `scripts/verify.sh parts FE-GATE-013`의 뒤 명령이 모두 rc=0.
- 게이트 「충족」은 조건을 갖춘 runner에서 FE-GATE-013이 통과한 것으로만
  센다.
- decisions.md: 3.1절(열린 결정)에서 빼고 2.2절에 결정·버린 안·재검토
  조건을 적었다. evidence.md 행에 결정 번호를 더했다.
- gates.md 3절의 보고 문구, improve.md 멈춤 조건 3, operate.md 4.1절,
  new-feature.md 완료 기준, desktop-gates 스킬 6단계를 새 규칙으로 고쳤다.
버린 안: runner에서 통과할 때까지 merge 판정을 미충족으로 두기. 그
runner가 아직 없어 모든 PR의 merge 판정이 막힌다.

위험: desktop에서 test:system의 provider 테스트는 여전히 돌지 않는다.
그 몫의 결함은 runner가 FE-GATE-013을 돌 때까지 merge 판정에서 안 보인다.
뒤 명령 목록을 옮겨 적지 않고 gates.json `commandIds`를 가리킨다.

검증: python3 scripts/check-work-docs.py OK(지난 ID 줄 0),
python3 -m unittest discover -s scripts/tests 71개 통과. 문서 검사는
desktop에서 돌린다.
2026-11-12 10:49:34 +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-013은 reference/gates.md 3절 조건을 채워 빼고 그 문구로 적었다) 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로 돌린다.
  • 매뉴얼 예시 기능 이름을 그대로 써서 템플릿 테스트의 글자와 부딪친다. 제품 이름을 쓴다.