sodalive-backend-spring-boot/docs/20260429_에이전트가이드통합정리.md

20260429 에이전트 가이드 통합 정리

구현 계획

• 기존 AGENTS.md의 우선순위, 에이전트 행동, 스킬/워크플로우 관련 항목을 분석한다.
• 공식 andrej-karpathy-skills CLAUDE.md 원문을 확인하고 삽입 위치와 래퍼 문구를 확정한다.
• AGENTS.md 상단 근처에 CORE EXECUTION PRINCIPLES (andrej-karpathy-skills) 섹션을 추가한다.
• 사용자 지시 > AGENTS.md > 프로젝트별 제약 조건 > oh-my-openagent > superpowers > 기본 모델 동작 우선순위를 명시한다.
• oh-my-openagent, superpowers, 충돌 해결 규칙, 실행 모드를 한국어 정책으로 추가한다.
• AGENTS.md에는 핵심 규칙만 남기고 세부 규칙은 docs/agent-guides/ 아래 별도 문서로 분리해 참조하도록 정리한다.
• 기존 docs/20260429_에이전트가이드상세규칙.md의 섹션 구성을 분석하고 분리 단위를 확정한다.
• docs/agent-guides/ 아래에 주제별 문서를 생성한다.
• AGENTS.md가 분리된 문서를 직접 참조하도록 수정한다.
• 기존 docs/20260429_에이전트가이드상세규칙.md를 제거한다.
• docs/agent-guides/ 하위 파일명에서 에이전트가이드 접두를 제거한 새 이름 규칙을 확정한다.
• docs/agent-guides/ 하위 파일명을 코드스타일.md, 테스트스타일.md, 설정보안.md, 작업절차.md, 문서유지보수.md로 정리한다.
• AGENTS.md와 연결된 작업 기록 문서의 참조 경로를 새 파일명 기준으로 갱신한다.
• 문서 변경 검증을 수행하고 결과를 기록한다.

검증 기록

• 작업 완료 후 검증 결과를 기록한다.

• 1차 구현

  • 무엇을: AGENTS.md에 명시적 지시 우선순위, CORE EXECUTION PRINCIPLES (andrej-karpathy-skills) 원문, oh-my-openagent/superpowers 제어 정책, 충돌 해결 규칙, 실행 모드를 추가했다. 동시에 Kotlin/Spring 스타일·테스트·보안·문서 유지보수의 상세 규칙은 docs/agent-guides/코드스타일.md, docs/agent-guides/테스트스타일.md, docs/agent-guides/설정보안.md, docs/agent-guides/작업절차.md, docs/agent-guides/문서유지보수.md로 분리하고 AGENTS.md는 핵심 규칙과 참조만 남기도록 정리했다.
  • 왜: 기존 AGENTS.md는 프로젝트 규칙은 충분했지만 명시적 우선순위 체계와 플러그인/스킬 통제 계층이 없었고, 세부 규칙이 길어져 상단에서 핵심 실행 원칙을 빠르게 파악하기 어려웠기 때문이다.
  • 어떻게: AGENTS.md, docs/20260429_에이전트가이드통합정리.md, docs/agent-guides/ 아래 분리 문서를 다시 읽어 필수 문구, 영어 원문 유지, 한국어 정책 분리, 참조 경로를 확인했다. lsp_diagnostics로 관련 문서 모두 No diagnostics found를 확인하고, ./gradlew tasks --all 실행 결과 BUILD SUCCESSFUL을 확인했다.

• 2차 정리

  • 무엇을: 동일 작업을 별도로 기록하던 docs/20260429_에이전트가이드분리.md의 구현 계획과 검증 범위를 이 문서로 통합하고, 중복 작업 문서는 제거했다.
  • 왜: 두 문서가 모두 같은 날짜의 동일 작업 흐름을 기록하고 있었고, 하나는 AGENTS.md 재구성, 다른 하나는 세부 규칙 분리라는 하위 단계만 다를 뿐 논리적으로 하나의 작업 계획 문서였기 때문이다.
  • 어떻게: 두 문서의 구현 계획과 검증 기록을 대조해 누락된 분리 작업 항목만 이 문서에 합쳤고, 이후 grep으로 두 문서명 참조를 확인한 뒤 중복 문서를 제거했다. 마지막으로 lsp_diagnostics와 ./gradlew tasks --all로 문서 정합성과 저장소 문서 검증 명령 성공을 다시 확인했다.

• 3차 정리

  • 무엇을: docs/agent-guides/ 하위 파일명에서 에이전트가이드 접두를 제거해 코드스타일.md, 테스트스타일.md, 설정보안.md, 작업절차.md, 문서유지보수.md로 정리했다. 함께 AGENTS.md와 이 문서의 참조 경로도 새 파일명 기준으로 수정했고, 별도 작업 문서였던 docs/20260429_agent_guides파일명정리.md는 이 문서로 통합했다.
  • 왜: 디렉터리 경로 자체가 이미 agent-guides라서 파일명에 동일한 의미를 반복할 필요가 없고, AGENTS 가이드 정비의 후속 단계 역시 별도 문서보다 하나의 연속 작업 기록 안에 남기는 편이 더 자연스럽기 때문이다.
  • 어떻게: grep으로 기존 docs/agent-guides/에이전트가이드*.md 참조가 남지 않았음을 확인했고, glob으로 새 파일명 5개만 존재함을 확인했다. lsp_diagnostics로 AGENTS.md, 이 문서, docs/agent-guides/ 전체에 대해 오류가 없음을 확인했고, ./gradlew tasks --all 실행 결과 BUILD SUCCESSFUL을 확인했다.