AI가 작성한 Pull Request(PR)도 스스로 설명할 수 있게, Spec Ramo 개발

AI가 작성한 PR을, 스스로 설명할 수 있나요

"여기는 왜 이렇게 했나요?"

리뷰에서 이런 질문을 받았는데, 제 자신의 PR임에도 즉답하지 못한 경우가 많았습니다.

코드를 작성한 것은 AI였고, 저의 이해는 얕은 상태였습니다.

현장은 거대한 모놀리스(monolith) 프로젝트입니다.

구현 속도는 빨라졌지만, 개발 전체는 오히려 느려지고 품질도 낮은 상태를 유지했습니다.

건강까지 해져서, 아무래도 안 되겠다고 느꼈습니다.

빨리 만들 수 있게 된 만큼, **'자신이 이해하지 못한 채 진행되는 것'**이 병목 현상(bottleneck)이 되고 있었습니다.

그래서 Spec 기반 개발 절차를 저 나름대로 정리하여, Spec Ramo (スペックラモ)라는 플러그인을 만들었습니다!

Spec Ramo란 무엇인가

이 이름은 'Spec'과 산스크리트어의 krama(크라마)='순서・단계'를 합친 조어입니다.

상정하는 현장은 다음과 같습니다.

아키텍처가 복잡한 거대한 모놀리스나 마이크로서비스와 같이 -
운영 중인 서비스에서, 기존 코드의 규약이나 아키텍처에 맞출 필요가 있을 때
서비스를 멈추지 않으면서,
기존 기능에 영향을 주지 않도록 배포하고 싶을 때

겪고 있던 어려움과 그 대응 방안은 다음과 같습니다.

어려웠던 점	Spec Ramo를 통한 대응
PR이 커서 읽는 데 시간이 걸림	1 Phase = 1 PR로 하고, 변경 상한을 400행(테스트 제외)으로 스크립트 검사 (일반적으로 리뷰하기 쉬운 행 수를 기준으로 함)
사양에서 정하지 않은 부분에 구현이나 리뷰에서 발견함	구현 전에 Design Doc으로, 보이는 움직임을 수용 조건 표로 고정함
구현자보다 먼저 리뷰어가 문제점을 발견함	구현 전후에 `/specramo:explain`으로 AI에게 설명하게 하여 코드 이해도를 높이고, 문제점을 사전에 찾음
규약이나 명명법 지적으로 인해 리뷰 왕복이 증가함	프로젝트의 규약 관점에서 AI가 리뷰하고, 규약이나 명명법 지적은 리뷰 요청 전에 해결함

일반적인 Spec 기반 개발과의 차이점

Spec 기반 개발은 코드보다 사양을 먼저 작성하고, 사양을 기준으로 구현하는 방법입니다.

대표적인 예로는 GitHub의 Spec Kit과 AWS의 Kiro가 있습니다.

공정	Spec Kit	Kiro	Spec Ramo
요구사항 결정	specify	requirements	`/specramo:prd` ・`/specramo:design`
설계하기	plan	design	`/specramo:design` ・`/specramo:phase-design`
작업으로 나누기	tasks	tasks	`/specramo:plan`
구현하기	implement	태스크 실행	`/specramo:implement`
차이 확인하기	converge	없음	`/specramo:review`
이해도 확인하기	없음	없음	`/specramo:explain`

사양과 구현이 일치하는지 확인하는 메커니즘은 기존 방법에도 있습니다.

차이점은 마지막 줄, 구현자의 이해도를 확인하는 공정입니다.

사용법: PRD부터 PR까지

⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.

순서	할 일	명령어	상세
1	준비	`/specramo:init`	설정 파일과 결과물 저장 공간을 만듭니다
2	요구사항	`/specramo:prd`	대화로 요구사항을 수집하여 PRD를 만듭니다
3	설계	`/specramo:design`	인수 조건(Acceptance Criteria) 표로 동작을 고정한 Design Doc을 만듭니다
4	계획	`/specramo:plan`	Design Doc을 1 Phase = 1 PR의 작업 계획서로 나눕니다
5	상세 설계	`/specramo:phase-design`	Phase 1개의 구현 방법을 기존 코드를 조사한 후 결정합니다
6	설계 설명	`/specramo:explain`	구현 전에 Phase의 설계를 설명합니다
7	구현	`/specramo:implement`	Phase를 1개 구현하고, 완료 조건을 명령어로 확인합니다
8	리뷰	`/specramo:review`	차이점을 4가지 관점에서 병렬로 리뷰합니다
9	코드 설명	`/specramo:explain`	PR을 draft로 만든 후, 차이점 코드의 설명과 자신의 인식을 맞춰봅니다
-	진행 상황	`/specramo:status`	Phase의 진행 상황과 이어서 실행할 명령어를 표시합니다

1~~4는 처음에 1회만, 5~~9는 Phase별로 반복합니다.

표에 있는 문서의 의미

PRD: 무엇을 위해 무엇을 만들었는지 정리한 요구사항 문서
Design Doc: 완성되었을 때의 동작을 결정하는 설계서
인수 조건(Acceptance Criteria): 완료라고 할 수 있는 조건. '~할 때, ~가 ~가 된다' 형태로 작성합니다
작업 계획서: Design Doc을 Phase (= PR)로 나누고, Phase별 대상과 완료 조건을 나열한 문서

목표는 '리뷰 요청 시 설명할 수 있는 상태'

리뷰가 끝나면 PR을 draft로 만들고, AI의 코드 설명과 자신의 인식이 일치하면 draft를 해제하고 리뷰를 요청합니다.

PR을 만드는 작업까지 포함하여 손으로 하는 부분은 AI에게 맡겨도 괜찮습니다.

다만, 리뷰어 앞에서 내용을 설명하는 것은 구현자 본인입니다.

강조한 점

1. 세부 결정일수록 나중에 한다

문서는 3가지 종류가 있고, 세부적인 결정일수록 착수 직전에 합니다.

문서	결정하는 것	만드는 타이밍
Design Doc	무엇을 만들면 정답인지 (보이는 동작)	처음에 1회
...
착수할 Phase의 구현 방법만 읽으면 되고, 기존 코드를 조사한 후 결정하므로, 재작업(손이 돌아가는 것)도 많이 줄었습니다!

2. 뒷정리 PR도 처음에 정한다

뒷정리 역시 작업 계획서 단계에서 결정합니다.

기존 프로세스를 대체할 때는, 전환 PR 그룹과 복귀 기간이 지난 후 오래된 프로세스를 삭제하는 PR 그룹으로 처음부터 나눕니다.

릴리스 후에 결함이 발견되어도, 전환만 되돌릴 수 있도록 하기 위해서입니다.

3. 구현 전과 후의 설명을 바꾼다

/specramo:explain는 구현 전과 구현 후에서 설명하는 내용이 달라집니다.

구현 전: 어느 계층에 어떤 책임을 둘지, 왜 그 설계를 했는지, 처리가 어떤 순서로 진행되는지
구현 후: 어떤 함수가 무엇을 받고 무엇을 반환할지, 테스트가 무엇을 보장하는지

설명 끝에는 이해를 확인하는 질문이 1~5개 돌아옵니다.

답변은 접혀 있으므로, 먼저 스스로 생각한 후에 열어볼 수 있습니다.

이를 활용하여 코드 이해도를 높입니다.

4. 리뷰는 관점별로 다른 AI가 한다

/specramo:review는 관점별로 다른 에이전트를 병렬로 구동합니다.

에이전트	확인할 것
설계서와의 비교	작업 계획서의 범위와 인수 조건에 부합하는지. 대상 외 파일을 변경하지 않았는지
...
Critical과 Warning이 0건이 된 후에 PR을 만들기 때문에, 팀 고유의 지적도 사람 리뷰 전에 찾기 쉽습니다!

도입

언어는 상관없습니다 (동봉된 언어 가이드라인은 Go와 TypeScript).

Claude Code 세션에서 이 두 가지를 실행합니다.

/plugin marketplace add DaichiHoshina/spec-ramo
/plugin install specramo@specramo

스코프(scope) (user / project) 를 결정하여 설치한 후, 도입할 리포지토리에서 /specramo:init를 실행합니다.

이제 준비 완료입니다!

사용해 보니 어땠나

숫자로 측정하지는 않았기 때문에, 여기부터는 개인적인 체감입니다.

✅ 품질이 향상되었다

이해한 후에 PR을 만들기 때문에, 리뷰에서 처음 발견되는 문제가 줄었습니다.

리뷰 코멘트의 수 자체도 적어졌고, 달린 코멘트에 대한 답변이나 수정 시간도 단축되었습니다!

✅ 리뷰 왕복 횟수가 줄었다

공정이 하나 늘었지만, 리뷰 왕복과 재작업이 줄어든 부분이 더 컸습니다.

✅ 정신적 부담이 줄었다

예전에는 구현을 여러 번 다시 출력해야 했지만, 지금은 한 번에 어느 정도 이상적인 코드를 출력할 수 있어, 예전처럼 매일 녹초가 되는 일이 줄었습니다.
(개인적으로 이게 가장 좋았습니다!)

맺음말

의외였던 점은, 이해하는 과정을 늘리는 것이 더 빨라졌다는 것입니다.

정말로 서두르지 않고 돌아가는 것이 빠랐습니다!

지금은