프레임워크 규칙

프레임워크 개요

구성 요소끼리 충분히 통합되어 있고 안정된 프레임워크를 사용한다.
SI 프로젝트에서 많이 쓰는 3계층 아키텍처를 기준으로 정리한다.

3계층 아키텍처(3-Tier Architecture)

프런트엔드

Presentation Tier (표현 계층) — 이 프로젝트는 dictionary-app(React 19 + Vite)

백엔드

Application/Logic Tier (응용/로직 계층) — 이 프로젝트는 dictionary-api(Spring Boot 4)

데이터베이스

Data Tier (데이터 계층) — 이 프로젝트는 MySQL(로컬)과 H2(테스트·운영)

실제 구성과 요청 흐름은 아키텍처 개요 참고.

프레임워크를 고를 때 고민할 점

AI와 함께 개발할 때는 사람이 쓰기 편한지뿐 아니라 AI가 정확한 코드를 만들 수 있는지도 기준이 된다. AI는 규칙이 흐릿한 곳에서 매번 다른 선택을 하므로, 선택지를 미리 좁혀 두는 것이 핵심이다.

통합이 잘 된 프레임워크를 고른다. 인증·DB 접근·검증·테스트를 공식 스타터나 표준 모듈로 제공하는 프레임워크는 조합할 부품이 적다. 부품이 적을수록 AI가 라이브러리를 임의로 골라 끼워 넣을 여지도 줄어든다. Spring Boot의 spring-boot-starter-*가 대표적인 예이다.
사용자가 많은 주류 기술을 고른다. 공개 코드와 문서가 많은 기술일수록 AI가 올바른 사용법을 알고 있다. 사용자가 적은 사내 프레임워크나 신생 라이브러리는 AI가 없는 API를 지어낼 가능성이 크다.
버전을 명시하고 최신 메이저 버전은 특히 조심한다. AI는 학습 시점의 옛 API로 코드를 쓰기 쉽다. 예를 들어 Spring Boot 4는 Jackson 3을 쓰므로 패키지가 com.fasterxml.jackson에서 tools.jackson으로 바뀌었다. 이런 차이는 CLAUDE.md에 버전과 함께 적어 둔다.
역할마다 라이브러리를 하나로 정한다. 서버 상태, 클라이언트 상태, 폼, HTTP 클라이언트, 날짜 처리처럼 같은 역할을 하는 라이브러리가 여럿이면 AI가 파일마다 다른 것을 쓴다. 쓰는 것과 함께 쓰지 않는 것도 적는다. dictionary-app은 “스타일은 별도 CSS 파일, styled-components, sx prop, 인라인 style 대신 Chakra UI v3의 chakra() 팩토리로 작성한다”처럼 대안을 명시해서 막는다.
규약이 강한(opinionated) 도구를 고른다. 디렉토리 구조, 라우팅, 설정 방식이 정해져 있으면 AI의 결과물이 일정해진다. 자유도가 큰 도구를 쓴다면 그만큼 CLAUDE.md에 구조를 직접 정해야 한다.
자동 검증 도구가 갖춰졌는지 본다. 타입 검사, 린터, 포매터, 테스트 러너가 명령 한 줄로 돌아가야 AI가 스스로 실수를 찾고 고친다. 정적 타입 언어(TypeScript, Java)는 컴파일 단계에서 오류를 잡아 주므로 AI와 궁합이 좋다.
계층 사이를 잇는 도구를 고려한다. 백엔드 API 스펙에서 프런트엔드 타입을 생성하면 두 계층의 응답 모양이 어긋나지 않는다. 이 프로젝트는 springdoc이 만든 OpenAPI 문서(/v3/api-docs)에서 openapi-typescript로 src/types/schema.ts를 생성한다(pnpm gen:api-types).
운영 환경과 팀을 함께 본다. 배포할 서버, 발주처가 요구하는 표준(공공 SI의 전자정부 표준프레임워크 등), 유지보수할 인력이 다룰 수 있는 기술인지도 따진다. AI가 코드를 써도 장애 대응과 검토는 사람이 한다.

이 프로젝트의 조합

역할별로 하나씩 고른 결과이다. 버전은 각 저장소의 package.json·build.gradle 기준이다.

계층	역할	선택
프런트엔드	프레임워크·빌드	React 19(React Compiler) + Vite 8, TypeScript
프런트엔드	UI	Chakra UI v3 + Emotion, Heroicons
프런트엔드	라우팅	React Router
프런트엔드	서버 상태	TanStack Query (`queries`·`mutations` 폴더로 분리)
프런트엔드	클라이언트 상태	Zustand
프런트엔드	폼·검증	React Hook Form + Zod
프런트엔드	HTTP·날짜·그리드	axios, dayjs, AG Grid
프런트엔드	검증 도구	oxlint, Prettier, Vitest
백엔드	프레임워크	Spring Boot 4.1 + Java 26, Gradle
백엔드	웹·검증	Spring Web MVC, Bean Validation
백엔드	DB 접근	Spring Data JPA + QueryDSL, Flyway
백엔드	인증·세션	Spring Security + Spring Session JDBC
백엔드	외부 연동·문서	`RestClient`, springdoc-openapi
백엔드	로깅·설정 암호화	Log4j2, Jasypt
백엔드	검증 도구	Spotless, JUnit + RestAssured, Jacoco
데이터베이스	DBMS	MySQL(로컬), H2(테스트·운영 데모)

조합 예시

프로젝트 성격에 따라 실제로 많이 쓰는 조합이다. 어느 조합을 고르든 위 표처럼 역할별로 하나씩 정해 CLAUDE.md에 적는다.

조합	구성	알맞은 경우
SPA + Spring Boot (이 프로젝트)	React + Vite + TanStack Query / Spring Boot + JPA·QueryDSL / MySQL	업무 화면이 많은 사내 시스템. 프런트엔드와 백엔드를 따로 배포하고 팀을 나눌 때
공공 SI	Vue 3 또는 React / 전자정부 표준프레임워크(Spring 기반) + MyBatis / Oracle·Tibero	발주처가 표준프레임워크 적용을 요구할 때. SQL을 직접 관리하는 문화일 때
풀스택 TypeScript	Next.js(App Router) + Prisma 또는 Drizzle / PostgreSQL	소규모 팀이 한 언어로 화면과 API를 함께 만들 때. 타입을 계층 간에 그대로 공유할 때
Python API	React / FastAPI + SQLAlchemy + Alembic / PostgreSQL	데이터 분석·AI 모델 연동이 중심인 서비스

응답 코드

성공 시 200, 201(데이터 생성), 204(데이터 삭제)를 쓴다.
실패 시 400(잘못된 요청), 401(로그인 필요), 403(권한 없음), 404(대상 없음), 500(서버 오류)을 쓴다.

공통 응답 형식

모든 계층이 같은 모양의 응답을 주고받도록 응답 봉투(envelope)를 정한다. 이 프로젝트는 모든 API가 ResponseDto로 감싼 JSON을 돌려준다.

{
  "successYn": "Y",
  "messageCd": "SUCCESS",
  "payload": {}
}

successYn: 성공 여부(Y/N).
messageCd: 클라이언트가 분기에 쓰는 결과 코드(NOT_FOUND, NOT_LOGIN 등). HTTP 상태와 1:1로 대응한다.
payload: 실제 데이터. 목록 조회는 pagination을 함께 싣는다.

결과 코드 목록과 예외가 응답으로 바뀌는 과정은 예외 처리 가이드, 프런트엔드에서 응답 봉투를 벗기는 방법은 백엔드 API 사용 예제 참고.

그 밖의 공통 항목

인증 방식(세션·토큰), API 버전 규칙(/v1/...)처럼 아키텍처에 따라 모든 계층이 함께 지켜야 하는 항목이 더 있을 수 있다. 이 프로젝트는 JWT 대신 DB 세션 기반 인증을 쓴다(아키텍처 개요 참고).