기존 코드에서 사양서를 자동 생성하는 cc-rsg를 사용해 보았다
요약
기존 코드베이스를 분석하여 사양서를 자동으로 역생성하는 Claude Code용 스킬인 'cc-rsg'를 소개합니다. 레거시 시스템의 문서 부재 문제를 해결하기 위해 리버스 엔지니어링 방식을 사용하여 코드의 구조와 로직을 사양서로 변환합니다.
핵심 포인트
- 코드에서 사양서를 역생성하는 Claude Code 전용 스킬
- 독자 맞춤형 사양서 생성을 위한 5단계 목적 설정 프로세스
- 코드 단위와 사양서 섹션 간의 일대일 추적성 확보
- 신뢰도 마커를 통한 생성된 내용의 정확도 표시
- 인간에게 질문을 던져 사양서의 빈틈을 채우는 메커니즘
서론
"사양서가 없는 시스템을, 사람이 코드를 읽으며 조사하면서 유지보수하고 있다"
SIer나 시스템 개발 현장에서는 이것이 흔히 일어나고 있습니다. 10년 이상 작동해 온 시스템에 사양서는 존재하지 않는다. 담당자는 떠났다. 작동하고 있는 것은 확실하지만, 왜 그렇게 작동하는지는 아무도 모른다.
문서가 없는 레거시 시스템(Legacy System)의 해석에 팀이 몇 주에서 몇 달을 소비하는 케이스는 드물지 않습니다.
그러한 과제에 대해, 코드에서 사양서를 역생성하는 도구인 "cc-rsg"를 사용해 보았습니다. Claude Code의 스킬로서 동작하는 것으로, 소규모부터 실무 수준의 대규모 코드베이스(Codebase)까지 실행해 본 결과가 상상 이상이었기에 정리해 보겠습니다.
cc-rsg란
cc-rsg(Reverse Spec Generator)는 기존 코드베이스를 해석하여 사양서를 자동 생성하는 Claude Code용 스킬입니다.
문서가 존재하지 않는 코드에서, 리버스 엔지니어링(Reverse Engineering)으로 사양서를 만들어낸다는 발상입니다.
소스 코드: https://github.com/daishir0/cc-rsg
통상적인 "코드를 작성하는" 용도의 AI와는 반대 방향으로 동작합니다.
| 통상적인 AI 활용 | cc-rsg |
|---|---|
| 사양서 → 코드 생성 | 코드 → 사양서 생성 |
| ... |
6단계의 흐름
cc-rsg는 6개의 단계로 진행됩니다. Phase 0의 대화에서 시작하여, 최종적으로 납품물(사양서)로 출력됩니다.
Phase 0: 목적 설정 (5가지 대화 질문)
↓
Phase 1: 리콘 (코드베이스 정찰 및 구조 파악)
...
Phase 0: 5가지 질문
처음에 5가지 질문에 답합니다. 이 대화를 통해 사양서의 방향성이 결정됩니다.
- 사양서의 주요 독자는 누구인가 (신규 참여 멤버 / 팀 리더 / 학습자 / 감사인)
- 이 사양서를 무엇을 위해 사용하는가 (기능 추가 전 이해 / 버그 조사 / 코드 리뷰 / 교육 목적)
- 어느 정도의 입도(Granularity)로 기술할 것인가 (모듈 / 클래스 / 함수)
- 특히 주의해야 할 영역이 있는가
- 출력 형식의 템플릿은 무엇인가 (web-app / api-service / batch-system / library-sdk)
처음에 "누가 무엇을 위해 읽는가"를 확정하는 것이 포인트입니다. 같은 코드라도 독자에 따라 사양서의 작성 방식이 완전히 달라지기 때문입니다.
Phase 2: 인벤토리(Inventory)의 개념
cc-rsg에서 중요한 것이 "인벤토리"입니다.
코드에서 추출한 모든 단위(함수, 클래스, 모듈 등)가 인벤토리로 등록되며, 그것이 사양서의 섹션이 됩니다. "코드의 무언가가 사양서의 무언가에 대응한다"라는 일대일 추적성(Traceability)이 담보됩니다.
Phase 3: 신뢰도 마커
생성된 사양서에는 신뢰도 마커가 붙습니다.
## calculateScore 함수 [CONFIDENCE: HIGH]
스코어 계산의 핵심 로직.
[REF: tetris.js:142-158]
...
[CONFIDENCE: HIGH]는 코드에서 명확하게 읽어낼 수 있는 내용. [CONFIDENCE: MED]는 추측이 포함된 부분. [ASSUMED: ...]는 "아마도 이럴 것이다"라는 가정을 명시하고 있습니다.
이것이 나중에 Phase 5의 대화로 이어집니다.
Phase 5: 질문 뱅크
cc-rsg는 7가지 카테고리의 질문을 자동 생성합니다.
| 카테고리 | 내용 |
|---|---|
| business_rule | 비즈니스 로직의 의도 |
| ... | |
| 이것들을 인간에게 질문하여 사양서의 "빈틈"을 채워 나가는 메커니즘입니다. |
우선 작은 예제로: 테트리스로 정밀도를 확인했다
첫 번째 소재로 테트리스(https://github.com/kubowania/Tetris)를 선택한 이유는 두 가지가 있습니다.
하나는 "누구나 알고 있다"는 것. 조작·테트리미노·회전·라인 제거——생성된 사양서를 읽고 "아, 확실히 그렇네"라고 검증할 수 있습니다. 또 하나는 "코드가 수백 줄"이라서, 모든 단계를 짧은 시간 안에 통과할 수 있는 현실적인 사이즈라는 점입니다.
대규모 코드베이스에 대한 적용은 이후 섹션에서 소개하겠습니다. 우선 여기서는 정밀도를 확인하는 것이 목적입니다.
Phase 0의 대화
이러한 설정으로 진행했습니다.
Q: 주요 독자는?
→ 학습자용 (이 코드를 통해 배우는 사람)
Q: 무엇을 위해 사용하는가?
...
Phase 2: 40개의 인벤토리 (Inventory)
코드베이스가 소규모였기 때문에 「절약 모드 (省力化モード)」가 자동으로 적용되었습니다. 함수 단위로 40개의 인벤토리 (Inventory)가 추출되었습니다.
인벤토리 (일부):
- init() — 게임 초기화
- draw() — 캔버스 그리기
...
Phase 3: 15분 만에 10장 분량의 초안 완성
병렬 조사 → 초안 생성 단계에서, 약 15분 만에 10장 구성의 초안이 완성되었습니다.
"인간이 하루 걸려 쓰는 품질의 80%를 5분 만에 뽑아냈다" —— 이것이 솔직한 평가입니다. 나머지 20%는 동적 검증, 업무 문맥 보완, 교정 등 인간이 사후에 덧붙여야 할 영역이지만, 초안(叩き台)으로서는 충분하고도 남습니다.
장 구성은 다음과 같습니다:
00-metadata.md # 메타 정보 · 생성 요약
01-overview.md # 프로젝트 개요
02-architecture.md # 아키텍처
...
Phase 4: 검증
40개의 인벤토리 (Inventory)가 모두 커버되었는지 자동으로 검증되었습니다. 커버리지 (Coverage) 100%.
Phase 5: 발견된 문제점들이 흥미로웠다
이 부분이 이번에 가장 놀랐던 점입니다.
Phase 5의 대화에서, cc-rsg는 코드로부터 7개의 문제 클러스터 (Problem Cluster)를 추출했습니다.
문제 1: 일시정지 중 키 입력 버그
일시정지 중에도 화살표 키가 반응하는 구현이 되어 있었습니다. 키 이벤트 (Key Event)의 가드 조건 (Guard Condition)이 일시정지 상태를 고려하지 않고 있습니다.
문제 2: 점수 계산 순서가 틀림
라인을 지운 다음에 점수를 계산하는 구현으로 되어 있으나, 본래는 점수 계산 후에 지워야 한다는 지적입니다. 계산 순서의 실수가 버그의 원인이 될 수 있습니다.
문제 3: 회전 상태가 리셋되지 않음
테트리미노 (Tetromino)가 고정될 때 회전 상태 변수가 리셋되지 않습니다. 다음 테트리미노에 잘못된 회전 상태가 이어질 가능성이 있습니다.
문제 4: J와 S 피스가 구현되지 않음
표준적인 테트리스에는 7종류의 테트리미노 (I, O, T, L, J, S, Z)가 있지만, 이 코드에는 J와 S가 구현되어 있지 않습니다.
문제 5: 사용되지 않는 이미지 파일
이미지 파일은 존재하지만, 코드 내에서 참조되지 않고 있습니다.
문제 6: SRS (Super Rotation System) 미구현
테트리스의 회전 시스템으로 일반적인 SRS가 구현되어 있지 않고, 단순한 회전만 가능합니다. 벽 차기 (Wall Kick) 처리가 없습니다.
이것들은 보통 코드를 읽고 있으면 찾아내기 어려운 문제들이 많죠.. 「코드를 읽고 사양서를 작성한다」는 작업 과정에서, 구현의 어노말리 (Anomaly)를 자동으로 검출해 준 셈입니다.
Phase 6: 납품물
최종적으로 00-metadata.md에서 시작하는 10장의 사양서 세트가 출력되었습니다. 각 섹션에는 [REF: file:line] 형태로 소스 코드에 대한 참조가 붙어 있어, "이 기술은 코드의 이 부분에서 왔다"는 추적성 (Traceability)이 유지됩니다.
## 라인 삭제 로직 [CONFIDENCE: HIGH]
4행 동시 삭제로 Tetris가 성립된다. 삭제 후 보드를 위에서부터 다시 그린다.
[REF: tetris.js:198-215]
...
추적성 (Traceability)의 가치
cc-rsg의 가장 큰 특징은 추적성 (Traceability)이라고 느꼈습니다.
"사양서의 이 기술은 코드의 어느 줄에서 왔는가"를 항상 추적할 수 있습니다. 사양서를 읽다가 "정말로 그런가?"라는 의문이 들면 즉시 코드를 확인할 수 있습니다.
사양서의 기술 → [REF: file.js:142] → 코드의 실제 구현
이러한 양방향 추적이 가능한 문서는 수작업으로는 좀처럼 유지하기 어렵습니다.
또한 신뢰도 마커 ([CONFIDENCE: HIGH/MED/LOW])와 가정의 명시 ([ASSUMED: ...])를 통해, "어디까지가 확실하고 어디부터가 추측인가"를 사양서를 읽는 사람에게 전달합니다.
프로덕션 레벨 시스템으로의 적용
테트리스가 「정밀도 데모」라면, 「스케일 데모」는 Redmine을 통해 확인했습니다.
Redmine (https://github.com/redmine/redmine)은 Ruby on Rails로 제작된 프로젝트 관리 도구로, 약 10만 행 · 1095개 파일로 구성된 프로덕션 레벨의 코드베이스입니다.
테트리스 vs Redmine 실측 비교
| 축 | 테트리스 | Redmine |
|---|---|---|
| 입력 규모 | 267행 (1개 파일) | 10만 행+ (1095개 파일) |
| ... | ... | |
| 입력이 400배임에도 출력은 약 2배로 끝납니다. 도메인 영역 단위로 묶는 장(Chapter) 구성 전략 덕분에, 모델 수가 늘어나도 장의 수는 선형적으로 증가하지 않습니다. |
Redmine에 대한 한 줄 평은 다음과 같았습니다.
"거대한 코드베이스의 '지도'를 5분 만에 그렸다"
개별 도로(메서드·로직)의 세부 사항까지는 그려내지 못했지만, 어디에 무엇이 있는지를 조망하기에는 충분합니다.
테트리스와는 사용법이 다릅니다. 테트리스는 행 번호 수준까지 추적할 수 있을 정도로 깊습니다. Redmine은 전체적인 지도로 기능합니다. 이 '깊이 vs 넓이'의 구분하여 사용하는 것이 실용적인 포인트입니다.
대규모 코드를 위한 스케일 설계 (Scale Design)
소규모 코드베이스에서는 '절약 모드 (Efficiency Mode)'가 자동으로 적용되었지만, 대규모 코드에서는 병렬 조사 모드로 전환됩니다.
| 코드 규모 | 모드 | 동작 |
|---|---|---|
| ~50개 함수 정도 | 절약 모드 | 메인 에이전트 1개로 처리 |
| ... | ... |
.cc-rsg/state.json
이 상태를 저장하기 때문에, 며칠에 걸쳐 여러 세션으로 나누어 진행할 수도 있습니다.
{
"phase": 3,
"inventory_completed": 128,
...
마이크로서비스 (Microservices) 구성이나, 여러 언어가 혼재된 시스템에서도 인벤토리(Inventory) 단위로 페이즈를 재개할 수 있습니다.
대응 언어에 대하여
테트리스의 예시는 JavaScript/CSS였지만, cc-rsg는 특정 언어의 파서 (Parser)에 의존하지 않습니다. Claude Code의 컨텍스트 이해 (Context Understanding)를 기반으로 하기 때문에, 많은 언어에 대응합니다.
| 분류 | 대응 예시 |
|---|---|
| Web 프론트엔드 | JavaScript, TypeScript, CSS, HTML |
| ... | ... |
특정 언어에 특화된 구문 분석기가 아니라 '코드를 읽고 의도를 추론하는' 접근 방식이므로, 언어에 관계없이 동일한 품질의 사양서가 생성되는 경향이 있습니다. 레거시(Legacy) PHP 시스템이나, 그다지 메이저하지 않은 언어의 코드베이스에도 적용할 수 있다는 점은 실용성 측면에서 상당히 도움이 되는 부분입니다.
문서 체계의 커스터마이징 (Customization)
Phase 0에서 선택하는 템플릿 (web-app / api-service / batch-system / library-sdk)은 스킬 디렉토리 내의 YAML 정의 파일로 관리됩니다.
~/.claude/skills/cc-rsg/templates/
├── web-app.yaml
├── api-service.yaml
...
자사 시스템에 최적화된 템플릿을 여기에 추가하면, 그대로 다음 분석에 사용할 수 있습니다. 예를 들어 '머신러닝 파이프라인 (Machine Learning Pipeline)'이나 '임베디드 시스템 (Embedded System)'용 템플릿을 만들면, 해당 도메인에 특화된 장 구성이나 질문 뱅크 (Question Bank)를 재사용할 수 있습니다. 사양서의 포맷을 조직의 표준에 맞추고 싶은 경우에도 이곳을 변경하기만 하면 됩니다.
생성 후의 대화형 확장
cc-rsg로 사양서 초안을 생성한 후, Claude Code와의 대화를 통해 내용을 더욱 풍성하게 만들 수 있습니다.
mermaid로 구조를 시각화
생성된 사양서에 대해 "도표를 추가해줘"라고 지시하는 것만으로 구조도를 작성할 수 있습니다.
"02-architecture.md에, 모듈 간의 의존 관계를 mermaid로 추가해줘"
이러한 의존 관계도가 추가됩니다:
그 외에도 상태 전이도(State Transition Diagram)나 시퀀스 다이어그램(Sequence Diagram)도 마찬가지로 대화식으로 추가할 수 있습니다.
"07-game-state.md에, 게임의 상태 전이를 mermaid의 stateDiagram으로 작성해줘"
ER 다이어그램이나 시퀀스 다이어그램도
API 서비스나 업무 시스템이라면, 데이터 모델의 ER 다이어그램 (ER Diagram)이나 API 호출의 시퀀스 다이어그램도 마찬가지로 지시를 통해 추가할 수 있습니다.
"08-data-model.md에, 테이블 정의를 mermaid의 erDiagram으로 작성해줘"
"외부 API와의 통신 흐름을 sequenceDiagram으로 03-architecture.md에 추가해줘"
생성된 사양서는 '완성품'이 아니라 '초안 (Draft)'으로서, 그 이후에도 대화를 계속하며 키워나가는 방식이 실제 사용 사례에 적합하다고 생각합니다.
요약
두 가지 코드베이스로 테스트한 결과를 정리합니다.
| 테트리스 (267행) | Redmine (10만 행 이상) |
|---|---||
| 한 줄 평 | 인간이 하루 걸려 작성할 품질의 80%를 5분 만에 만들어냈다 | 거대한 코드베이스의 "지도"를 5분 만에 그려냈다 |
| ... |
cc-rsg는 "완벽한 사양서를 자동 생성하는" 도구가 아닙니다.
인간이 작성하기 전에 초안 (Draft)을 제시해 주는 도구입니다. 나머지 20%—동적 검증 (Dynamic Verification), 업무 문맥 보완, 장(Chapter) 간의 정합성—는 인간이 리뷰합니다. 이러한 역할 분담으로 사용하는 것이 현실적입니다.
사양서가 없는 레거시 시스템 (Legacy System)의 해석, 인수인계 문서 작성, 신규 참여 멤버를 위한 설명 자료, 감사 대응—"코드를 언어화해야만 하는" 상황은 현장에 매우 많습니다. 그에 대한 하나의 해답으로서, 시도해 볼 가치는 충분하다고 생각합니다.
이 기사가 도움이 되었다면, 꼭 지원을 부탁드립니다!
앞으로도 Claude Code 활용 팁을 계속해서 전달하겠습니다.
참고 링크
Discussion
AI 자동 생성 콘텐츠
본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기