sodalive-vuejs-creator-admin/AGENTS.md

AGENTS.md

문서 목적

• 이 문서는 /Users/klaus/Develop/sodalive/Admin/soda-creator-admin 저장소에서 작업하는 에이전트용 실행 가이드다.
• 목표는 "추측 최소화 + 기존 패턴 준수 + 검증 우선"이다.
• 이 문서의 규칙은 코드/테스트/문서 변경 모두에 적용한다.

커뮤니케이션 규칙

• "질문에 대한 답변과 설명은 한국어로 한다."
• 이 저장소에서 사용자에게 전달하는 설명, 진행 상황, 결과 보고는 한국어로 작성한다.
• 코드 식별자, 경로, 명령어는 원문(영문) 그대로 유지한다.

커밋 메시지 규칙 (표준 Conventional Commits)

• 기본 형식은 <type>(scope): <description>를 사용한다.
• type은 소문자(feat, fix, chore, docs, refactor, test 등)를 사용한다.
• 제목(description)은 한글로 작성하고, 명령형/간결한 현재형으로 작성한다.

커밋 메시지 검증 절차

• git commit 실행 직전에 work/check-commit-message-rules.sh를 실행해 규칙 준수 여부를 확인한다.
• git commit 실행 직후에도 work/check-commit-message-rules.sh를 다시 실행해 최종 메시지를 재검증한다.
• 스크립트 결과가 [FAIL]이면 커밋 메시지를 규칙에 맞게 수정한 뒤 다시 검증한다.

작업 계획 문서 규칙 (docs)

• 모든 작업 시작 전에 docs 폴더 아래에 계획 문서를 먼저 생성하고, 해당 문서를 기준으로 구현을 진행한다.
• 기능 추가 중 발생한 오류 수정이나 보완 작업은 새로운 문서를 만들지 않고, 기존 기능 추가 계획 문서에 내용을 추가한다.
• 계획 문서 파일명은 [날짜]_구현할내용한글.md 형식을 사용한다.
• 날짜는 YYYYMMDD 8자리 숫자를 사용한다.
• 파일명 예시: 20260101_구글계정으로로그인.md
• 구현 항목은 기능/작업 단위로 분리해 체크박스(- [ ]) 목록으로 작성한다.
• 구현 완료 시마다 체크박스를 - [x]로 갱신하고, 각 항목이 정상 구현되었는지 확인한다.
• 작업 도중 범위가 변경되면 계획 문서의 체크박스 항목을 먼저 업데이트한 뒤 구현을 진행한다.
• 모든 구현이 끝난 후 결과 보고 시 계획 문서 맨 아래에 무엇을, 왜, 어떻게 검증했는지 한국어로 간단히 기록한다.
• 후속 수정이 발생해도 기존 검증 기록은 삭제/덮어쓰지 않고 누적한다(예: 1차 구현, 2차 수정).
• 검증 기록은 단계별로 무엇을/왜/어떻게를 유지해 작성하고, 이전 단계와 구분이 되도록 명시한다.
• 단계별 어떻게에는 실제 실행한 검증 명령과 결과(성공/실패/불가 사유)를 함께 기록한다.
• 기존 기록 정정이 필요하면 원문을 지우지 말고 정정 항목을 추가해 사유와 변경 내용을 남긴다.

에이전트 동작 원칙

• 추측하지 말고, 근거 파일을 읽고 결정한다.
• 기존 관례를 깨는 변경은 이유가 명확할 때만 수행한다.
• 불필요한 리팩터링 확장은 피하고 요청 범위를 우선 충족한다.
• 결과 보고 시 무엇을, 왜, 어떻게 검증했는지 한국어로 간단히 남긴다.