Lab 02: 구조로 재구축 (Spec·Steering)

목표

Lab 01의 지적이 왜 나왔는지 이해하고, 같은 앱을 규칙(Steering)과 명세(Spec)를 먼저 정한 뒤 다시 만듭니다. 그리고 리뷰를 다시 돌려 지적이 얼마나 줄었는지를 숫자로 확인합니다.

왜 구조가 필요한가 (개념)

지적은 여러분의 실력 문제가 아닙니다

Lab 01에서 나온 지적들을 성격별로 묶으면 대개 보안 · 에러 처리 · 엣지케이스 · 유지보수 · 접근성 다섯 갈래입니다. 중요한 사실이 하나 있습니다. 같은 방식으로 만들면 누가 해도 같은 지적을 받습니다. 원인은 사람이 아니라 방식에 있습니다.

AI는 왜 “그럴듯하게” 틀리는가

AI(대규모 언어 모델)는 다음에 올 말을 확률로 고르는 아주 강력한 자동완성입니다. “이게 맞는가”가 아니라 “이게 그럴듯한가”를 기준으로 단어를 이어 붙입니다. 그래서 두 가지 일이 벌어집니다.

그럴듯하지만 틀린 것이 섞입니다. 학습한 코드 중에는 짧고 흔한 예제(보안·예외 처리를 생략한)가 압도적으로 많습니다. AI는 “가장 흔한 = 가장 그럴듯한” 패턴을 따라가므로, 그 생략까지 그대로 재현합니다.
매번 결과가 달라집니다. 확률에서 하나를 “뽑는” 방식이라, 같은 요청도 실행할 때마다 조금씩 다른 코드가 나옵니다.

그리고 바이브 코딩은 “코드를 읽지 않는” 방식이라, 이 그럴듯한 오류를 걸러 줄 사람이 과정에 없었습니다. 그래서 지적이 쌓인 것입니다.

처방: 지적을 “규칙 한 줄”로 되돌리기

지적 하나하나는 사실 미리 규칙 한 줄만 정해뒀다면 안 생겼을 것들입니다.

리뷰가 잡은 지적	이 규칙 한 줄이 있었다면
화면 출력에서 생기는 보안 위험(XSS)	“화면 출력은 `textContent`만 쓴다”
저장소 접근 중 앱이 멈춤	”저장소 접근은 `try/catch`로 감싼다”
한 파일에 코드가 다 뒤엉킴	”3개 파일로 나누고 데이터는 배열로 분리”
설정값이 곳곳에 흩어짐	”설정값은 파일 상단 상수로 모은다”

이 “규칙 한 줄”들을 담는 자리가 Kiro에 두 종류 있습니다.

구분	무엇인가	사람의 역할
Steering	”항상 지킬 규칙”. 한 번 적어두면 모든 요청에 자동 반영	규칙을 정한다
Spec(명세)	“이번에 만들 것의 정의”. 요구사항 → 설계 → 작업 순서 문서	직접 쓰지 않고 검토한다

핵심 — 구조(Steering·Spec)는 속도를 늦추는 비용이 아니라, 같은 실수를 다시 안 하게 만드는 지렛대입니다.

전체 흐름

Step 1

규칙(Steering) 만들기

항상 지킬 규칙 고정

Step 2

명세(Spec) 만들기

요구사항 검토

Step 3

명세대로 구현

v2 앱 완성

Step 4

재리뷰 → 지적 수 비교

v1 vs v2

Step 1: 규칙(Steering) 만들기

아래 프롬프트를 Kiro에 넣습니다. 실행 후 .kiro/steering/ 폴더에 규칙 파일이 실제로 생겼는지 확인하세요.

이 프로젝트의 Steering 규칙 파일을 .kiro/steering/ 에 만들어줘.
- tech: 바닐라 HTML/CSS/JS만. 외부 라이브러리·CDN 금지.
- structure: index.html / style.css / app.js 3개 파일. 퀴즈 데이터는 app.js 상단에 배열로 분리.
- quality: 화면 출력은 innerHTML 금지 textContent 사용. localStorage 접근은 try-catch. 설정값은 상단 상수. 전역 변수 금지 — 코드는 IIFE나 모듈로 감싼다.
- a11y: 점수·문제 영역에 aria-live="polite". 답 선택 후 "다음" 버튼으로 포커스 이동. 정오답은 색상만 쓰지 말고 ✓/✗ 아이콘 병기.
- 제약: 로그인·서버·외부 API·광고 없음.

Kiro에서 생성된 .kiro/steering/project-rules.md — Tech Stack·File Structure·Code Quality·Accessibility·Constraints 규칙 — `.kiro/steering/project-rules.md`에 규칙이 파일로 저장됩니다. 이 파일이 이후 모든 생성 요청에 자동 반영됩니다.

왜 규칙부터? Steering은 이후 모든 생성 요청에 자동으로 반영됩니다. 규칙을 먼저 심어야 v2가 그 규칙 위에서 만들어집니다.

🎯 체크포인트

.kiro/steering/에 규칙 파일이 생겼다

Step 2: 명세(Spec) 만들기

아직 코드는 만들지 않게 합니다. 명세가 나오면 직접 읽어 보고, 빠진 요구사항이 있으면 한 가지를 찾아 추가하세요.

이 퀴즈 앱을 위 규칙에 맞게 처음부터 다시 만들 거야.
먼저 requirements / design / tasks 명세를 작성해줘. 코드는 아직 만들지 마.

Kiro가 .kiro/specs/에 생성한 requirements.md — 개요, 기능 요구사항(FR-1 퀴즈 풀기, FR-2 점수·진행도, FR-3 결과 화면, FR-4 오답 노트) — `.kiro/specs/`에 `requirements.md`·`design.md`·`tasks.md` 세 문서가 만들어집니다. 코드보다 먼저 이 명세를 사람이 검토합니다.

힌트 — “문제·보기 순서 섞기”, “틀린 문제를 다시 풀 때 오답 노트 갱신” 같은 요구사항이 자주 빠집니다. 하나 찾아 추가해 보세요. 이게 바로 “직접 쓰지 않고 검토한다”의 실제입니다.

🎯 체크포인트

requirements / design / tasks 명세가 생성됐다
명세를 읽고 빠진 요구사항을 한 가지 추가했다

Step 3: 명세대로 구현

명세가 확정되면 구현을 지시합니다. 먼저 입력창에서 #folder 를 골라 2.vibe-coded 폴더를 선택한 뒤, 아래 프롬프트를 보냅니다. 이렇게 대상 폴더를 지정하면 명세대로 만든 결과가 그 폴더 안에 정리됩니다. 완료 후 브라우저로 열어 동작을 확인하세요.

명세대로 구현해줘.

예상 결과: 2.vibe-coded 폴더가 index.html / style.css / app.js 3개 파일로 나뉘고, 퀴즈 데이터가 배열로 분리된 v2 앱이 만들어집니다.

2.vibe-coded 폴더에 3개 파일로 재구축된 v2 앱 실행 화면과, Kiro가 규칙 충족 여부를 스스로 점검한 검증 결과 표(3파일 구조·innerHTML 0건·IIFE 등 전부 통과) — 규칙·명세대로 재구축된 v2 앱. `2.vibe-coded`가 `index.html`·`app.js`·`style.css`로 분리되고, Kiro가 규칙 충족 여부를 표로 스스로 점검합니다.

🎯 체크포인트

명세대로 v2 앱을 구현하고 브라우저에서 동작을 확인했다

Step 4: 재리뷰하고 비교하기

새로 만든 앱(v2)에 /review를 다시 돌립니다.

/review

Lab 01의 지적 개수(v1)와 방금 나온 지적 개수(v2)를 나란히 적어 봅니다.

버전	만든 방식	`/review` 지적 수
v1	바이브 코딩 (Lab 01)	(본인 값 기록)
v2	Steering·Spec (이번 Lab)	(본인 값 기록)

이 숫자 차이가 오늘의 결론입니다.

재리뷰 결과 1 — 프로젝트 규칙 준수 표가 전부 PASS, 코드 품질 이슈는 경미한 3건뿐 — 구조로 재구축한 v2를 `/review`한 결과 — 규칙 위반 0건, 남은 것은 경미한 코드 품질 이슈뿐입니다. Lab 01의 8~12개 지적과 비교됩니다.

재리뷰 결과 2 — 접근성·기능 완성도 전부 통과, 총평 '명세를 충실히 따른 깔끔한 구현, 규칙 위반 없음' — 구조로 재구축한 v2를 `/review`한 결과 — 규칙 위반 0건, 남은 것은 경미한 코드 품질 이슈뿐입니다. Lab 01의 8~12개 지적과 비교됩니다.

왜? 여기서 사람의 역할이 바뀝니다. 코드를 타이핑하는 사람에서, 규칙을 정하고 결과를 검증하는 사람으로. 앱이 커질수록 이 방식의 이득은 기하급수적으로 커집니다.

🎯 체크포인트

v2에 /review를 다시 돌렸다
v1 대비 v2의 지적이 줄어든 것을 표로 확인했다

핵심 확인 포인트

#	확인 항목	상태
1	지적이 왜 나오는지(확률 생성·구조의 필요)를 이해했다	☐
2	`.kiro/steering/`에 규칙 파일을 만들었다	☐
3	Spec(requirements/design/tasks)을 만들고 검토했다	☐
4	명세대로 v2 앱을 구현했다	☐
5	v1 대비 v2의 지적이 줄어든 것을 확인했다	☐

교육 포인트 정리

이 Lab에서 배운 것

확률 생성: AI는 “맞는가”가 아니라 “그럴듯한가”로 답한다
Steering: 항상 지킬 규칙을 한 번 정해 모든 요청에 자동 반영
Spec: 요구사항→설계→작업을 사람이 검토하는 명세
비교로 증명: v1과 v2의 지적 수 차이가 구조의 효과다

아직 안 된 것 (다음 Lab에서 해결)

❌ 코드는 구조를 갖췄지만, 문항 내용의 사실 여부는 아직 검증 안 됨
❌ 검증을 매번 손으로 해야 함

트러블슈팅

규칙 파일이 안 생김

→ 방금 규칙을 .kiro/steering/ 에 파일로 저장해줘라고 다시 지시합니다.

명세만 만들고 구현을 안 함

→ Step 3 프롬프트(명세대로 구현해줘)를 명확히 다시 입력합니다.

v2 지적이 안 줄었음

→ 규칙이 느슨했던 것입니다. 위 표의 규칙 한 줄(예: textContent)을 Steering에 더 추가하고 다시 만들어 봅니다. 이 과정 자체가 좋은 배움입니다.

재구축이 잘 안 되면

→ quiz-app/3.spec-driven 폴더에 규칙·명세대로 완성된 정답 예시가 있습니다. 이 폴더를 Kiro로 열어 이어가거나, 내 결과와 비교하며 참고하세요. (Steering·Spec 원본은 quiz-app/kiro-settings/에 있습니다.)

참고 자료

Kiro 공식 사이트 — Specs·Steering 기능 문서
Spec-driven development (Kiro Docs) — 요구사항·설계·작업 명세 흐름