[구현사례] 신규 프로젝트를 복제 한 번으로 시작하기: 보일러플레이트 템플릿 표준화

 

Tech-Frontier.md  kt cloud

$ whoami --team ❯ kt cloud 플렛폼엔지니어링팀 김재혁 님

📋 요약 TL;DR

이 글에서는 공통 기능과 프로젝트 구조, AI 코딩 지침·AI Skill, API·Bot·MCP·Batch 접점 구조를 보일러플레이트 템플릿으로 표준화한 과정을 다룹니다. 반복되는 개발·운영 고민을 줄이고 사람과 AI가 같은 규칙에서 개발하도록 한 설계 원칙과 적용 인사이트를 정리합니다. #보일러플레이트 #개발표준화 #AI코딩지침 #AISkill #MCP

---

1. 문제 정의 — 왜 "표준 템플릿"이 필요했나

새로운 서비스를 시작할 때마다 우리는 비슷한 고민을 반복하고 있었습니다. 팀 안에는 JSP, PHP를 비롯해 다양한 솔루션과 버전이 혼재해 있었고, 프로젝트마다 구조와 컨벤션이 조금씩 달랐습니다. 그러다 보니 새로 합류한 동료가 코드를 파악하는 데 시간이 걸렸고, 같은 기능을 매번 다른 방식으로 다시 구현하는 일도 잦았습니다.

 

동시에 현실적인 제약도 있었습니다. 새로운 기술을 충분히 학습하고 검증할 시간은 늘 부족했고, 그럼에도 짧은 기간 안에 여러 개의 서비스를 빠르게 만들어내야 했습니다. 그렇다고 단순히 "찍어내기"만 해서는 안 됐습니다. 서비스마다 필요한 기능을 골라 쓸 수 있어야 했고, 이후 요구사항이 늘어나도 무리 없이 확장할 수 있어야 했습니다.

 

정리하면 우리가 마주한 문제는 다음과 같았습니다.

• 기술 스택과 프로젝트 구조가 팀 내에서 표준화되어 있지 않다.
• 인증·권한·로깅 같은 기반 기능을 서비스마다 처음부터 다시 만든다.
• 속도(빠른 출시)와 품질(확장성·일관성)을 동시에 만족시키기 어렵다.

이 문제들은 특정 한 프로젝트의 문제가 아니라, 새 프로젝트를 시작할 때마다 구조적으로 반복되는 비용이었습니다. 그래서 "매번 다시 만들지 않아도 되는 출발점"을 표준으로 정의하기로 했습니다.

---

2. 접근 방식 — 검증된 공통 구조를 템플릿으로

해법의 방향은 분명했습니다. 이미 여러 프로젝트에서 검증된 공통 구조를 모아, 신규 프로젝트의 기준이 되는 보일러플레이트 템플릿으로 만드는 것입니다. 핵심 원칙은 두 가지였습니다.

① 비즈니스 로직은 제외하고, 기반 기능만 표준화한다.
인증, 권한, 공통 코드, 환경 설정, 로깅, 빌드, 문서화처럼 어떤 서비스에서도 반복적으로 필요한 영역만 템플릿에 담습니다. 서비스 고유의 비즈니스 로직은 각 프로젝트의 몫으로 남겨, 템플릿이 특정 도메인에 묶이지 않도록 했습니다.

② 구조화된 표준 코드와 예제 + AI 지침을 함께 제공한다.
단순히 빈 골격만 주는 것이 아니라, 바로 참고할 수 있는 예제 코드와 AI가 따라야 할 코딩 지침을 함께 넣었습니다.

 

그 결과 신규 프로젝트는 이 템플릿을 복제한 뒤 서비스명과 도메인만 바꾸면 곧바로 개발을 시작할 수 있게 됩니다.

2-1. 프로젝트 구조 (시각 자료 ①)

boilerplate-template/
├─ backend/                Kotlin · Spring Boot
│  ├─ application/         ← 서비스 로직 코어 (비즈니스 로직)
│  ├─ api/                 HTTP 접점
│  ├─ bot/                 메신저 접점
│  ├─ mcp/                 AI 접점 (MCP)
│  └─ batch/               스케줄 접점
├─ frontend/               TypeScript · React
│  ├─ pages/               화면 페이지
│  ├─ shared/              공통 컴포넌트 (Table·Tree·Modal·ErrorBoundary)
│  └─ services/            Backend 연동
├─ .ai/                    AI 표준
│  ├─ rules/               AI 코딩 지침
│  └─ skills/              분석·배포·로그·컨벤션·보안 리뷰
├─ build.gradle.kts        빌드
└─ README.md               문서화

application 은 서비스의 핵심 로직을 담는 코어이며, api·bot·mcp·batch 는 이 코어를 호출하는 접점입니다. 신규 프로젝트는 이 구조를 복제한 뒤 서비스명·도메인만 변경합니다.

2-2. Backend — Kotlin · Spring Boot

Backend는 인가된 권한에 따라 기능을 제공하는 비즈니스 로직 기반의 API 서비스입니다. 언어는 Kotlin, 프레임워크는 Spring Boot를 채택했습니다. 표준으로 미리 적용해 둔 항목은 다음과 같습니다.

구분	적용 항목	적용 방법
보안 / 인증	사용자 인증	OIDC 기반 IdP를 통한 JWT 토큰 검증 및 갱신(OIDC 레벨로 추상화)
	서비스 인증	Bearer Token 기반 인증
아키텍처	Layer 분리	서비스 로직 코어(Application)와 접점(API·Bot·MCP·Batch)을 역할별 프로젝트로 분리
	환경 변수 관리	Spring Config 적용(Application YAML)
연동	PostgreSQL	Spring Data JPA, Kotlin JDSL
	Redis	캐시 패키지, 세션 데이터 저장(세션 로그인 및 클러스터 간 데이터 공유)
공통 기능	인증 연동	사용자 인증 및 토큰 검증·갱신
	메뉴 관리	메뉴 관리 기능을 Application Layer에 적용
	권한 관리	권한 관리 기능을 Application Layer에 적용
	로깅	표준 로그 포맷, 에러 발생 시 사내 메신저 알림 채널 연동
	모니터링	Actuator를 통한 서비스 상태 확인(Database / API Endpoint / JVM)
	API 문서	Swagger를 통한 API 명세 확인
기타	코드 컨벤션	ktlint, detekt
	테스트	JUnit5 기반 자동화 테스트

 

여기서 중요한 것은 단순한 라이브러리 목록이 아니라 "왜 미리 넣어두었는가"입니다. 인증·권한·로깅·모니터링·문서화는 어떤 서비스를 만들더라도 결국 필요해지는 기능입니다. 매 프로젝트에서 이를 다시 설계하는 대신, 검증된 형태로 한 번 만들어 표준에 포함시켜 두면 개발자는 처음부터 비즈니스 로직에 집중할 수 있습니다.

2-3. Frontend — TypeScript · React

Frontend는 운영자에게 서비스를 제공하는 Web Service로, 사용자(팀)에 인가된 권한 범위의 기능을 노출합니다. 기술 스택은 TypeScript · React이며, UI 컴포넌트는 Antd를 사용하되 추후 사내 디자인 시스템으로 전환할 수 있도록 구성했습니다.

구분	적용 항목	적용 방법
계층 분리	Page	화면 페이지 기능 구현
	Shared Component	공통 컴포넌트 구현
	Service	Backend 연동 기능 구현
컴포넌트	Page	단일형·Split형 페이지 분할 컴포넌트 제공
	Table	공통 테이블 컴포넌트 제공(Excel Export 포함)
	Tree	공통 트리 컴포넌트 제공
	Modal	공통 모달 컴포넌트 제공
	ErrorBoundary	페이지 에러 렌더링 규격화
공통 기능	로그인 / 로그아웃	OIDC 기반 로그인·로그아웃(서버 기준 인증)
	메뉴 관리	메뉴별 권한 관리
	권한 관리	승인 / 반려 어드민 권한 승인 프로세스
기타	코드 컨벤션	husky, eslint, xo

 

Frontend 역시 "화면을 그리는 일"보다 그 이전 단계, 즉 인증·권한·공통 컴포넌트·에러 처리의 규격을 먼저 표준화했습니다. 테이블, 트리, 모달처럼 거의 모든 화면에서 쓰이는 요소를 공통 컴포넌트로 제공하면, 개발자는 화면마다 같은 코드를 반복하지 않고 일관된 사용자 경험을 빠르게 구현할 수 있습니다.

2-4. ⭐ 핵심 차별점 — AI까지 표준화한 보일러플레이트

이 템플릿이 단순한 "코드 스타터 키트"와 가장 크게 다른 지점이 바로 여기에 있습니다. 우리는 공통 코드만 표준화한 것이 아니라, AI가 그 코드를 만드는 방식 자체를 표준화했습니다. 이는 세 축으로 나뉩니다.

 

① AI 코딩 지침 — "AI도 팀의 규칙을 지키게 하기"

 

최근에는 코드를 사람이 직접 작성하기보다 AI의 도움을 받아 작성하는 비중이 빠르게 늘고 있습니다. 그런데 흥미롭게도, AI에게 맡기면 맡길수록 새로운 문제가 드러났습니다. AI조차 팀의 규칙을 일관되게 지키지 않는다는 점이었습니다. 같은 요청에도 매번 다른 구조와 스타일의 코드가 나오니, 애써 만들어 둔 표준의 의미가 흐려질 수 있었습니다.

 

그래서 템플릿에 최소한의 AI 코딩 지침을 명문화해 함께 포함시켰습니다. 사람이 지켜야 할 컨벤션을 AI도 동일하게 따르도록 규칙으로 박아두면, 작성 주체가 사람이든 AI든 결과물의 구조와 품질이 일정 수준으로 수렴합니다. lint가 "작성된 코드"를 검사한다면, AI 지침은 그보다 앞단에서 "코드가 만들어지는 방식"을 정렬한다는 점에서 한 단계 더 근본적인 표준화입니다.

 

시각 자료 ② — AI 코딩 지침(규칙 파일) 샘플

# 프로젝트 AI 코딩 지침
## 아키텍처
- 비즈니스 로직은 반드시 application 모듈에만 작성한다.
- api·bot·mcp·batch 는 application 을 호출하는 접점일 뿐, 자체 로직을 두지 않는다.
## 코드 컨벤션
- Kotlin 코드는 ktlint · detekt 규칙을 준수한다.
- 하나의 함수는 한 가지 책임만 갖도록 작성한다.
## 보안
- 인증·인가는 표준 모듈을 사용하고 우회 구현하지 않는다.
- 키·토큰 등 민감정보는 코드에 하드코딩하지 않는다.
## 테스트 · 문서
- 신규 로직은 JUnit5 테스트를 함께 작성한다.
- 공개 API 는 Swagger 명세를 갱신한다.
# → 사람도 AI도 동일한 규칙 위에서 코드를 작성하게 된다

② AI Skill — "반복 작업을 AI에게 위임하기"

 

여기서 한 걸음 더 나아가, 프로젝트에서 자주 수행하는 작업을 AI Skill 형태로 템플릿에 기본 탑재하는 방향으로 표준을 확장하고 있습니다. 지침이 "어떻게 코드를 짤지"에 대한 규칙이라면, AI Skill은 "무엇을 대신 해줄지"에 대한 실행 능력입니다. 템플릿을 복제하는 순간, 개발자는 다음과 같은 작업을 도와줄 AI Skill을 함께 손에 넣게 됩니다.

• 프로젝트 분석 Skill — 코드 구조와 의존성을 파악해 새로 합류한 개발자의 온보딩을 돕습니다.
• 배포 Skill — 배포 설정(value·chart) 관리, 개발기 자동 배포, 배포 로그 분석을 지원합니다.
• 로그·시스템 분석 Skill — 실행 에러 로그를 분석하고, DML·DDL 쿼리를 점검합니다.
• 코드 컨벤션 리뷰 Skill — ktlint·detekt·eslint 같은 정적 분석을 넘어, 팀의 컨벤션과 클린코드 기준에 맞춰 코드를 리뷰하고 개선점을 제안합니다.
• 보안 리뷰 Skill — 인증·권한 처리, 민감 정보 노출, 흔한 취약점 패턴 등을 점검해 배포 전에 보안 관점의 리뷰를 거치도록 돕습니다.

③ MCP · Bot 확장 — "하나의 서비스 로직(Application)에 여러 접점을 연결하기"

 

여기서 MCP를 이해하려면, 먼저 이 템플릿의 Backend 구조가 가진 핵심 설계를 짚어야 합니다. 우리는 비즈니스 로직을 Application이라는 하나의 코어 계층에 모았습니다. Application은 "어떤 서비스의 실제 로직"이 되는 존재이고, 그 로직을 외부에 노출하는 입구(접점)는 그때그때 필요에 따라 갈아 끼울 수 있도록 분리했습니다.

 

시각 자료 ③ — 접점 → Application 코어 구조

   API   ─┐
   Bot   ─┤
   MCP   ─┼──▶  Application  ──▶  PostgreSQL
   Batch ─┘     (서비스 로직 코어)  ──▶  Redis
✚ 새로운 접점이 필요하면 Application 은 그대로, 접점 어댑터만 추가
  → 비즈니스 로직 중복 구현 없이 확장 가능

즉 API · Bot · MCP · Batch는 모두 같은 Application을 호출하는 서로 다른 접점일 뿐입니다. 동일한 비즈니스 로직을 어떤 통로로 노출할 것인가의 차이만 있을 뿐, 핵심 로직은 한 곳에서 재사용됩니다.

• API → Application — 화면(Frontend)이나 외부 서비스가 HTTP로 로직을 호출하는 기본 접점입니다.
• Bot → Application — 사내 메신저 채널에서 채팅으로 동일한 로직을 실행하는 접점입니다. ("이 서비스 개발기 배포해줘" 같은 요청을 그대로 처리)
• MCP → Application — MCP(Model Context Protocol)는 AI가 표준화된 방식으로 이 서비스의 로직과 접점을 만들 수 있게 해주는 구조입니다. 템플릿에 구현해 둔 서비스 기능을 MCP로 노출하면, AI가 임의의 방식이 아니라 정해진 인터페이스를 통해 그 로직을 호출할 수 있습니다.
• Batch → Application — 스케줄 기반의 배치 작업이 같은 로직을 재사용해 실행하는 접점입니다.

이 구조의 장점은 확장성입니다. 새로운 접점이 필요해지면(예: 새로운 외부 프로토콜, 새로운 채널) Application은 그대로 둔 채 접점 어댑터만 추가하면 됩니다. 비즈니스 로직을 매번 다시 구현하지 않고, "입구"만 늘려가며 같은 서비스를 다양한 방식으로 제공할 수 있는 것입니다. MCP와 Bot은 바로 이 확장 가능한 접점 구조 위에서 자연스럽게 추가된 결과물입니다.

접점	호출 주체	역할
API	Frontend · 외부 서비스	HTTP 기반으로 로직 호출
Bot	사람(협업 채널)	메신저에서 채팅으로 로직 실행
MCP	AI	표준 인터페이스로 AI가 로직과 접점 형성
Batch	스케줄러	정기 작업으로 로직 재사용
↓ 모두 동일한 Application(서비스 로직 코어)을 호출 ↓

 

정리하면 이 템플릿은 "표준 코드 + AI가 지킬 규칙(지침) + AI가 대신 해줄 작업(Skill) + 하나의 Application코어에 API·Bot·MCP·Batch를 자유롭게 붙이는 확장 구조"를 함께 제공합니다. 표준화의 대상을 코드에서 개발·운영 행위 전반과 서비스 아키텍처로까지 넓혔다는 점이, 우리가 이 템플릿에서 가장 강조하고 싶은 부분입니다.

---

3. 적용 결과 및 인사이트

템플릿을 실제 프로젝트에 적용하면서 체감한 변화는 다음과 같습니다.

• 사람과 AI가 같은 규칙 위에서 일하게 되었습니다. AI 코딩 지침과 lint(ktlint·detekt·eslint 등)가 함께 작동하면서, 작성 주체가 사람이든 AI든 일정 수준 이상의 일관된 코드가 만들어졌습니다. AI를 적극 활용하면서도 품질이 흔들리지 않는다는 점이 가장 큰 변화였습니다.
• 반복 작업을 AI Skill에 위임할 수 있게 되었습니다. 프로젝트 분석·배포·로그 분석 같은 정형화된 작업을 AI Skill이 거들면서, 개발자는 환경 세팅이 아니라 비즈니스 문제에 더 빨리 집중할 수 있었습니다.
• 서비스 간 연동 비용이 줄었습니다. 표준 서비스끼리 주고받는 요청·응답에 대한 표준 코드가 마련되어, 연동 지점에서 매번 형식을 새로 협의할 필요가 줄었습니다.
• 사내 시스템 연동의 진입 장벽이 낮아졌습니다. 자주 연동하는 사내 시스템에 대한 표준 정보가 템플릿에 정리되어 있어, 처음 연동하는 개발자도 빠르게 따라갈 수 있습니다.
• 개발과 배포 속도가 빨라졌습니다. 표준 코드와 연동 기반이 이미 갖춰져 있으니, 새 서비스를 더 빠르게 개발하고 배포할 수 있게 되었습니다.

적용 과정에서 가장 크게 배운 점은, 표준화의 진짜 가치는 "코드를 빨리 짜는 것"이 아니라 "고민의 반복을 줄이는 것"에 있다는 사실이었습니다. 인증을 어떻게 붙일지, 로깅 포맷을 어떻게 맞출지, 권한을 어디서 검사할지 — 이미 답이 정해진 질문을 매번 다시 던지지 않게 되면서, 팀의 에너지가 정작 중요한 비즈니스 문제로 옮겨갈 수 있었습니다.

---

4. 향후 계획 / 마무리

표준 템플릿은 완성형이 아니라 계속 다듬어 나가는 기반입니다. 앞으로의 방향은 다음과 같습니다.

4-1. 더 타이트하고, 더 확장성 있게

• 핵심 기능은 더 오밀조밀하게 추상화하여, 기능 단위의 추상화 레벨을 높입니다.
• 그 핵심을 바탕으로 누구나 더 쉽게 가져다 쓸 수 있도록 확장성을 강화합니다.
• 가져다 쓰는 것으로 끝내지 않고, 운영 가시성까지 확보할 수 있도록 DevOps와의 연동을 기본 표준에 포함합니다.

4-2. AI Skill을 "기본 탑재"로 끌어올리기

현재 일부 AI Skill은 이미 존재하지만, 모든 신규 프로젝트가 별도 설정 없이 곧바로 사용할 수 있도록 템플릿의 기본 구성으로 끌어올리는 것이 다음 목표입니다. 지향점은 "복제하는 순간 사람도, AI도, 자동화 작업도 함께 따라온다"는 경험입니다.

• 프로젝트 분석 Skill — 이미 존재하나 템플릿 기본 포함은 아직 미반영. 기본 탑재를 추진합니다.
• 배포 Skill — 배포 설정(value·chart) 관리, 개발기 자동 배포, 배포 로그 분석을 표준 흐름으로 통합합니다.
• 로그·시스템 분석 Skill — 실행 에러 로그 분석과 DML·DDL 쿼리 점검을 상시 지원합니다.
• 코드 컨벤션 · 보안 리뷰 Skill — 정적 분석을 넘어선 컨벤션·클린코드 리뷰와 보안 취약점 점검을 표준 워크플로우에 포함합니다.

이렇게 AI 지침(규칙)과 AI Skill(실행 능력)이 템플릿에 함께 녹아들면, 보일러플레이트는 단순한 시작점을 넘어 "AI와 함께 일하는 표준 개발 환경" 그 자체가 됩니다.

4-3. MCP · Bot 으로 확장하기

마지막 확장 방향은 AI의 작동 범위를 프로젝트 밖으로 넓히는 것입니다. 사내 시스템 연동을 MCP 서버로 표준화해 AI가 정해진 인터페이스로 안전하게 시스템에 접근하게 하고, 그 능력을 Bot으로 노출해 메신저 채널에서 배포·로그 분석·자산 조회 같은 표준 작업을 곧바로 호출할 수 있도록 만드는 것이 목표입니다. 이렇게 되면 개발·운영의 표준이 IDE 안을 넘어 팀의 협업 흐름 전체로 자연스럽게 스며들게 됩니다.

비슷한 고민, 즉 "새 프로젝트를 시작할 때마다 같은 기반을 다시 만든다"는 문제를 가진 팀이라면, 거창한 프레임워크부터 만들기보다 이미 검증된 공통 구조를 한곳에 모으는 것에서 출발해 보길 권합니다. 표준은 처음부터 완벽할 필요가 없습니다. 반복되는 비용을 하나씩 표준으로 흡수해 나가는 과정 자체가 곧 팀의 자산이 됩니다.

 

---

?› 자주 묻는 질문 FAQ

Q. 비즈니스 로직을 일부러 제외한 이유가 있나요?

A. 템플릿이 특정 도메인에 종속되면 재사용 범위가 급격히 좁아지기 때문입니다. 모든 서비스가 공통으로 필요로 하는 기반 기능만 표준화하고 비즈니스 로직은 각 프로젝트에 맡김으로써, 어떤 도메인의 서비스든 같은 출발점에서 시작할 수 있도록 했습니다.

Q. AI에게 코드를 맡기면 결국 비슷해지는데, 왜 별도의 지침이 필요한가요?

A. 실제로는 같은 요청에도 AI가 매번 다른 구조와 스타일의 코드를 만들어내는 경우가 많았습니다. 사람이 지키는 컨벤션을 AI 지침으로 명문화해 두면, 작성 주체가 사람이든 AI든 결과물이 팀의 표준으로 수렴하게 됩니다.

Q. API · Bot · MCP · Batch가 모두 있으면 비슷한 로직을 네 번 구현해야 하나요?

A. 아닙니다. 그 점이 이 구조의 핵심입니다. 비즈니스 로직은 Application 코어 한 곳에만 구현하고, API·Bot·MCP·Batch는 그 로직을 호출하는 접점(어댑터) 일 뿐입니다. 새로운 통로가 필요해지면 Application 은 그대로 둔 채 접점만 추가하면 되므로, 같은 로직을 다양한 방식으로 노출하면서도 중복 구현 없이 확장할 수 있습니다.

Q. AI Skill과 MCP는 둘 다 AI 관련인데 어떻게 다른가요?

A. 작동하는 시점과 위치가 다릅니다. AI Skill 은 주로 개발·운영 과정에서 AI가 "무엇을 대신 해줄지"를 정의하는 능력입니다. 반면 MCP 는 런타임에 AI가 Application 에 구현된 서비스 로직을 표준 인터페이스로 호출하도록 만드는 접점 으로, API·Bot·Batch와 같은 계열에 속합니다. 정리하면 Skill은 "AI의 작업 능력", MCP는 "AI가 우리 서비스에 접속하는 입구"입니다.

Q. 표준을 강하게 잡으면 오히려 자유도와 확장성이 떨어지지 않나요?

A. 그래서 "핵심은 타이트하게, 그 위는 확장성 있게"를 원칙으로 삼고 있습니다. 모든 서비스가 공유해야 하는 기반은 단단하게 추상화하되, 그 위에서 각 팀이 필요에 맞게 확장할 수 있는 여지를 남겨 두는 방향으로 발전시키고 있습니다.

---