서론
안녕하세요.
퐁핑퐁(pongpingpong)은 탁구장 레슨 운영을 앱 하나로 모으는 프로젝트입니다.
탁구장의 레슨 운영은 보통 여러 곳에 흩어져 있습니다.
일정은 전화와 카카오톡으로 잡고, 출결과 남은 횟수는 Excel에 따로 적고,
결석한 수업의 보강은 다시 메시지를 주고받으며 조율합니다. 월말 정산은 그 기록들을 모아 계산합니다.
기록이 나뉘어 있으니 “이 수강생이 이번 달 보강을 몇 번 썼는지” 같은 질문 하나에도 매번 여러 곳을 확인해야 합니다.
그래서 레슨 일정부터 출결, 보강, 정산까지를 한 곳에서 처리하고,
관장 · 강사 · 수강생 세 역할이 각자 필요한 화면만 보도록 만들어 보기로 했습니다.
Pongpingpong Repository
https://github.com/ryudain05/pongpingpong
GitHub - ryudain05/pongpingpong
Contribute to ryudain05/pongpingpong development by creating an account on GitHub.
github.com
만들기 시작하고 먼저 부딪힌 것은 코드가 아니라 규칙이었습니다.
보강은 월 몇 회까지 허용할지, 당일 취소는 어떻게 처리할지, 정산율은 어느 금액에 곱할지.
역할이 셋이라 같은 규칙도 화면마다 다르게 보여야 했고, 한 번 정한 규칙이 앱과 서버 여러 곳에 동시에 걸렸습니다.
화면을 그리기 전에 규칙부터 어딘가에 적어 두고 시작해야 하는 프로젝트였습니다.
이 프로젝트는 Kiro CLI로 작업했습니다.
퐁핑퐁 저장소에서 Kiro CLI를 처음 실행했을 때 눈에 띈 것은 에이전트가 써 주는 코드가 아니라,
프로젝트 안에 생기는 .kiro 디렉터리였습니다.
기능을 구현하기 전에 어떤 문서를 만들고,
그 문서를 어디에 두고,
어떤 순서로 다음 단계에 넘어갈지가 도구 안에 이미 정해져 있었습니다.
에이전트와 정한 규칙을 대화 안에만 두면 세션이 끝날 때 같이 사라집니다.
어제 정한 보강 정책을 오늘 다시 설명하게 되는 식입니다.
앞에서 말한 “규칙을 적어 두고 시작해야 한다”는 문제를 도구가 먼저 전제하고 있다는 점이 흥미로웠습니다.
그래서 이 글에서는 퐁핑퐁을 만들면서 Kiro가 기본으로 제공하는 개발 흐름을 어떻게 사용했는지,
그리고 그 과정에서 느낀 점을 정리했습니다.
모델이 코드를 얼마나 잘 쓰는지가 아니라, 개발 프로세스가 파일과 명령으로 고정되어 있다는 점에 초점을 맞췄습니다.
Kiro의 개발 흐름은 Spec에서 시작합니다
요구사항을 먼저 정리하고 구현으로 넘어가는 방식,
이른바 Spec-driven development를 Kiro는 이 흐름을 별도 설치나 설정 없이 기본 workflow로 제공합니다.
Spec 흐름은 다음 네 단계로 구성됩니다.
요구사항(requirements)
→ 설계(design)
→ 작업 목록(tasks)
→ 구현 및 검증(execution)
각 단계의 산출물은 기능별 디렉터리에 정해진 이름으로 남습니다.
.kiro/specs/makeup-confirm/
├── requirements.md # 사용자 스토리와 수용 기준
├── design.md # 기술 설계
└── tasks.md # 실행 단위 작업 목록
작업을 시작하는 명령, 단계별 산출물의 이름, 다음 단계로 넘어가는 방법이 모두 정해져 있습니다.
사람마다 프롬프트를 다르게 작성해도 프로젝트의 기능 계획이 일정한 형태로 남습니다.
버그 수정에는 별도의 Spec 형식이 있습니다.
이 경우 요구사항 대신 현재 동작, 기대 동작, 바뀌면 안 되는 동작을 기록합니다.
버그를 정리할 때 마지막 항목을 빠뜨리는 일이 많은데, 그 칸이 양식에 미리 포함되어 있다는 점이 유용했습니다.
tasks.md는 계획 문서이면서 실행 상태입니다
Spec에서 가장 인상적이었던 부분입니다.
tasks.md는 작성하고 끝나는 계획서가 아닙니다.
작업이 진행되면 각 항목의 상태가 진행 중 또는 완료로 갱신되고, 작업 사이의 의존 관계도 함께 관리됩니다.
계획 문서와 실행 큐가 같은 파일에 들어 있습니다.
이 구조에서 얻은 이점은 다음과 같습니다.
- 대화 세션이 끊겨도 진행 상태를 파일에서 확인할 수 있습니다.
- 다른 작업을 하다 돌아와도 컨텍스트를 다시 설명할 필요가 없습니다.
- 진행 기록이 커밋에 함께 남으므로, 기능의 구현 의도를 코드보다 먼저 확인할 수 있습니다.
퐁핑퐁처럼 매일 퇴근 후에 조금씩 이어 붙이는 프로젝트에서는 이 차이가 특히 크게 느껴졌습니다.
어제 어디까지 했는지를 대화 기록이 아니라 파일에서 확인할 수 있다는 점이 좋았습니다.
요구사항 분석이 별도의 명령으로 존재합니다
Kiro CLI에는 요구사항의 모호함이나 빠진 완료 조건을 점검하는 /spec analyze_requirements 명령이 있습니다.
구현을 시작하기 전에 요구사항을 검토하는 단계가 workflow 안에 명시적으로 포함되어 있습니다.
퐁핑퐁에서 가장 까다로웠던 기능은 보강 슬롯 확정이었습니다.
요구사항을 정리하는 단계에서 다음과 같은 질문을 먼저 확인하게 됩니다.
- 같은 슬롯을 두 명이 동시에 확정하면 어떻게 처리합니까?
- 보강 잔여 횟수가 없을 때 응답은 무엇입니까?
- 확정에 실패한 사용자는 어떤 화면으로 돌아갑니까?
- 강사가 확정된 보강을 취소하면 보강권은 복구됩니까?
이 질문들을 정리하면서 슬롯 선택과 확정을 분리하고, 확정 시점에 서버가 다시 검증하도록 설계했습니다.
같은 슬롯을 두 명이 동시에 신청하면 DB 행 잠금으로 한 명만 성공하고 나머지는 409로 다른 시간을 안내받습니다.
보강 잔여가 없으면 400입니다. 강사가 확정된 보강을 취소하면 수강생의 보강권이 자동으로 복구되고 알림이 전송됩니다.
구현을 먼저 시작했다면 동시성 문제를 나중에 발견하고 API 응답 형태부터 다시 잡아야 했을 내용입니다.
요구사항 검토를 생각날 때 하는 일이 아니라, 다음 단계로 넘어가기 전에 반드시 거치는 자리로 만들어 두었다는 점이 좋았습니다.
Steering은 필요한 순간에만 켜집니다
Steering은 프로젝트 지침을 Markdown 파일로 관리하는 기능입니다.
여기서 중요한 부분은 각 문서가 언제 읽힐지를 파일이 스스로 선언한다는 점입니다.
파일 맨 위의 front matter에 포함 방식을 적습니다.
---
inclusion: always
---
포함 방식은 네 가지입니다.
| 모드 | 언제 포함되는가 | 적합한 문서 |
| always | 항상 포함 (기본값) | 코딩 컨벤션, 보안 정책 |
| fileMatch | 패턴에 맞는 파일을 다룰 때만 | 컴포넌트 규칙, API 규칙 |
| manual | 대화에서 #파일이름 으로 호출 | 릴리스 절차, 트러블슈팅 |
| auto | 요청이 description과 맞으면 자동 | 도메인별 가이드 |
Cursor의 .cursor/rules도 alwaysApply, globs, description 조합으로 거의 같은 네 가지 동작을 제공합니다.
지침을 조건부로 포함한다는 발상은 이미 여러 도구가 공유하고 있고, Kiro에서도 이를 Steering이라는 이름으로 사용할 수 있습니다.
조건부 포함은 다음과 같이 작성합니다.
---
inclusion: fileMatch
fileMatchPattern: ["**/*.dart"]
---
지침이 많아질수록 이 차이가 커집니다.
하나의 큰 파일에 모든 규칙을 담으면 Flutter 화면을 수정하는 중에도 정산 규칙과 DB 마이그레이션 절차를 함께 읽게 됩니다. Steering은 규칙을 파일 단위로 나누고, 필요한 순간에만 포함되도록 선언해 둘 수 있습니다.
또한 워크스페이스의 실제 파일을 지침 안에서 참조할 수 있습니다.
#[[file:docs/architecture.md]]
규칙을 문서에 복사해 두는 대신 원본을 가리키므로, 설계가 바뀌어도 지침이 낡지 않습니다.
지침 문서가 코드와 어긋나는 문제를 구조적으로 줄여 주는 방식이라 인상적이었습니다.
문서 안에서 다른 파일을 참조하는 기능 자체는 Claude Code의 CLAUDE.md 등에도 있지만,
Steering에서는 포함 조건과 함께 쓸 수 있다는 점이 편했습니다.
퐁핑퐁의 Steering 구성은 다음과 같습니다.
.kiro/
├── settings/mcp.json
└── steering/
├── product.md # 제품 목표
├── business-rules.md # 보강 · 정산 · 출결 규칙
├── development.md # 개발 순서
├── structure.md # 코드 구조
├── tech.md # 기술 스택
└── user-flows.md # 역할별 사용자 흐름
product.md, tech.md, structure.md는 Kiro가 기본으로 생성하는 세 파일이고,
business-rules.md와 user-flows.md는 퐁핑퐁에 맞게 추가했습니다.
특히 보강 횟수 제한이나 정산율처럼 화면 여러 곳에 영향을 주는 규칙을 한 파일에 모아 두니,
같은 규칙을 매번 다시 설명하지 않아도 되는 점이 편했습니다.
Agent Hooks는 Spec 작업 실행에 연결됩니다
Kiro에는 특정 이벤트가 발생했을 때 셸 명령이나 에이전트 프롬프트를 자동으로 실행하는 Agent Hooks가 있습니다.
걸 수 있는 이벤트는 다음과 같습니다.
- 파일 생성, 저장, 삭제
- 세션 시작, 에이전트 응답 완료
- 도구 실행 전후
- Spec 작업(task) 실행 전후
설정은 .kiro/hooks/ 아래 JSON으로 두거나, 대화로 훅 생성을 요청할 수 있습니다.
앞의 세 항목은 다른 도구의 훅에서도 볼 수 있는 이벤트입니다.
제가 찾아본 범위에서 Kiro에만 있었던 것은 마지막 항목입니다.
앞에서 tasks.md가 실행 큐라고 했는데, 그 큐의 각 단계에 검증을 끼워 넣을 수 있다는 뜻입니다.
작업이 하나 끝날 때마다 린트와 타입 체크를 실행하거나, 위험한 작업 전에 선행 조건을 확인하고 중단시킬 수 있습니다.
계획, 실행, 검증이 같은 구조 안에서 연결됩니다.
다만 퐁핑퐁에서는 훅까지 사용하지 않았습니다.
구조상 Spec과 가장 잘 맞는 기능으로 보여 다음에 적용해 볼 예정입니다.
MCP로 Figma 시안을 연결했습니다
Kiro CLI에서는 .kiro/settings/mcp.json에 사용할 서버를 적어 두면 됩니다.
{
"mcpServers": {
"figma": {
"command": "npx",
"args": ["-y", "figma-developer-mcp", "--stdio"]
}
}
}
퐁핑퐁에서는 Figma MCP를 붙였습니다. 디자인 시안을 읽어 docs/figma/에 분석을 남기고, 그 결과를 프론트엔드 디자인 토큰으로 옮기는 데 사용했습니다.
Kiro를 선택할 수 있는 경우
이번 사용 경험을 기준으로 하면 Kiro는 다음과 같은 경우에 잘 맞는다고 생각합니다.
첫째, 기능을 구현하기 전에 요구사항과 설계를 문서로 검토하고 싶은 경우입니다. 기능이 작을 때는 바로 구현하는 편이 빠를 수 있지만, 보강 확정처럼 예외 상황이 많은 기능이라면 Spec 산출물이 도움이 됩니다.
둘째, 기능 계획의 형식을 팀 단위로 통일하고 싶은 경우입니다. 모든 개발자가 요구사항, 설계, 작업 목록을 비슷한 형태로 남기도록 만들 수 있습니다.
셋째, 한 번에 끝나지 않고 여러 세션에 걸쳐 진행되는 작업입니다. 작업 목록을 기준으로 구현을 실행하고, 필요할 때 중간에 방향을 조정하는 흐름이 잘 맞습니다.
반대로 파일 한두 개를 고치는 단순한 변경이라면 Spec을 거치지 않는 편이 빠릅니다.
모든 작업에 Spec을 적용하면 오히려 문서 작성 비용이 구현 비용을 넘어설 수 있습니다.
사용하면서 알게 된 한계
Spec workflow가 있다고 해서 요구사항이 자동으로 정확해지는 것은 아닙니다.
요구사항이 모호하면 모호한 requirements.md와 모호한 tasks.md가 만들어집니다.
보강을 월 몇 회까지 허용할지, 당일 취소를 어떻게 처리할지 같은 정책은 여전히 제가 정해야 했습니다.
Kiro가 하는 일은 그 결정을 대신해 주는 것이 아니라, 결정하지 않고 넘어가기 어렵게 만드는 것에 가깝습니다.
마무리
Kiro의 장점은 AI가 더 많은 일을 대신한다는 데 있지 않았습니다.
기능을 구현하기 전에 어떤 문서와 단계를 거칠지 정해져 있고,
그 결과가 프로젝트 파일로 남고, 훅이 그 흐름에 붙는다는 점.
이 중 앞의 두 가지는 다른 도구로도 만들 수 있습니다.
다만 Kiro는 그것을 직접 조립하지 않아도 기본값으로 제공하고,
계획이 대화가 아니라 저장소에 남는 파일이며, 훅이 그 파일의 작업 단위에 걸립니다.
정리하면 새로운 기능이라기보다 개발 프로세스를 기본값으로 고정해 둔다는 쪽이 Kiro의 성격에 가까웠습니다.
퐁핑퐁에서는 그 가능성을 Steering과 아키텍처 문서 중심으로 확인했습니다.
다음에는 실제 Spec workflow를 적용해 요구사항 분석부터 작업 실행까지 기록해 보면서,
Kiro가 개발 프로세스에 어느 정도의 실질적인 차이를 만드는지 더 구체적으로 정리해 보려고 합니다.
참고 링크
'개발' 카테고리의 다른 글
| 모놀리식 아키텍처와 MSA(Micro Service Architecture) (1) | 2024.03.08 |
|---|
