@agentsmd/preset-spring 0.0.0-stage → 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 이태경
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# @agentsmd/preset-spring
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[`@agentsmd/cli`](https://www.npmjs.com/package/@agentsmd/cli)의 Spring Boot 서버 프리셋입니다. Spring Boot 4(Spring Framework 7) 기준입니다.
+
+```bash
+npx @agentsmd/cli init --preset git,java,spring   # Git·Java 규칙과 함께 (권장)
+npx @agentsmd/cli init --preset java,spring       # Java 규칙과 함께
+```
+
+- 구조·설정: 기능 단위 패키지, 레이어 의존 방향, 생성자 주입, DTO 경계, `@ConfigurationProperties`, JSpecify
+- JPA·트랜잭션: 엔티티 규칙, 지연 로딩과 N+1, `@Transactional`·`readOnly`, open-in-view, Flyway 마이그레이션
+- API: URL·상태 코드, Bean Validation, `ProblemDetail` 오류 응답, 페이징
+- 테스트: `@WebMvcTest`·`MockMvcTester`, `@DataJpaTest`, `@MockitoBean`, Testcontainers `@ServiceConnection`
+- Java 코드 규칙, 검증 명령, 포맷 설정은 넣지 않습니다. [Java 프리셋](https://www.npmjs.com/package/@agentsmd/preset-java)을 함께 고르면 더해집니다.
+- Git 훅·GitHub 설정은 설치하지 않습니다. `AGENTS.md`는 고른 프리셋에 맞춰 만들어집니다.

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Spring Boot 서버용 프리셋. Spring Boot 4(Spring Framework 7) 기준이다.
+ *
+ * 패키지 구조·설정, JPA·트랜잭션, API·테스트 문서를 담는다.
+ * Java 코드 규칙과 검증 명령, 포맷 설정은 넣지 않는다. Java 프리셋을 함께 고르면 더해진다.
+ * 프리셋끼리 의존하지 않으므로, 이 프리셋만 설치해도 문서의 링크가 깨지지 않게 다른 프리셋 문서로 링크하지 않는다.
+ * `files/`는 빌드 결과(dist/)와 소스(src/) 어디서 실행해도 패키지 루트 기준으로 같은 위치다.
+ */
+export declare const springPreset: {
+    name: string;
+    description: string;
+    filesDir: string;
+    docs: {
+        path: string;
+        when: string;
+    }[];
+    rules: string[];
+    nextSteps: string[];
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;CAgCP,CAAC"}

package/dist/index.js

@@ -0,0 +1,43 @@
+import { fileURLToPath } from "node:url";
+/**
+ * Spring Boot 서버용 프리셋. Spring Boot 4(Spring Framework 7) 기준이다.
+ *
+ * 패키지 구조·설정, JPA·트랜잭션, API·테스트 문서를 담는다.
+ * Java 코드 규칙과 검증 명령, 포맷 설정은 넣지 않는다. Java 프리셋을 함께 고르면 더해진다.
+ * 프리셋끼리 의존하지 않으므로, 이 프리셋만 설치해도 문서의 링크가 깨지지 않게 다른 프리셋 문서로 링크하지 않는다.
+ * `files/`는 빌드 결과(dist/)와 소스(src/) 어디서 실행해도 패키지 루트 기준으로 같은 위치다.
+ */
+export const springPreset = {
+    name: "spring",
+    description: "Spring Boot 서버용 구조·JPA·트랜잭션·API·테스트 규칙",
+    filesDir: fileURLToPath(new URL("../files", import.meta.url)),
+    docs: [
+        {
+            path: "docs/spring-architecture.md",
+            when: "클래스·패키지를 만들 때. 패키지 구조, 의존 방향, 주입, DTO 경계, 설정",
+        },
+        {
+            path: "docs/spring-data-jpa.md",
+            when: "엔티티·Repository·트랜잭션을 다룰 때. 지연 로딩, N+1, 스키마 마이그레이션",
+        },
+        {
+            path: "docs/spring-api.md",
+            when: "컨트롤러·API 를 만들 때. URL, 상태 코드, 요청 검증, 오류 응답, 페이징",
+        },
+        {
+            path: "docs/spring-testing.md",
+            when: "Spring 이 필요한 테스트를 쓸 때. 슬라이스 테스트, @MockitoBean, Testcontainers",
+        },
+    ],
+    rules: [
+        "필드 주입 대신 생성자 주입을 쓴다.",
+        "엔티티를 API 요청·응답으로 쓰지 않는다. DTO(record)로 바꾼다.",
+        "다른 기능의 repository·엔티티를 직접 쓰지 않고 그 기능의 service 를 통한다.",
+        "`@Transactional` 은 service 에 두고, 조회는 `readOnly = true`. 트랜잭션 안에서 외부 API 를 부르지 않는다.",
+    ],
+    nextSteps: [
+        "검증 명령은 java 프리셋이 넣습니다. 함께 설치하지 않았다면 agentsmd init --preset java 를 실행하세요.",
+        "application.yml 에 docs/spring-data-jpa.md 의 open-in-view·batch fetch 설정을 넣으세요.",
+    ],
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,IAAI,EAAE,QAAQ;IACd,WAAW,EAAE,wCAAwC;IACrD,QAAQ,EAAE,aAAa,CAAC,IAAI,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7D,IAAI,EAAE;QACJ;YACE,IAAI,EAAE,6BAA6B;YACnC,IAAI,EAAE,8CAA8C;SACrD;QACD;YACE,IAAI,EAAE,yBAAyB;YAC/B,IAAI,EAAE,mDAAmD;SAC1D;QACD;YACE,IAAI,EAAE,oBAAoB;YAC1B,IAAI,EAAE,gDAAgD;SACvD;QACD;YACE,IAAI,EAAE,wBAAwB;YAC9B,IAAI,EAAE,+DAA+D;SACtE;KACF;IACD,KAAK,EAAE;QACL,sBAAsB;QACtB,4CAA4C;QAC5C,sDAAsD;QACtD,oFAAoF;KACrF;IACD,SAAS,EAAE;QACT,0EAA0E;QAC1E,gFAAgF;KACjF;CACe,CAAC"}

package/files/docs/spring-api.md

@@ -0,0 +1,72 @@
+# API
+
+Spring MVC 로 REST API 를 만들 때의 규칙이다.
+
+## 컨트롤러
+
+- 컨트롤러는 요청 검증, 서비스 호출, 응답 변환만 한다. 업무 규칙은 서비스와 도메인에 둔다.
+- 요청·응답은 DTO(record)로 받고 돌려준다. → [spring-architecture.md](spring-architecture.md)
+- 컨트롤러마다 try-catch 로 예외를 응답으로 바꾸지 않는다. 전역 예외 처리에 맡긴다.
+
+## URL 과 메서드
+
+- 자원은 복수 명사로 쓴다. (`/orders`, `/orders/{orderId}`) URL 에 동사를 넣지 않는다. (`/getOrders`)
+- CRUD 로 표현하기 어려운 상태 전이는 하위 경로로 쓴다. (`POST /orders/{orderId}/cancel`)
+
+| 메서드 | 용도 | 성공 응답 |
+| --- | --- | --- |
+| `GET` | 조회 | `200` |
+| `POST` | 생성, 상태 전이 | 생성은 `201` 과 `Location` 헤더, 상태 전이는 `200`·`204` |
+| `PUT` | 전체 교체 | `200`·`204` |
+| `PATCH` | 일부 수정 | `200`·`204` |
+| `DELETE` | 삭제 | `204` |
+
+| 실패 상황 | 상태 코드 |
+| --- | --- |
+| 요청 형식·값 검증 실패 | `400` |
+| 인증 없음 | `401` |
+| 권한 없음 | `403` |
+| 자원 없음 | `404` |
+| 현재 상태와 충돌 (이미 취소된 주문 취소 등) | `409` |
+| 서버 오류 | `500` |
+
+## 요청 검증
+
+- 요청 DTO 필드에 Bean Validation(`@NotBlank`, `@Positive`, `@Size` 등)을 붙이고, 컨트롤러 파라미터에 `@Valid` 를 붙인다.
+- 형식 검증(필수, 길이, 범위)은 DTO 에서, 업무 규칙 검증(재고, 상태)은 도메인·서비스에서 한다.
+
+```java
+public record CreateOrderRequest(@NotNull Long productId, @Positive int quantity) {}
+
+@PostMapping("/orders")
+public ResponseEntity<OrderResponse> create(@Valid @RequestBody CreateOrderRequest request) {
+    OrderResponse response = orderService.create(request.productId(), request.quantity());
+    return ResponseEntity.created(URI.create("/orders/" + response.id())).body(response);
+}
+```
+
+## 오류 응답
+
+- 오류 응답은 RFC 9457 Problem Details 형식으로 통일한다. Spring 의 `ProblemDetail` 을 쓴다.
+- `spring.mvc.problemdetails.enabled: true` 로 Spring 이 던지는 기본 예외(검증 실패 등)도 같은 형식으로 응답한다.
+- 기능 예외는 `@RestControllerAdvice` 한 곳에서 상태 코드와 오류 코드로 바꾼다.
+- 오류 코드(`ORDER_NOT_CANCELABLE`)를 함께 내려 클라이언트가 메시지 문구가 아니라 코드로 분기하게 한다.
+- 응답에 스택 트레이스, SQL, 내부 클래스 이름을 넣지 않는다. 예상하지 못한 예외는 로그로 남기고 일반 메시지만 돌려준다.
+
+```java
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+
+    @ExceptionHandler(OrderNotCancelableException.class)
+    public ProblemDetail handle(OrderNotCancelableException e) {
+        ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT, e.getMessage());
+        problem.setProperty("code", "ORDER_NOT_CANCELABLE");
+        return problem;
+    }
+}
+```
+
+## 목록과 페이징
+
+- 개수가 늘어날 수 있는 목록은 페이징한다. `Pageable` 을 받고 최대 크기를 제한한다. (`spring.data.web.pageable.max-page-size`)
+- `Page` 객체를 그대로 응답하지 않는다. 내용과 페이지 정보를 담은 응답 DTO 로 감싼다.

package/files/docs/spring-architecture.md

@@ -0,0 +1,82 @@
+# Spring 구조 · 설정
+
+Spring Boot 4(Spring Framework 7) 기준이다. Java 코드 규칙과 검증 명령은 Java 프리셋 문서를 따른다.
+이미 다른 구조를 쓰는 프로젝트는 기존 구조를 따르고, 새로 만드는 부분만 이 문서에 맞춘다.
+
+## 패키지
+
+기능(도메인) 단위로 먼저 나누고, 그 안을 레이어로 나눈다.
+
+```text
+com.example.app/
+  order/            기능 하나
+    controller/     HTTP 요청·응답
+    dto/            요청·응답 DTO
+    service/        유스케이스, 트랜잭션 경계
+    repository/     Spring Data 인터페이스
+    domain/         엔티티, 값 객체, 도메인 규칙
+    exception/      이 기능의 예외
+  member/
+  global/           설정, 전역 예외 처리, 보안 같은 기술 기반
+```
+
+- 필요 없는 하위 패키지는 만들지 않는다. (API 가 없는 기능에는 `controller/` 를 두지 않는다)
+- `global` 에는 비즈니스 규칙을 두지 않는다. 두 기능이 같은 개념을 쓴다고 `global` 로 올리지 않고, 기능 경계를 먼저 다시 본다.
+- 외부 시스템 연동(결제, 메일 등)은 서비스가 쓰는 인터페이스를 `service` 에 두고, 구현은 `global/external/<시스템>` 에 둔다.
+
+## 의존 방향
+
+```text
+controller → service → repository
+                │          │
+                └──▶ domain ◀┘
+```
+
+- `domain` 은 다른 레이어를 모른다. Spring 에 의존하지 않는다. (JPA 매핑 어노테이션만 예외)
+- `global` 은 기능 패키지에 의존하지 않는다.
+- 다른 기능의 `repository`·엔티티를 직접 쓰지 않는다. 그 기능의 `service` 를 통한다.
+  즉시 결과가 필요 없으면 도메인 이벤트(`ApplicationEventPublisher`, `@TransactionalEventListener`)로 나눈다.
+- 다른 기능의 엔티티는 객체가 아니라 ID 로 참조한다.
+- 의존 방향은 ArchUnit 테스트로 검사할 수 있다. → [spring-testing.md](spring-testing.md)
+
+## 빈과 주입
+
+- 생성자로 주입한다. 필드 주입(`@Autowired` 필드)을 쓰지 않는다. 생성자가 하나면 `@Autowired` 를 붙이지 않는다.
+- 주입받는 필드는 `private final` 이다. Lombok 을 쓰면 `@RequiredArgsConstructor` 로 생성자를 만든다.
+- 구현이 하나뿐인 서비스에 인터페이스를 만들지 않는다. (`XxxServiceImpl` 금지)
+- 현재 시각은 `Clock` 빈을 주입받아 쓴다. 테스트에서 시각을 고정할 수 있다.
+
+## DTO 경계
+
+- 컨트롤러는 엔티티를 요청으로 받거나 응답으로 돌려주지 않는다. 지연 로딩 예외, 순환 참조, 내부 필드 노출이 생긴다.
+- 요청·응답 DTO 는 `record` 로 만든다.
+- 엔티티 → 응답 변환은 DTO 의 정적 팩토리(`OrderResponse.from(order)`)에 둔다. 엔티티가 DTO 를 모르게 한다.
+
+```java
+public record OrderResponse(Long id, String status, int totalPrice) {
+
+    public static OrderResponse from(Order order) {
+        return new OrderResponse(order.getId(), order.getStatus().name(), order.totalPrice());
+    }
+}
+```
+
+## 설정
+
+- 설정 값은 `@ConfigurationProperties` 와 `record` 로 묶어 받는다. `@Value` 를 여러 클래스에 흩어 두지 않는다.
+- `@Validated` 와 Bean Validation 으로 애플리케이션 시작 시점에 검증한다. 값이 틀리면 뜨지 않는다.
+- 비밀값은 설정 파일에 적지 않고 `${DB_PASSWORD}` 처럼 환경변수를 참조한다.
+- 환경별 설정은 `application-<profile>.yml` 로 나누고, 운영 값은 환경변수로 덮어쓴다.
+
+```java
+@Validated
+@ConfigurationProperties(prefix = "payment")
+public record PaymentProperties(@NotBlank String baseUrl, @NotNull Duration timeout) {}
+```
+
+- 애플리케이션 클래스에 `@ConfigurationPropertiesScan` 을 붙여 등록한다.
+
+## null
+
+- Spring Boot 4 는 JSpecify 로 null 가능성을 표시한다. null 이 될 수 있는 반환값·파라미터에는 `org.jspecify.annotations.Nullable` 을 붙인다.
+- Spring 의 `org.springframework.lang.Nullable` 은 새로 쓰지 않는다.

package/files/docs/spring-data-jpa.md

@@ -0,0 +1,88 @@
+# JPA · 트랜잭션
+
+Spring Data JPA(Hibernate) 를 쓰는 프로젝트의 규칙이다.
+
+## 엔티티
+
+- 도메인 모델과 JPA 엔티티는 같은 클래스로 쓴다. 매핑 전용 클래스를 따로 두지 않는다.
+- JPA 용 기본 생성자는 `@NoArgsConstructor(access = AccessLevel.PROTECTED)` 로 만든다.
+- setter 를 두지 않는다. 상태는 의도를 드러내는 메서드로 바꾼다. (`changeStatus()` 가 아니라 `cancel()`)
+- getter 는 응답 변환 같은 읽기에만 쓴다. Lombok 을 쓰면 클래스에 `@Getter` 를 붙인다.
+- 엔티티에 `@Setter`, `@Data`, `@ToString`, `@EqualsAndHashCode` 를 쓰지 않는다. 지연 로딩 필드를 건드리거나 순환 참조로 터진다.
+- enum 컬럼은 `@Enumerated(EnumType.STRING)` 으로 저장한다. `ORDINAL` 은 상수 순서를 바꾸면 데이터가 틀어진다.
+- 값 객체는 `@Embeddable` 로 매핑한다.
+
+```java
+@Entity
+@Getter
+@NoArgsConstructor(access = AccessLevel.PROTECTED)
+public class Order {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Enumerated(EnumType.STRING)
+    private OrderStatus status;
+
+    @ManyToOne(fetch = FetchType.LAZY)
+    private Member member;
+
+    public void cancel() {
+        if (status != OrderStatus.PAID) {
+            throw new OrderNotCancelableException(id);
+        }
+        status = OrderStatus.CANCELED;
+    }
+}
+```
+
+## 연관관계
+
+- 모든 연관관계를 지연 로딩(`fetch = FetchType.LAZY`)으로 둔다. `@ManyToOne`, `@OneToOne` 은 기본값이 즉시 로딩이라 직접 적는다.
+- 양방향 연관관계는 반대쪽에서 탐색할 이유가 있을 때만 만든다.
+- 다른 기능(Aggregate)의 엔티티는 연관관계 대신 ID 로 참조한다.
+- `cascade`, `orphanRemoval` 은 같은 Aggregate 안의 부모·자식 사이에만 쓴다.
+
+## N+1 과 조회
+
+- 목록을 읽은 뒤 연관 엔티티를 쓰면 행마다 쿼리가 나간다(N+1). fetch join(`join fetch`)이나 `@EntityGraph` 로 함께 읽는다.
+- 컬렉션을 fetch join 하면서 페이징하면 Hibernate 가 메모리에서 페이징한다. 컬렉션은 `default_batch_fetch_size` 로 묶어 읽는다.
+- 목록·검색·통계처럼 일부 컬럼만 필요한 조회는 엔티티 대신 DTO(record) projection 으로 읽는다.
+- 단건 상세는 엔티티를 읽어 트랜잭션 안에서 응답 DTO 로 바꾼다.
+- 개발 환경에서는 실행 SQL 을 로그로 보며 N+1 을 확인한다. (`logging.level.org.hibernate.SQL: debug`)
+
+```yaml
+spring:
+  jpa:
+    open-in-view: false
+    properties:
+      hibernate:
+        default_batch_fetch_size: 100
+```
+
+## Repository
+
+- Aggregate 루트마다 하나 만든다. `JpaRepository<Xxx, ID>` 를 바로 상속하고 서비스가 주입받는다. 포트 인터페이스와 구현으로 나누지 않는다.
+- 메서드 이름 쿼리가 길어지면 `@Query` 로 쓴다.
+- 없을 때의 처리는 서비스에서 기능 예외로 바꾼다. (`findById(id).orElseThrow(() -> new OrderNotFoundException(id))`)
+
+## 트랜잭션
+
+- `@Transactional` 은 service 의 public 메서드에 둔다. 컨트롤러와 repository 에 두지 않는다.
+- 조회만 하는 메서드는 `@Transactional(readOnly = true)` 로 둔다.
+- 수정은 엔티티 메서드로 상태를 바꾸고 변경 감지에 맡긴다. 수정 뒤 `save()` 를 다시 부르지 않는다.
+- 트랜잭션 안에서 외부 API 호출·메시지 발행을 하지 않는다. DB 커넥션을 오래 잡고, 롤백돼도 외부 호출은 되돌릴 수 없다.
+  커밋 뒤에 할 일은 `@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)` 로 처리한다.
+- 같은 클래스 안에서 `this.method()` 로 부르면 `@Transactional` 이 적용되지 않는다. (프록시를 거치지 않는다)
+- checked 예외는 기본으로 롤백하지 않는다. 기능 예외는 unchecked 로 만든다.
+
+## open-in-view
+
+- `spring.jpa.open-in-view` 를 `false` 로 둔다. 기본값(`true`)은 응답을 다 쓸 때까지 DB 커넥션을 잡고, 컨트롤러에서 지연 로딩이 일어나 쿼리 위치를 알기 어렵게 만든다.
+
+## 스키마
+
+- 스키마 변경은 Flyway(또는 Liquibase) 마이그레이션 파일로 한다.
+- `spring.jpa.hibernate.ddl-auto` 는 운영에서 `validate` 나 `none` 이다. `create`, `update` 를 쓰지 않는다.
+- 이미 적용된 마이그레이션 파일은 고치지 않는다. 바꿀 내용은 새 파일로 추가한다.

package/files/docs/spring-testing.md

@@ -0,0 +1,72 @@
+# Spring 테스트
+
+Spring Boot 4 기준이다. 테스트 원칙(given/when/then, AssertJ, 재현 테스트)은 Java 프리셋 문서를 따른다.
+이 문서는 Spring 이 필요한 테스트를 어떻게 띄우는지 정한다.
+
+## 테스트 종류
+
+Spring 컨텍스트를 띄우는 테스트는 느리다. 가능한 한 아래 표의 위쪽 방법을 쓴다.
+
+| 대상 | 방법 |
+| --- | --- |
+| 도메인 객체, 서비스 | Spring 없이 단위 테스트. 서비스의 Repository·외부 연동은 Mockito 로 대체 |
+| 컨트롤러 (요청·검증·응답 형식) | `@WebMvcTest(OrderController.class)` 와 `MockMvcTester`. 서비스는 `@MockitoBean` |
+| Repository, 쿼리 | `@DataJpaTest` 와 Testcontainers 로 띄운 운영과 같은 DB |
+| 여러 레이어를 잇는 흐름 | `@SpringBootTest`. 핵심 시나리오에만 쓴다 |
+
+## 규칙
+
+- `@MockBean`·`@SpyBean` 은 Spring Boot 4 에서 제거됐다. `@MockitoBean`·`@MockitoSpyBean` 을 쓴다.
+- 기술별 테스트 starter(`spring-boot-starter-webmvc-test`, `spring-boot-starter-data-jpa-test` 등)를 `testImplementation` 으로 둔다.
+- `@SpringBootTest` 에서 MockMvc 를 쓰려면 `@AutoConfigureMockMvc` 를 붙인다.
+- DB 는 H2 같은 다른 DB 로 대신하지 않는다. 방언·제약·함수가 달라 운영에서만 실패하는 쿼리를 놓친다.
+- Testcontainers 컨테이너는 `@ServiceConnection` 을 붙인 `@TestConfiguration` 빈으로 두고 테스트에서 `@Import` 한다.
+  같은 설정의 테스트끼리 컨텍스트 캐시를 함께 써서 컨테이너를 한 번만 띄운다.
+- `@DataJpaTest` 는 `@ServiceConnection` 으로 띄운 DB 를 내장 DB 로 바꾸지 않는다. (`@AutoConfigureTestDatabase` 기본값 `NON_TEST`)
+- 테스트마다 `@MockitoBean` 조합이나 설정이 다르면 컨텍스트를 새로 띄운다. 공통 조합은 기반 클래스나 설정으로 모은다.
+- 의존 방향 규칙은 ArchUnit 테스트로 검사할 수 있다. → [spring-architecture.md](spring-architecture.md)
+
+## 예시
+
+```java
+@TestConfiguration(proxyBeanMethods = false)
+public class TestcontainersConfiguration {
+
+    @Bean
+    @ServiceConnection
+    MySQLContainer mysqlContainer() {
+        return new MySQLContainer(DockerImageName.parse("mysql:8.4"));
+    }
+}
+
+@DataJpaTest
+@Import(TestcontainersConfiguration.class)
+class OrderRepositoryTest {
+
+    @Autowired
+    private OrderRepository orderRepository;
+
+    @Test
+    @DisplayName("회원의 결제 완료 주문만 최신순으로 조회한다")
+    void findPaidOrders() { ... }
+}
+
+@WebMvcTest(OrderController.class)
+class OrderControllerTest {
+
+    @Autowired
+    private MockMvcTester mvc;
+
+    @MockitoBean
+    private OrderService orderService;
+
+    @Test
+    @DisplayName("수량이 0 이면 400 을 돌려준다")
+    void rejectsZeroQuantity() {
+        assertThat(mvc.post().uri("/orders").contentType(MediaType.APPLICATION_JSON).content("""
+                        {"productId": 1, "quantity": 0}
+                        """))
+                .hasStatus(HttpStatus.BAD_REQUEST);
+    }
+}
+```

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@agentsmd/preset-spring",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.6.0",
+  "description": "Spring Boot 서버용 AI 작업 지침 프리셋 (구조·JPA·트랜잭션·API·테스트 규칙)",
+  "keywords": [
+    "agents.md",
+    "ai-agent",
+    "spring",
+    "spring-boot",
+    "jpa"
+  ],
+  "homepage": "https://github.com/xoruddl/agentsmd-kit#readme",
+  "bugs": "https://github.com/xoruddl/agentsmd-kit/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xoruddl/agentsmd-kit.git",
+    "directory": "packages/preset-spring"
+  },
+  "license": "MIT",
+  "author": "이태경 (https://github.com/xoruddl)",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "files"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@agentsmd/core": "0.6.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
 }