Skip to content
Dictionary Guide

템플릿 코드 작성 규칙 정리

템플릿 코드에서 규칙 정의가 필요한 항목

Section titled “템플릿 코드에서 규칙 정의가 필요한 항목”
  1. 템플릿 기능 지정
  2. 템플릿이 갖춰야 할 요소
  3. 규칙 등록과 활용 방법

템플릿 기능 지정

Section titled “템플릿 기능 지정”

CRUD를 비롯해 여러 형태의 API가 모두 들어 있는 기능(feature) 하나를 템플릿으로 지정하고 규칙에 적어둔다. 이후 AI 에이전트는 새 기능을 만들 때 이 코드를 참조해 같은 패턴으로 작성한다. 규칙을 글로만 설명할 때보다 실제로 동작하는 코드를 가리킬 때 AI가 훨씬 정확하게 따라 한다.

dictionary-api는 board(게시판)를 템플릿으로 지정했다. 업무 기능이 아니라 템플릿 용도로 둔 기능이라, 업무 요구사항 때문에 모양이 바뀌지 않는다.

  • Directoryapi/board/
    • Directorycontroller/
      • BoardController.java find · findAll · findByPage · create · update · delete · deleteAll
    • Directorydto/
      • BoardCreate.java API별 요청 DTO
      • BoardUpdate.java
      • BoardFindAll.java
      • BoardFindByPage.java
      • BoardDeleteAll.java
      • BoardResponseDto.java 기능 안에서 공유하는 응답 DTO
    • Directoryrepository/
      • BoardRepository.java Spring Data JPA
      • BoardQueryDslRepository.java 동적 조건·페이징
      • BoardQueryDslRepositoryImpl.java
    • Directoryservice/
      • BoardService.java

템플릿이 갖춰야 할 요소

Section titled “템플릿이 갖춰야 할 요소”
  1. 모든 형태의 API — 단건·전체·페이지 조회, 등록(201 + Location), 수정, 단건·일괄 삭제(204)를 한 기능 안에 모두 둔다. 새 기능이 어떤 API를 만들든 참고할 원형이 있어야 한다.
  2. 모든 계층 — Entity, Repository(JPA + QueryDsl), Service, DTO, Controller를 빠짐없이 갖춘다.
  3. 공통 규칙 적용 — 네이밍(<Feature> 접두어), final 명시, 예외 처리(BizException), 인가 애노테이션(@GuestForbidden), Swagger 문서화처럼 규칙으로 정한 항목을 템플릿이 모두 지키고 있어야 한다. 템플릿이 규칙을 어기면 AI는 그 위반까지 그대로 복제한다.
  4. 테스트 — 계층별 테스트(Service는 Mockito, Repository는 @DataJpaTest, Controller는 RestAssured)도 함께 둔다. 그래야 새 기능의 테스트도 같은 모양으로 요청할 수 있다.

규칙 등록과 활용

Section titled “규칙 등록과 활용”
  1. CLAUDE.md에 템플릿 기능과 그 용도를 적는다.
    CLAUDE.md (dictionary-api)
    - `board`: findAll/findByPage/find/create/update/delete/deleteAll 풀 CRUD 예제 — 새 CRUD 기능을 추가할 때
      템플릿으로 삼기 좋다.
  2. 새 기능을 요청할 때 템플릿을 함께 언급하면, AI가 탐색 없이 바로 같은 패턴으로 작성한다. 
    board 기능을 템플릿으로 삼아 t_column 테이블의 CRUD API를 만들어 줘
  3. 규칙이 바뀌면 템플릿 코드부터 고친다. 템플릿이 최신 규칙을 따르고 있어야 이후 만들어지는 기능도 최신 규칙을 따른다.