결정 기록

하네스를 만들며 내린 큰 결정과 근거입니다. 새 프로젝트에서 같은 고민을 다시 하지 않도록, 그리고 상황이 바뀌면 다시 열 수 있도록 「무엇을 보고 정했는지」를 남깁니다. 형식은 결정 기록 템플릿을 따릅니다.

D1. Figma 는 정본이 아니라 검수 캔버스 → 이후 처리 흐름에서 제거

• 배경: 처음 계획은 코드 → Figma → 사람 검토 → 고친 것만 되읽어 코드로.
• 본 것: 같은 화면 둘을 Figma 경유안(A)과 「요청 + 문서」안(B)으로 비교. 규칙 위반(B 1 · 0 / A 0 · 0)과 부품 재사용(둘 다 4/5, 16/16)은 같았지만, 요청과 어긋난 곳은 B 0~1건, A 4~5건. Figma 는 동작 · 미정 사항 · 선택지 목록을 실어 나르지 못한다.
• 결정: 정본은 코드와 요청서. 이후 5장짜리 요청이 코드 완성 뒤 Figma 에서만 1시간 넘게 걸려 처리 흐름에서 Figma 를 뺐다.
• 다시 열 조건: 디자이너가 Figma 에서 직접 수정하는 비중이 커질 때.

D2. 모델은 화면만, 나머지는 스크립트

• 본 것: 이틀 동안 처리 9번 실패, 화면 생성 실패 0번. 실패는 모두 배포 대기 · 머지 타임아웃 등 모델이 운전하던 주변.
• 결정: 모델과 스크립트 사이의 약속을 plan.json 하나로. git · gh 쓰기 권한은 모델에게 주지 않는다.

D3. 러너는 GitHub job 이 아니라 launchd

• 본 것: self-hosted 러너 연결이 15~25분마다 끊겨 job 이 버려지고 에이전트가 함께 죽었다(같은 요청 4연속).
• 결정: launchd 감시자 + 신뢰 사본. GitHub 워크플로는 수동 예비로만 남긴다.

D4. Storybook 대신 Studio + llms.txt

• 본 것: Studio 에 이미 Playground 와 문서가 있었고, Storybook MCP 는 실행 중인 서버에서만 동작했다.
• 결정: Storybook 을 만들지 않고 AI 용 색인 llms.txt 한 장으로 대신.

D5. 디자인 시스템은 레지스트리 대신 복사(vendoring)

• 본 것: 패키지가 TS 원본을 export, 하네스 저장소가 비공개, 인프라 미정.
• 결정: lock(sha256)과 손 편집 검사를 붙인 복사. 레지스트리는 인증 구조가 정해지면.

D6. 브랜치 보호 대신 권한 규칙과 산출물 검사

• 본 것: 무료 플랜 비공개 저장소는 브랜치 보호 불가.
• 결정: 저장소의 deny · ask 규칙, 화면 자리 밖 변경 차단, 결정 판독 규칙. 사람의 손 머지는 막지 못하므로 감지 · 경고.

D7. 운영 배포는 사람이 발행한 태그로만

• 본 것: main 머지가 곧 배포이던 시절, 팀 안에 「태그가 배포를 일으킨다」는 오해가 있었다. 머지와 배포를 나눌 필요.
• 결정: main 머지는 쌓이고, GitHub 릴리스 발행이 배포. 에이전트는 릴리스를 만들 수 없다.

D8. 리뷰는 다른 모델로, 판단은 사람이

• 결정: 개발은 Claude, 릴리스 리뷰는 Codex(GPT), 그 지적의 타당성 검증은 다시 개발 세션의 Claude, 머지 결정은 사람. GPT 수정은 정해진 경로 밖에서만, 네트워크 없는 샌드박스에서.

D9. 뜻이 갈리면 묻지 말고 만들어서 보여 준다

• 본 것: 질문은 사람을 기다리게 하고, 기다리는 동안 맥락이 식는다.
• 결정: 가장 그럴듯한 해석으로 만들고, 버린 갈래를 needsDecision 첫 줄에 남긴다. 개선 버튼으로 바로 고칠 수 있다.