@agentsmd/preset-java 0.0.0-stage → 0.2.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,12 @@
-# Temporary Holding Version
+# @agentsmd/preset-java
 
-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)의 Java·Gradle 프리셋입니다.
+
+```bash
+npx @agentsmd/cli init --preset git,java   # Git 작업 규칙과 함께
+npx @agentsmd/cli init --preset java       # Java 규칙만
+```
+
+- Java 코드 규칙 문서: 코드 스타일, 클린 코드 원칙과 예시, Java 체크리스트
+- palantir-java-format(Spotless) 커밋 검사, Gradle CI
+- Git 작업 규칙은 [Git 프리셋](https://www.npmjs.com/package/@agentsmd/preset-git)을 함께 고르면 더해집니다. `AGENTS.md`는 고른 프리셋에 맞춰 만들어집니다.

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Java·Gradle 프로젝트용 프리셋.
+ *
+ * Java 코드 규칙 문서, Spotless(palantir-java-format) 커밋 검사, Gradle CI를 담는다.
+ * Git 작업 규칙은 Git 프리셋을 함께 고르면 더해진다.
+ * `files/`는 빌드 결과(dist/)와 소스(src/) 어디서 실행해도 패키지 루트 기준으로 같은 위치다.
+ */
+export declare const javaPreset: {
+    name: string;
+    description: string;
+    filesDir: string;
+    hooksPath: string;
+    docs: {
+        path: string;
+        when: string;
+    }[];
+    rules: string[];
+    verify: 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;;;;;;GAMG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;CA0BL,CAAC"}

package/dist/index.js

@@ -0,0 +1,36 @@
+import { fileURLToPath } from "node:url";
+/**
+ * Java·Gradle 프로젝트용 프리셋.
+ *
+ * Java 코드 규칙 문서, Spotless(palantir-java-format) 커밋 검사, Gradle CI를 담는다.
+ * Git 작업 규칙은 Git 프리셋을 함께 고르면 더해진다.
+ * `files/`는 빌드 결과(dist/)와 소스(src/) 어디서 실행해도 패키지 루트 기준으로 같은 위치다.
+ */
+export const javaPreset = {
+    name: "java",
+    description: "Java·Gradle 프로젝트용 지침, 커밋 훅, Spotless·Gradle CI",
+    filesDir: fileURLToPath(new URL("../files", import.meta.url)),
+    // Spotless 검사(pre-commit.d/spotless)를 연결한다.
+    hooksPath: ".githooks",
+    docs: [
+        {
+            path: "docs/project-direction.md",
+            when: "모든 작업 시작 전 (필수). 범위 밖 작업이면 먼저 질문",
+        },
+        { path: "docs/code-style.md", when: "코드 작성, 주석" },
+        { path: "docs/clean-code.md", when: "코드 작성, 설계" },
+        { path: "docs/clean-code-examples.md", when: "코드 작성 시 참고 예시" },
+        { path: "docs/java-checklist.md", when: "Java 코드 작성·리뷰" },
+        { path: "docs/lint-and-ci.md", when: "훅·린트·CI 설정" },
+    ],
+    rules: [
+        "코드에는 의도를 설명하는 주석을 적극적으로 단다.",
+        "포맷은 손으로 맞추지 않는다. 커밋 전 `./gradlew spotlessApply`.",
+    ],
+    verify: "./gradlew spotlessCheck build",
+    nextSteps: [
+        "docs/project-direction.md 에 프로젝트 목표와 범위를 채우세요.",
+        "Gradle 프로젝트라면 docs/lint-and-ci.md 의 Spotless 설정을 build.gradle.kts 에 추가하세요.",
+    ],
+};
+//# 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;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,IAAI,EAAE,MAAM;IACZ,WAAW,EAAE,gDAAgD;IAC7D,QAAQ,EAAE,aAAa,CAAC,IAAI,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7D,4CAA4C;IAC5C,SAAS,EAAE,WAAW;IACtB,IAAI,EAAE;QACJ;YACE,IAAI,EAAE,2BAA2B;YACjC,IAAI,EAAE,kCAAkC;SACzC;QACD,EAAE,IAAI,EAAE,oBAAoB,EAAE,IAAI,EAAE,WAAW,EAAE;QACjD,EAAE,IAAI,EAAE,oBAAoB,EAAE,IAAI,EAAE,WAAW,EAAE;QACjD,EAAE,IAAI,EAAE,6BAA6B,EAAE,IAAI,EAAE,eAAe,EAAE;QAC9D,EAAE,IAAI,EAAE,wBAAwB,EAAE,IAAI,EAAE,eAAe,EAAE;QACzD,EAAE,IAAI,EAAE,qBAAqB,EAAE,IAAI,EAAE,YAAY,EAAE;KACpD;IACD,KAAK,EAAE;QACL,6BAA6B;QAC7B,kDAAkD;KACnD;IACD,MAAM,EAAE,+BAA+B;IACvC,SAAS,EAAE;QACT,gDAAgD;QAChD,4EAA4E;KAC7E;CACe,CAAC"}

package/files/.githooks/pre-commit.d/spotless

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+#
+# Java 포맷 검사. 공통 pre-commit 훅이 실행한다.
+# Gradle 프로젝트가 붙어 있고 Java 파일이 스테이징됐을 때만 spotlessCheck 를 돌린다.
+# 규칙: docs/lint-and-ci.md
+
+set -euo pipefail
+
+if [ -x ./gradlew ] && git diff --cached --name-only | grep -q '\.java$'; then
+  if ! ./gradlew -q spotlessCheck; then
+    echo "pre-commit: 포맷 위반. ./gradlew spotlessApply 후 다시 스테이징하세요." >&2
+    exit 1
+  fi
+fi

package/files/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+# 규칙: docs/lint-and-ci.md
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  # 커밋 규칙(파일 수, 메시지 형식)은 CI 에서 막지 않는다. 로컬 훅만 검사한다.
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      # 지침 전용 저장소일 때는 Gradle 프로젝트가 없으므로 빌드를 건너뛴다.
+      - name: Gradle 프로젝트 확인
+        id: detect
+        run: |
+          if [ -f gradlew ]; then echo "gradle=true" >> "$GITHUB_OUTPUT"; fi
+
+      - uses: actions/setup-java@v6
+        if: steps.detect.outputs.gradle == 'true'
+        with:
+          distribution: temurin
+          java-version: 21
+
+      - uses: gradle/actions/setup-gradle@v6
+        if: steps.detect.outputs.gradle == 'true'
+
+      - name: 포맷 검사 + 빌드
+        if: steps.detect.outputs.gradle == 'true'
+        run: ./gradlew spotlessCheck build

package/files/docs/clean-code-examples.md

@@ -0,0 +1,179 @@
+# 클린 코드 예시
+
+원칙은 [clean-code.md](clean-code.md).
+
+## 조기 반환
+
+```java
+// Bad
+public int discount(Member member) {
+    if (member != null) {
+        if (member.isActive()) {
+            return member.isVip() ? 20 : 10;
+        }
+    }
+    return 0;
+}
+
+// Good
+public int discount(Member member) {
+    if (member == null || !member.isActive()) {
+        return 0;
+    }
+    return member.isVip() ? VIP_RATE : DEFAULT_RATE;
+}
+```
+
+## 매직 넘버
+
+```java
+// Bad
+if (password.length() < 8) { ... }
+
+// Good
+/** 보안 정책 v2 기준 최소 길이. */
+private static final int MIN_PASSWORD_LENGTH = 8;
+
+if (password.length() < MIN_PASSWORD_LENGTH) { ... }
+```
+
+## boolean 플래그 파라미터
+
+```java
+// Bad
+sendMail(user, true);
+
+// Good
+sendWelcomeMail(user);
+sendReminderMail(user);
+```
+
+## Tell, Don't Ask
+
+```java
+// Bad
+if (order.getStatus() == Status.PAID && order.getPaidAt().isAfter(limit)) {
+    order.setStatus(Status.CANCELED);
+}
+
+// Good
+order.cancel(limit);
+```
+
+## 원시 값 포장
+
+```java
+// Bad
+public void register(String email) {
+    if (!email.contains("@")) throw new IllegalArgumentException();
+    ...
+}
+
+// Good
+public record Email(String value) {
+    public Email {
+        if (value == null || !value.contains("@")) {
+            throw new InvalidEmailException(value);
+        }
+    }
+}
+```
+
+## 예외 처리
+
+```java
+// Bad
+try {
+    payment.approve();
+} catch (Exception e) {
+}
+
+// Good
+try {
+    payment.approve();
+} catch (PgTimeoutException e) {
+    // PG 타임아웃은 승인 여부가 불확실하므로 조회 후 재처리 대상에 넣는다.
+    throw new PaymentPendingException(payment.id(), e);
+}
+```
+
+## SRP
+
+```java
+// Bad: 주문 저장, 메일 발송, 포인트 적립이 한 클래스에
+class OrderManager {
+    void order(...) { save(); sendMail(); addPoint(); }
+}
+
+// Good: 책임별로 나누고 조합
+class OrderService {
+    private final OrderRepository orders;
+    private final OrderNotifier notifier;
+    private final PointRewarder rewarder;
+}
+```
+
+## OCP (타입별 분기 제거)
+
+```java
+// Bad: 결제 수단 추가마다 switch 수정
+int fee(PayType type, int amount) {
+    switch (type) {
+        case CARD: return amount * 3 / 100;
+        case BANK: return 500;
+        default: throw new IllegalArgumentException();
+    }
+}
+
+// Good: 새 수단은 구현체만 추가
+interface FeePolicy {
+    int fee(int amount);
+}
+
+class CardFeePolicy implements FeePolicy {
+    public int fee(int amount) { return amount * 3 / 100; }
+}
+```
+
+## LSP
+
+```java
+// Bad: 상위 계약을 깨는 하위 타입
+class ReadOnlyList<E> extends ArrayList<E> {
+    @Override public boolean add(E e) { throw new UnsupportedOperationException(); }
+}
+
+// Good: 필요한 계약만 가진 타입을 쓴다
+List<E> items = List.copyOf(source);
+```
+
+## ISP
+
+```java
+// Bad
+interface Worker { void work(); void eat(); }
+class Robot implements Worker { public void eat() { } } // 빈 구현
+
+// Good
+interface Workable { void work(); }
+interface Eatable { void eat(); }
+class Robot implements Workable { ... }
+```
+
+## DIP
+
+```java
+// Bad: 구체 클래스를 직접 생성
+class OrderService {
+    private final MySqlOrderRepository repository = new MySqlOrderRepository();
+}
+
+// Good: 추상에 의존, 생성자 주입
+class OrderService {
+    private final OrderRepository repository;
+
+    OrderService(OrderRepository repository) {
+        this.repository = repository;
+    }
+}
+```

package/files/docs/clean-code.md

@@ -0,0 +1,48 @@
+# 클린 코드 + SOLID
+
+코드 작성·리뷰 시 체크리스트. 예시는 [clean-code-examples.md](clean-code-examples.md).
+Java 는 [java-checklist.md](java-checklist.md) 를 함께 본다. 겹치면 그쪽이 우선한다.
+
+## 함수
+
+- 한 가지 일만 한다. 이름으로 설명이 안 되면 쪼갠다.
+- 20줄 이내 권장. 들여쓰기 2단계 이내.
+- 파라미터 3개 이하. 넘으면 객체로 묶는다.
+- 조기 반환(guard clause)으로 중첩을 줄인다.
+- 부수효과를 숨기지 않는다. 조회 메서드는 상태를 바꾸지 않는다.
+- boolean 플래그 파라미터 금지. 메서드를 나눈다.
+
+## 값과 상태
+
+- 매직 넘버·문자열은 상수나 enum 으로.
+- 불변을 기본으로. 필드는 `final`, 컬렉션은 방어적 복사.
+- null 반환 대신 `Optional` 또는 빈 컬렉션.
+- 원시 값 대신 의미 있는 타입. (`String email` → `Email`)
+
+## 객체
+
+- 데이터를 꺼내서 판단하지 말고 객체에 시킨다. (Tell, Don't Ask)
+- 디미터 법칙: `a.getB().getC().do()` 금지.
+- getter/setter 기계적 생성 금지. 필요한 것만.
+
+## 예외
+
+- 예외를 삼키지 않는다. 빈 catch 금지.
+- 의미 있는 커스텀 예외로 감싼다. 원인(cause)을 유지한다.
+- 에러 코드 반환 대신 예외.
+
+## SOLID
+
+| 원칙 | 규칙 | 신호 |
+| --- | --- | --- |
+| SRP 단일 책임 | 클래스가 바뀌는 이유는 하나 | 클래스 이름에 `And`, `Manager`, `Util` |
+| OCP 개방-폐쇄 | 기능 추가 시 기존 코드 수정 없이 확장 | 타입별 `if/switch` 가 여러 곳에 반복 |
+| LSP 리스코프 치환 | 하위 타입은 상위 타입 계약을 지킨다 | 오버라이드에서 `UnsupportedOperationException` |
+| ISP 인터페이스 분리 | 클라이언트가 안 쓰는 메서드에 의존하지 않게 | 빈 구현 메서드 |
+| DIP 의존 역전 | 구체 클래스가 아니라 추상에 의존 | 내부에서 `new` 로 협력 객체 생성 |
+
+## 과설계 방지
+
+- 구현체가 하나뿐이고 교체 계획이 없으면 인터페이스를 만들지 않는다.
+- 패턴은 문제가 보일 때 적용한다. 미리 넣지 않는다.
+- 세 번 반복되면 추출한다. 두 번은 참는다.

package/files/docs/code-style.md

@@ -0,0 +1,62 @@
+# 코드 스타일
+
+## 포맷
+
+- palantir-java-format (Spotless). 들여쓰기 공백 4칸, 줄 길이 120. 수동 정렬하지 않는다.
+- 커밋 전 `./gradlew spotlessApply`. pre-commit 훅이 `spotlessCheck` 를 돌린다.
+- 설정은 [lint-and-ci.md](lint-and-ci.md).
+
+## 네이밍
+
+| 대상 | 규칙 | 예 |
+| --- | --- | --- |
+| 클래스 | 명사, PascalCase | `OrderCanceler` |
+| 메서드 | 동사, camelCase | `cancelOrder()` |
+| boolean | `is/has/can` 접두 | `isCancelable()` |
+| 상수 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
+| 컬렉션 | 복수형 | `orders` |
+
+- 축약어 금지. (`ord`, `mgr`, `tmp`)
+- 타입을 이름에 넣지 않는다. (`orderList` → `orders`)
+
+## 주석
+
+주석은 적극적으로 단다. 단, 코드를 반복하지 말고 **의도와 이유**를 쓴다.
+
+필수:
+
+- public 클래스·메서드: Javadoc. 역할, 파라미터 제약, 반환값, 예외.
+- 비즈니스 규칙·정책 값: 출처나 이유.
+- 비자명한 로직: 왜 이렇게 했는지.
+- 우회 코드: 원인과 제거 조건.
+
+형식:
+
+- TODO: `// TODO(작성자): 내용 #이슈번호`
+- 한 줄 주석은 대상 코드 바로 위에.
+
+금지:
+
+- 코드를 그대로 읽는 주석 (`// i 증가`)
+- 주석 처리된 코드
+- 변경 이력 주석 (git 이 한다)
+
+```java
+/**
+ * 주문을 취소한다.
+ *
+ * @param orderId 취소할 주문 ID. null 불가
+ * @throws OrderNotCancelableException 결제 후 24시간이 지난 경우
+ */
+public void cancel(Long orderId) {
+    Order order = orderRepository.getById(orderId);
+
+    // 정산이 결제 후 24시간 시점에 확정되므로 그 이후 취소는 환불 절차로 처리한다.
+    if (order.isPaidBefore(CANCEL_LIMIT)) {
+        throw new OrderNotCancelableException(orderId);
+    }
+    order.cancel();
+}
+```
+
+설계 원칙은 [clean-code.md](clean-code.md), 예시는 [clean-code-examples.md](clean-code-examples.md).

package/files/docs/java-checklist.md

@@ -0,0 +1,113 @@
+# 자바 클린 코드 체크리스트
+
+Java 코드 작성·리뷰 시 확인한다. [clean-code.md](clean-code.md) 와 겹치면 이 문서가 우선한다.
+
+| # | 체크 항목 |
+| --- | --- |
+| 1 | 자바 코드 컨벤션을 지켰는가 |
+| 2 | 메서드 들여쓰기가 1단계인가 |
+| 3 | `else` 를 쓰지 않았는가 |
+| 4 | 원시값과 문자열을 포장했는가 |
+| 5 | 컬렉션에 일급 컬렉션을 적용했는가 |
+| 6 | 인스턴스 변수가 2개 이하인가 |
+| 7 | 도메인 객체에 getter/setter 가 없는가 |
+| 8 | 메서드 인자가 3개 이하인가 |
+| 9 | 한 줄에 점(`.`)이 하나인가 |
+| 10 | 메서드가 한 가지 일만 하는가 |
+| 11 | 클래스가 작은가 |
+
+## 1. 자바 코드 컨벤션
+
+- [palantir-java-format](https://github.com/palantir/palantir-java-format) 스타일을 따른다. Google Java Style 기반이고 들여쓰기 4칸, 줄 길이 120 이다.
+- IntelliJ 는 palantir-java-format 플러그인으로 포맷팅한다.
+- 포맷은 손으로 맞추지 않는다. 최종 판정은 `spotlessCheck`. → [lint-and-ci.md](lint-and-ci.md)
+
+## 2. 들여쓰기 1단계
+
+- 메서드 안의 들여쓰기는 1단계만 허용한다.
+- 중첩이 생기면 안쪽 블록을 메서드로 추출한다.
+
+## 3. else 금지
+
+- `else` 를 쓰지 않는다. 조기 반환으로 바꾼다.
+
+```java
+// 나쁨
+if (score >= 60) {
+    return PASS;
+} else {
+    return FAIL;
+}
+
+// 좋음
+if (score >= 60) {
+    return PASS;
+}
+return FAIL;
+```
+
+## 4. 원시값·문자열 포장
+
+- 의미 있는 원시값과 문자열은 클래스로 포장한다.
+- 검증 로직은 포장 클래스 생성자에 둔다.
+
+```java
+public class Money {
+    private final int amount;
+
+    public Money(int amount) {
+        // 음수 금액은 도메인상 존재할 수 없으므로 생성 시점에 막는다.
+        if (amount < 0) {
+            throw new IllegalArgumentException("금액은 0 이상이어야 한다.");
+        }
+        this.amount = amount;
+    }
+}
+```
+
+## 5. 일급 컬렉션
+
+- 컬렉션은 그 컬렉션만 필드로 가진 클래스로 감싼다.
+- 컬렉션 관련 로직(검증, 합계, 필터)은 일급 컬렉션 안에 둔다.
+
+```java
+public class Lottos {
+    private final List<Lotto> lottos;
+
+    public Lottos(List<Lotto> lottos) {
+        this.lottos = List.copyOf(lottos);
+    }
+
+    public int countWinning(WinningNumbers winning) { ... }
+}
+```
+
+## 6. 인스턴스 변수 2개 이하
+
+- 3개 이상의 인스턴스 변수를 가진 클래스를 만들지 않는다.
+- 어렵다면 최소한 줄이려고 시도한다. 관련 있는 필드끼리 객체로 묶는다.
+
+## 7. getter/setter 금지
+
+- 핵심 로직을 담은 도메인 객체에는 getter/setter 를 쓰지 않는다.
+- 값을 꺼내 판단하지 않고 객체에 메시지를 보낸다.
+- DTO 는 허용한다.
+
+## 8. 메서드 인자 3개 이하
+
+- 4개 이상의 인자는 허용하지 않는다.
+- 3개도 줄일 수 있는지 먼저 검토한다.
+
+## 9. 한 줄에 점 하나
+
+- 디미터 법칙("친구하고만 대화하라")을 지킨다.
+- `location.current.representation.substring(0, 1)` 처럼 점이 여러 개면 리팩터링 대상을 찾는다.
+
+## 10. 메서드는 한 가지 일만
+
+- 메서드 이름으로 하는 일이 다 설명되지 않으면 나눈다.
+
+## 11. 작은 클래스
+
+- 클래스를 작게 유지한다.
+- 클래스가 커지면 책임을 나눌 수 있는지 먼저 본다.

package/files/docs/lint-and-ci.md

@@ -0,0 +1,52 @@
+# 훅 · 린트 · CI
+
+## Git 훅
+
+`.githooks/pre-commit` 이 `.githooks/pre-commit.d/` 의 검사를 이름 순서로 실행한다.
+Java 프리셋은 포맷 검사를 넣는다. Git 프리셋을 함께 설치했다면 커밋 형식·파일 수 검사도 같이 돈다.
+
+| 파일 | 검사 |
+| --- | --- |
+| `.githooks/pre-commit.d/spotless` | `gradlew` 가 있고 `.java` 가 스테이징됐으면 `spotlessCheck` |
+
+- 클론한 뒤 훅이 동작하지 않으면 `git config core.hooksPath .githooks` 로 연결한다.
+- `--no-verify` 금지.
+
+## 린트 (Spotless + palantir-java-format)
+
+프로젝트에 Gradle 을 붙일 때 `build.gradle.kts` 에 추가한다.
+
+palantir-java-format 은 Google Java Style 을 바탕으로 들여쓰기 4칸, 줄 길이 120 을 쓴다.
+
+```kotlin
+plugins {
+    java
+    id("com.diffplug.spotless") version "8.10.4"
+}
+
+spotless {
+    java {
+        target("src/**/*.java")
+        palantirJavaFormat("2.103.0")
+        removeUnusedImports()
+        trimTrailingWhitespace()
+        endWithNewline()
+    }
+}
+```
+
+| 명령 | 용도 |
+| --- | --- |
+| `./gradlew spotlessApply` | 포맷 적용 |
+| `./gradlew spotlessCheck` | 포맷 검사 (훅, CI) |
+
+## CI
+
+[.github/workflows/ci.yml](../.github/workflows/ci.yml)
+
+| job | 실행 | 검사 |
+| --- | --- | --- |
+| `build` | PR, main push | `spotlessCheck build`. `gradlew` 없으면 건너뜀 |
+
+- 커밋 규칙(파일 수, 메시지 형식)은 CI 에서 검사하지 않는다. 로컬 훅만 검사한다.
+- 버전을 올릴 때는 이 문서의 스니펫과 CI 를 같이 고친다.

package/files/docs/project-direction.md

@@ -0,0 +1,54 @@
+# 프로젝트 방향
+
+<!--
+작성 규칙:
+- 사람이 채운다. 에이전트는 사용자 요청 없이 이 문서를 고치지 않는다.
+- 각 섹션은 3~5줄 불릿. 채울 내용이 없으면 섹션을 지운다.
+- 방향이 바뀌면 이 문서부터 고친다.
+-->
+
+## 목표
+
+<!-- 이 프로젝트가 해결하는 문제. 한 줄 요약 + 핵심 목표 -->
+
+-
+
+## 범위
+
+<!-- 이번 단계에서 만드는 것 -->
+
+-
+
+## 하지 않는 것
+
+<!-- 범위 밖. 에이전트가 임의로 추가하지 않도록 명시한다 -->
+
+-
+
+## 기술 스택
+
+| 구분 | 선택 | 이유 |
+| --- | --- | --- |
+| 언어 | | |
+| 프레임워크 | | |
+| 빌드 | | |
+| DB | | |
+
+## 설계 원칙
+
+<!-- 판단이 갈릴 때 따르는 우선순위. 예: 성능보다 가독성 -->
+
+-
+
+## 진행 단계
+
+| 단계 | 내용 | 상태 |
+| --- | --- | --- |
+| 1 | | 진행 중 |
+
+## 결정 기록
+
+<!-- 방향에 영향을 준 결정. 날짜와 이유를 한 줄로 -->
+
+| 날짜 | 결정 | 이유 |
+| --- | --- | --- |

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@agentsmd/preset-java",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Java·Gradle 프로젝트용 AI 작업 지침 프리셋 (코드 규칙 문서, Spotless 커밋 검사, Gradle CI)",
+  "keywords": [
+    "agents.md",
+    "ai-agent",
+    "java",
+    "gradle",
+    "spotless"
+  ],
+  "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-java"
+  },
+  "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.2.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
 }