Image: AI generated
기존 프로젝트에 SSOT를 적용하고 싶은데 처음부터 다시 쓸 수 없다면, 레거시 Go·TypeScript·Python·Java·C#·Rust·PHP 백엔드에서 OpenAPI와 DDL을 자동 추출하고 싶다면 — codistill이 기존 코드에서 명세를 짜낸다.
“우리는 이미 200 엔드포인트가 있는데요”
yongol 글을 읽은 사람이 묻는다. “좋은 건 알겠는데, 우리 프로젝트에는 이미 코드가 수만 줄이에요. 처음부터 SSOT를 작성해야 하나요?”
처음부터 작성하면 좋겠지만, 현실에서는 불가능하다. 운영 중인 서비스를 멈추고 명세를 처음부터 쓸 수 있는 팀은 없다. 영업 중인 가게의 기초를 뜯을 수는 없다.
그래서 codistill을 만들었다. 기존 코드에서 SSOT를 짜낸다.
코드를 넣으면 명세가 나온다
codistill은 웹 프레임워크 소스 코드를 정적 분석하여 선언적 명세를 자동 추출한다.
codist scan --openapi ./my-project
이 한 줄이면 기존 코드에서 OpenAPI 3.0 스펙이 나온다. 수작업으로 며칠 걸리던 것이 초 단위로 끝난다.
프로젝트에 이미 openapi.yaml이 있으면 codist가 이를 감지해 병합한다 — 구조는 코드에서(라우터 등록이 사실의 기준), 설명은 기존 스펙에서 가져오고, 어떤 라우트에도 연결되지 않은 죽은 명세는 버린다.
런타임 오버헤드 제로. 계측(instrumentation) 불필요. 순수 정적 분석이다. 학술적으로도 같은 방향이 검증되고 있다. Huang et al.(2024)은 ICSE에서 소스 코드 정적 분석만으로 REST API의 OpenAPI 명세를 자동 생성하는 기법(Respector)을 발표했다. codistill 자체도 대규모 실제 코드베이스 — Immich, Ghost, NocoDB, Plane, AppFlowy 등 — 를 대상으로 단련되며, 운영 규모의 소스에서만 드러나는 추출 결함들을 고쳤다(changelog).
열여섯 프레임워크, 여덟 언어
| 언어 | 프레임워크 |
|---|---|
| Go | Gin, Fiber, Echo |
| TypeScript | NestJS, Fastify, Hono, Express |
| Python | FastAPI, Flask, Django |
| Java | Spring Boot, Quarkus |
| C# | ASP.NET Core |
| Rust | Actix Web |
| PHP | Laravel |
| Deno TypeScript | Supabase Edge Functions |
세 개(Gin, NestJS, FastAPI)로 시작한 것이 이제 여덟 개 언어, 열여섯 개 프레임워크를 커버한다. 프레임워크는 go.mod, package.json, requirements.txt, pom.xml, *.csproj, Cargo.toml, composer.json, supabase/functions/로 자동 감지되며, --framework로 지정할 수도 있다. 대부분의 백엔드는 tree-sitter로 분석하고, Go+Gin은 go/ast + go/types를 직접 쓴다.
추출하는 것
| 레이어 | 출력 |
|---|---|
| 라우트 | HTTP 메서드, 경로, 핸들러 위치, 미들웨어 |
| 요청 | 바디 바인딩 타입 + 구조체 필드, 쿼리/폼/경로 파라미터, 파일 업로드 |
| 응답 | 상태 코드, 바디 타입 + 구조체 필드, json/validate 태그 |
| OpenAPI | paths, parameters, requestBody, responses, components/schemas |
| DDL | 마이그레이션 히스토리에서 테이블별 CREATE TABLE 스냅샷 (ALTER COLUMN·제약·인덱스 포함) |
| SQL | 리포지토리 메서드 스켈레톤 — CRUD 타입, 테이블, 파라미터, 반환 |
소스 코드에 흩어져 있던 결정이 선언적 명세로 응축된다.
DDL 통합
마이그레이션 파일이 50개 쌓여 있으면, 현재 스키마가 어떤 상태인지 파악하기 어렵다. ALTER TABLE이 누적된 순서를 머릿속에서 재생해야 한다.
codist ddl ./migrations -o ./schema
마이그레이션 히스토리를 전부 읽고, 테이블별로 깨끗한 CREATE TABLE 스냅샷 하나를 출력한다. 50개 파일이 테이블 수만큼의 .sql 파일로 정리된다.
CREATE/ALTER/DROP TABLE, ADD/DROP/ALTER COLUMN, 제약(constraint), 인덱스를 처리한다. Prisma 기반 프로젝트라면 codist prisma가 schema.prisma를 직접 읽어 — 복합 FK, enum, pgvector 타입까지 — FK 순서로 정렬된, 실제 DB에 그대로 적용되는 DDL을 낸다.
sqlc 쿼리 스캐폴딩
리포지토리 패턴으로 작성된 코드에서 SQL 쿼리 스켈레톤을 추출한다.
codist sql next --repo ./repository --queries ./db/query
next — 래칫 워크플로우다. 쿼리가 없는 다음 리포지토리 메서드를 보여주고, 스켈레톤을 작성하면 다음으로 넘어간다. 전부 채우면 멈춘다.
codist sql status
현재 진행 상태를 보여준다. 에이전트가 “다 했습니다"라고 선언하는 것이 아니라, 기계가 남은 메서드 수를 판정한다.
yongol 파이프라인으로의 진입
codistill의 출력은 yongol의 입력이다.
기존 코드
↓ codist scan --openapi
↓ codist ddl
↓ codist sql next
OpenAPI + DDL + sqlc 쿼리
↓ yongol validate
↓ yongol generate
SSOT 기반 코드베이스
codistill이 기존 코드에서 SSOT를 역추출하고, yongol이 그 SSOT의 정합성을 검증하고 코드를 생성한다. brownfield에서 greenfield로의 전환이 한 번에 일어나는 것이 아니라, 점진적으로 일어난다. Perry와 Wolf(1992)가 정의한 아키텍처 침식(erosion)과 드리프트(drift) — 명세를 위반하면 침식이고, 명세에 무감각해지면 드리프트다. codistill은 이미 드리프트가 발생한 코드에서 명세를 역추출하여 일치시키는 도구다.
처음에는 codistill이 추출한 OpenAPI와 DDL만 yongol에 넣는다. validate를 돌리면 레이어 간 불일치가 드러난다. 하나씩 고친다. SSaC를 추가한다. Rego를 추가한다. Hurl을 추가한다. 매 단계마다 yongol이 정합성을 보장한다.
기초 공사가 아니라 내진 보강이다. Martin Fowler(2004)가 명명한 Strangler Fig 패턴 — 레거시를 한 번에 교체하지 않고 점진적으로 감싸서 대체하는 것. 영업 중인 가게 문을 닫지 않고 건물을 보강한다.
시작
npx skills add park-jun-woo/codistill
codist scan --openapi ./my-project
기존 코드에서 명세가 증류된다.
코드: github.com/park-jun-woo/codistill
관련 글
- yongol — AI 코딩 SaaS의 용골 — codistill이 추출한 SSOT를 검증하고 코드를 생성하는 도구.
- Ratchet Pattern — 에이전트가 끝까지 가게 만드는 방법 —
codist sql next의 래칫 워크플로우 배경. - Reins Engineering — 고삐 있는 AI — codistill이 속한 엔지니어링 체계.
출처
- Huang, R., Motwani, M., Martinez, I., & Orso, A. (2024). Generating REST API Specifications through Static Analysis. Proceedings of the IEEE/ACM 46th International Conference on Software Engineering (ICSE 2024). ACM
- Lercher, A., Macho, C., Bauer, C., & Pinzger, M. (2024). Generating Accurate OpenAPI Descriptions from Java Source Code. arXiv:2410.23873. arXiv
- Chauhan, S., Rasheed, Z., et al. (2026). OpenAI for OpenAPI: Automated generation of REST API specification via LLMs. Journal of Systems and Software. arXiv
- Perry, D. E. & Wolf, A. L. (1992). Foundations for the Study of Software Architecture. ACM SIGSOFT Software Engineering Notes, 17(4), 40-52. ACM
- De Silva, L. & Balasubramaniam, D. (2012). Controlling software architecture erosion: A survey. Journal of Systems and Software, 85(1), 132-151. ScienceDirect
- Fowler, M. (2004). StranglerFigApplication. martinfowler.com/bliki. Link
- Fritzsch, J., Bogner, J., Wagner, S., & Zimmermann, A. (2019). Microservices Migration in Industry: Intentions, Strategies, and Challenges. 2019 IEEE ICSME, pp. 481-490. arXiv
- Curino, C. A., Moon, H. J., & Zaniolo, C. (2008). Graceful database schema evolution: the PRISM workbench. Proceedings of the VLDB Endowment, 1(1), 761-772. VLDB
- Nghiem, D., Guo, H., & Foster, J. S. (2023). A Qualitative Study of REST API Design and Specification Practices. 2023 IEEE VL/HCC, pp. 148-156. IEEE
변경이력
- 2026-06-19: 커버리지를 8개 언어·16개 프레임워크로 확장; DDL ALTER COLUMN 및 Prisma 스키마 지원; 실제 코드베이스 대상 검증(codistill v0.1.11)
- 2026-05-26: 초판