05. 복잡한 작업에 Specs 활용

단순한 즉흥 수정으로는 감당하기 어려운 복합 기능을 다룰 때, Kiro의 Spec 기능으로 요구사항·설계·작업 단계를 체계적으로 풀어가는 방법을 다룹니다.

다루는 문제

지금까지의 모듈에서는 홈페이지 개선, 물리 버그 수정, 상호작용 버그 처리, DRY 리팩터처럼 비교적 작은 변경을 살펴봤습니다. 이번에는 범위가 넓은 새 기능, 즉 로그인 페이지에 빠져 있는 Forgot Password 링크를 만들어 봅니다. 인증은 Amazon Cognito를 사용하고 있는데, 비밀번호 재설정 메일을 보내려면 사용자의 이메일이 먼저 검증되어 있어야 합니다. 따라서 작업은 두 갈래로 갈라집니다.

여러 레이어가 얽혀 있고 의존 관계도 있어, 한 번의 프롬프트로 끝낼 작업이 아닙니다. 이럴 때 Spec이 진가를 발휘합니다.

Spec 만들기 절차

  1. Kiro의 채팅 패널에서 Spec 모드를 열고 다음과 같이 요청합니다.

    I need a specification for email verification and password reset

    Kiro가 프로젝트 구조를 훑어본 뒤 Spec 초안을 만들기 시작합니다.

  2. 요구사항(requirements) 검토. Kiro는 짧은 요청을 사용자 스토리 기반의 상세 요구사항으로 확장합니다. 이 과정에서 미처 떠올리지 못한 엣지 케이스가 드러나는 경우도 많습니다. 내용이 마음에 들면 채팅에 LGTM처럼 짧게 승인 의사를 적고, 수정이 필요하면 어떤 방향으로 다시 써달라고 구체적으로 알려줍니다.

    Kiro가 생성한 requirements 문서
    Spec의 첫 단계로 생성된 requirements 문서

  3. 설계(design) 검토. Kiro가 기존 코드와 요구사항을 비교하면서 새 기능을 어떻게 끼워 넣을지 설계안을 작성합니다.

    Kiro가 생성한 design 문서
    요구사항을 바탕으로 만들어진 design 문서
    설계 문서 우측 상단의 Preview 버튼을 누르면 마크다운이 렌더링된 화면이 열려 플로우 다이어그램이 제대로 보입니다.
    설계 문서에 포함된 코드 조각은 API의 형태를 상상한 의사코드(pseudocode)로 보아야 합니다. 실제 구현은 이와 달라질 수 있습니다. 만족스러우면 LGTM, 그렇지 않다면 구체적인 피드백을 남기세요.

  4. 작업 목록(tasks) 검토. Kiro는 요구사항과 설계를 합쳐 실제 실행 가능한 단위 작업으로 쪼갭니다. 이것이 새 기능까지 가는 단계별 경로가 됩니다.

    Kiro가 생성한 tasks 문서
    실행 단위로 나뉜 tasks 문서
    기본 작업 순서가 팀의 스타일과 안 맞을 수 있습니다. 예를 들어 TDD를 선호한다면 테스트가 마지막이 아니라 처음에 와야겠죠. 이런 습관을 Kiro에게 학습시키려면 steering 파일을 활용하세요. .kiro/steering/specs.md를 만들고 “항상 코드보다 테스트를 먼저 작성하라”와 같은 지시를 적어두면 다음 Spec부터 반영됩니다.

  5. 작업 실행. 각 작업 위에 표시되는 Start Task 링크를 클릭하면 Kiro가 그 작업을 시작합니다.

    Start Task 링크로 작업을 진행하는 모습
    Start Task로 작업을 하나씩 진행
    작업이 “Task completed”로 표시되더라도 그대로 끝난 것이 아닙니다. 결과 코드를 검토하고, 직접 실행해 보고, 필요한 만큼 다듬는 과정은 여전히 사람의 몫입니다.

  6. Spec을 기록으로 남기기. 생성된 Spec은 .kiro/specs에 저장되며, 이는 코드와 함께 저장소에 커밋하기 위한 위치입니다. 시간이 흐르면 이 폴더가 곧 “왜 이렇게 만들었는가”를 설명하는 설계 의도의 아카이브가 됩니다. 나중에 같은 기능을 손볼 때 동료 개발자에게도, Kiro 자신에게도 훌륭한 참고 자료가 됩니다.

이번 모듈에서 배운 것