[global] AGENTS.md SOT 재구성 및 CLAUDE.md import 적용#323
Conversation
github-actions
Bot
requested review from
hongjm0912,
snowykte0426 and
wwwcomcomcomcom
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates AGENTS.md and CLAUDE.md to refine project documentation, tech stack details, and core development rules. The reviewer identified a Kotlin version inconsistency between AGENTS.md and CONTRIBUTING.md, and highlighted a discrepancy between the updated API response documentation and the repository's style guide regarding response wrapping.
AGENTS.md Core Rules에 있던 테스트(Kotest 구조)와 주석 작성 기준을 별도 rules 파일로 분리한다. AGENTS.md는 요약을 들고 있지 않고, rules 파일이 Single Source of Truth가 되도록 한다. - testing.md: Kotest DescribeSpec + MockK + Given-When-Then 구조와 한국어 명명 - comments.md: 주석 작성 기준과 안티패턴 예시
AGENTS.md의 Core Rules 요약 섹션은 계층/DI/불변성/null safety/트랜잭션/JPA처럼 Kotlin·Spring 모델이 이미 학습한 일반 컨벤션을 재선언하는 형태였다. 세부 규칙은 .claude/rules/에 있으므로 요약 섹션을 제거하고 Detailed Rules 참조만 남긴다.
Build/Test/Format은 일반 Gradle 사용법으로 모델이 이미 안다. ktlintFormat은 .claude/hooks/postToolUse.sh가 .kt 파일 저장 시 자동 실행하므로 명시 지시가 불필요하다. 프로젝트 고유 정보인 '실행 가능 모듈 목록'만 Runnable Modules 섹션으로 남긴다.
postToolUse hook이 .kt 파일 Edit/Write 시 자동으로 ktlintFormat을 실행한다. 명시 프롬프트로 두면 토큰만 차지하고 실효성이 없으므로 제거한다.
Claude Code는 .claude/rules/ 파일을 작업 컨텍스트에 따라 자동 로드한다. '규칙 파일을 직접 읽으세요'는 자동 주입과 이중 지시가 되어 rules 메커니즘의 의미를 퇴색시키므로 제거한다. 자동 로드된 규칙과 코드가 충돌할 때 규칙 파일을 보완 제안하라는 지시만 남긴다.
평균적으로 한국어 입력이 영어 대비 토큰 사용량이 2배 이상 증가한다. 사용자 상호작용 언어 정책(line 1 한국어 응답 지시)은 그대로 유지하면서 본문 설명만 영어로 옮겨 토큰 효율을 개선한다.
| - Common Entity: `datagsm-common/src/main/kotlin/.../domain/` | ||
| - Exception Handler: `datagsm-common/.../global/common/error/` | ||
| - API Response: Use `CommonApiResponse` wrapper | ||
| - `.claude/rules/`의 세부 규칙은 Claude Code가 작업 컨텍스트에 맞춰 자동 로드합니다. 자동 로드된 규칙과 충돌하는 코드를 발견하면 단순 수정에 그치지 말고 규칙 파일에 누락된 항목이 있는지 점검하고 보완을 제안하세요. No newline at end of file |
There was a problem hiding this comment.
사용자 상호작용 규칙에 따른다고 하셨는데 사실 이해가 되지 않습니다. 해당 내용도 한국어로 유지할 이유가 있을까요
There was a problem hiding this comment.
kotest-guide 같은 스킬이 존재하는데 충돌하는 것 같습니다. 테스트 컨벤션을 rule로 정의한다면 차라리 path 프론트매터를 추가하는게 좋을 것 같습니다.
| ## Runnable Modules | ||
|
|
||
| ## Coding Conventions | ||
| Modules launched via `./gradlew :<module>:bootRun`: `datagsm-oauth-authorization`, `datagsm-oauth-userinfo`, `datagsm-openapi`, `datagsm-web`. (`datagsm-common` is a library module and is not run directly.) | ||
|
|
There was a problem hiding this comment.
Gradle 사용법을 재차 알려줄 필요는 없을 것 같습니다
wwwcomcomcomcom
left a comment
wwwcomcomcomcom
left a comment
There was a problem hiding this comment.
AGENTS.md를 SOT(Single Source of Truth)로 재구성하고 CLAUDE.md에서 import하는 구조가 명확합니다. comments.md, testing.md 규칙 파일 추가 및 Kotlin 버전 정보 수정도 적절합니다. LGTM
3 participants
개요
AGENTS.md와CLAUDE.md를 Anthropic 공식 메모리 가이드와 HumanLayer의 CLAUDE.md 베스트 프랙티스에 맞춰 재구성하였습니다.AGENTS.md를 단일 진실 소스(SOT)로 두고CLAUDE.md는@AGENTS.mdimport + Claude Code 전용 지시만 남겼으며, 두 파일의 부정확한 서술과 중복 지시를 정정하였습니다.본문
구조 재설계
AGENTS.md를 SOT로 두고CLAUDE.md는 첫 줄에@AGENTS.md로 import하도록 변경하였습니다. 이는 Anthropic 공식 문서가 권장하는 패턴으로, 두 파일에 동일 내용을 중복 유지하던 문제를 제거하였습니다..claude/rules/에 분리되어 있어,AGENTS.md본문에서 상세 규칙을 빼고 인덱스만 남겼습니다.부정확한 내용 정정
datagsm-openapi모듈 설명을 "Public read-only API"에서 "외부 공개 API (API Key 인증)"로 수정하였습니다. 실제ProjectController,ClubController,StudentController,WebhookController에POST/PUT/DELETE엔드포인트가 존재합니다.project,webhook등)을 모듈 설명에 추가하였습니다.Spring Boot 4.0표기를 실제 버전인Spring Boot 4.0.3으로 수정하고Kotlin 2.3.10을 명시하였습니다..../domain/경로를 풀 패키지 경로로 수정하였습니다.셀프 리뷰 후 추가 정정
문서 재작성 직후 셀프 리뷰를 통해 발견한 7가지 문제를 각각 별도 커밋으로 수정하였습니다.
.geminiignore파일 언급 제거AGENTS.md와 중복되는 한국어 응답 지시 제거commit스킬이ktlintFormat을 자동 실행하지 않으므로, 사용자 직접 실행 안내로 정정CommonApiResponse설명을 실제 동작에 맞게 정정 (ResponseBodyAdvice가 없고, 컨트롤러는 DTO를 직접 반환하며GlobalExceptionHandler만 명시적으로 래핑함을 확인)참고