프론트에는 맡은 일별 작업 절차서가 없었다. 세션은 루트 CLAUDE.md의 리뷰 기준만 읽고 시작했고, 개선 작업 기준은 main에 들어가지 않은 초안 (브랜치 docs/improvement-manual의 docs/improvement 11개)에만 있었다. 백엔드 docs/work/와 같은 모양으로 README(크기·공통 단계·커밋·보고), playbook 여섯(new-feature, improve, research-design, docs-writing, operate, delegate, 모두 같은 9절 뼈대), reference 일곱(gates, review-criteria, structure, testing, performance, defect-patterns, decisions)과 evidence.md를 둔다. 초안의 장을 나눠 옮긴 표는 evidence.md 1.1절이다. SPEC.md의 공통 완료 기준 9개는 improve.md 5절로 옮겨, 문서 체계 정리가 SPEC.md를 이력으로 옮길 수 있게 한다. 진입 문서에는 지난 리뷰 ID를 쓰지 않고 내용과 날짜로 쓴다. ID는 evidence.md와 결정·결함 패턴 색인에만 둔다. 결함 패턴 번호 P-NN은 결정 번호 꼴과 겹쳐 영역 글자+번호(G·T·C·S·W·B)로 다시 매기고 옛 번호 대응을 evidence.md 4절에 남겼다. 열린 결정 대기는 2026-11-06 리뷰 기준으로 갱신했다. 버린 대안: 초안처럼 docs/improvement/ 장 번호 체계를 유지하기. 백엔드와 진입 경로·검사기가 갈라진다. 위험·한계: 이 커밋만으로는 문서 검사 범위 밖이다. docs/README.md가 이 폴더를 링크하는 커밋부터 verify:documentation이 경로를 본다. cold-read 시험은 하지 않았다. 검증: python3 scripts/check-work-docs.py rc=0(뒤 커밋에서 더함). Refs: design-docs harness/01-harness-design.md 13절, PR #6
7.1 KiB
7.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를 여는 일, 기능 폴더 밖 파일(
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). 생성은 파일을 쓰는 일이라 노트북에서 해도 되지만 node가 필요하다. 소유자 환경에서는 desktop에서 만들고 결과를 커밋으로 가져오거나, 노트북 깨끗한 복제본에서 만든다(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 기록은 생성 출력
Next:의 명령으로 다시 쓰고 같은 커밋에 넣는다. 손으로 고치지 않는다. 예산(config/performance/budgets.json)을 넘으면 올리기 전에 멈추고 묻는다(꼭 지킬 것 4). - 제거 확인: 매뉴얼 01장 11단계. 기능을 지운 사본이 게이트를 통과해야 한다(
test:sample-removal -- --feature=<id>, FE-GATE-020). - desktop에서 merge 단계를 돌린다:
scripts/verify.sh merge. 결과를 보고 싶으면 서브에이전트arch-reviewer(경계 리뷰)와verify-app(desktop에서 앱을 띄워 그 라우트를 연다)에 맡긴다.
5. 완료 기준
- 생성 명령으로 시작했고, 템플릿 소유 파일을 생성 명령 밖에서 고치지 않았다(고쳤으면 큼으로 올려 결정을 받았다).
- 동작마다 테스트가 있고 RED → GREEN을 봤다.
- 초기 JS 기록과 기능 모양 기록이 빌드와 맞는다(
test:unit안의 대조). scripts/verify.sh merge가 통과했다(FE-GATE-013은 operate.md 4.1절대로 적었다). 라우트 로딩을 바꿨으면test:performance(FE-GATE-026)도 돌렸다.- 기능을 지운 사본이 통과한다(FE-GATE-020 안의 드릴).
- 다운스트림에 보이는 변경(공개 포트, 생성 명령 출력)이 있으면
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절 형식으로 묻는다.
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로 돌린다.- 매뉴얼 예시 기능 이름을 그대로 써서 템플릿 테스트의 글자와 부딪친다. 제품 이름을 쓴다.