이 대화를 모르는 서브에이전트에게 AGENTS.md부터 읽혀 두 일(새 기능 만들기, diff 리뷰)의 절차를 쓰게 했다. 막힌 곳 16, 사실과 다른 곳 5가 나왔다. 고친 것: - new-feature: 생성·기준선 다시 쓰기를 desktop에서 하고 --apply-back으로 받는다. FE-GATE-020은 제품 기능을 지우지 않으므로 그 기능의 제거 드릴을 따로 돌린다(사실과 달랐다). 생성 명령이 만드는 첫 context는 중간이다. 새 기능은 FE-GATE-026도 돌린다. 매뉴얼 예시 이름이 오면 묻는다. 초기 JS 기록의 파일을 적는다. - gates·improve·AGENTS: FE-GATE-013 결정 대기 동안의 merge 판정 문구, PR·diff 리뷰도 merge 단계 전부를 돌린다, diff 리뷰의 base·head 규칙과 ID 체계와 둘 곳, 라운드 세는 법, "빠른 게이트 8개"를 "검사 8개 (package script)"로. - review-criteria: 발견 한 개의 칸(가이드 36.3절 줄임)과 통제 M0~M4· 증거 E0~E4의 뜻을 옮긴다. 가이드 없이 판정할 수 있다는 문장을 맞춘다. - README·CLAUDE·decisions·rules/docs·skills: 최근 리뷰 README의 실제 절 이름, 사고 순서 흔적의 여섯 칸과 design-docs 위치, 보고 칸과 말투의 정본, `docs/work/README.md`를 가리키게, 리뷰 README 조치 절 예외, 스킬의 새 명령 모양. 고치지 않은 것: 세션에 주입된 옛 CLAUDE.md(시험 세션이 이 브랜치 전에 시작했다). 검증: scripts/verify.sh docs rc=0, scripts/verify.sh hooks 통과.
8.1 KiB
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. 절차
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-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로 돌린다.- 매뉴얼 예시 기능 이름을 그대로 써서 템플릿 테스트의 글자와 부딪친다. 제품 이름을 쓴다.