8.3 KiB
8.3 KiB
AGENTS.md
목적
이 파일은 이 프로젝트에서 작업하는 AI 에이전트(Codex 등)가 반드시 따라야 하는 공통 작업 규칙을 정의한다. 모든 작업은 본 문서의 지침을 우선 적용한다.
기본 응답 및 문서 원칙
- 모든 대화, 설명, 보고, 문서 작성은 반드시 한국어로 한다.
- 코드 내 주석은 반드시 JSDoc 형식으로 작성한다.
- 사용자가 별도 형식을 요구하지 않는 한, 답변은 짧고 명확하게 작성한다.
- AI가 사용자에게 보여주는 문서, 보고, 작업 요약에는 이모지를 가급적 사용하지 않는다.
- 추측성 답변을 하지 않는다. 불확실한 내용은 반드시 불확실하다고 명시한다.
- 작업 완료를 선언하기 전에 실제 수정 파일과 문서 반영 여부를 다시 확인한다.
프로젝트 기본 전제
- 기본 스타일링은 Tailwind CSS를 사용한다.
- 사이트 전역 기본 폰트는 반드시
Pretendard를 기준으로 유지한다. - 사람이 구조를 빠르게 파악할 수 있도록 의미 있는 고유 클래스명을 반드시 함께 부여한다.
- Nuxt SSR 기반으로 SEO 대응한다.
- JavaScript + JSDoc + Zod를 사용한다 (TypeScript 미사용).
- 세미콜론은 사용하지 않는다.
- 로컬 개발 DB와 NAS 운영 DB는 반드시 분리한다.
- 운영 설정, 경로, URL, 키값은 반드시 환경 변수로 관리한다.
작업 수행 절차 (필수)
모든 작업은 아래 순서를 반드시 따른다.
- docs/ 내 관련 문서를 먼저 읽는다.
- 작업 대상과 관련된 실제 코드 파일을 확인한다.
- 기존 구현 방식과 패턴을 파악한다.
- 작업 범위를 최소화하여 수정한다.
- 필요한 경우 검증을 수행한다.
- 작업 완료 후 문서를 즉시 갱신한다.
- 변경 누락이 없는지 다시 확인한 뒤 결과를 정리한다.
이 순서를 생략하거나 임의로 바꾸지 않는다.
문서 선참조 규칙
새로운 코드를 작성하거나 기존 코드를 수정하기 전, 반드시 아래 문서를 우선 참조한다.
- docs/update.md
- docs/todo.md
- docs/spec.md
- docs/convention.md
- docs/history.md
- docs/map.md
- docs/deploy.md
- docs/changelog.md
문서와 실제 코드가 충돌할 경우:
- 실제 코드를 기준으로 현재 상태를 확인한다.
- 필요한 수정을 진행한다.
- 관련 문서를 최신 상태로 맞춘다.
문서 자동 관리 규칙
모든 작업 수행 후, AI는 관련 내용을 아래 문서에 즉시 반영해야 한다.
작업 이력
- 파일: docs/update.md
- 수행한 작업 내용을 짧고 간략한 항목형으로 기록한다.
- 서술형 문장 대신
~추가.,~수정.,~정리.,~진행.형식을 우선 사용한다. - 같은 날 여러 번 수정하더라도 누적 관리한다.
- 버전 변경 작업은 버전을 명확히 기록한다.
- 날짜 기준이 아니라 버전 기준 섹션으로 구분한다.
- 가장 최신 버전 섹션이 항상 문서 상단에 오도록 유지한다.
할 일 및 이슈
- 파일: docs/todo.md
- 아직 해결되지 않은 문제를 기록한다.
- 다음 작업자가 바로 이어서 할 수 있도록 구체적으로 작성한다.
- 이미 구현된 항목은 즉시 삭제한다.
- 더 이상 필요 없는 항목도 즉시 삭제한다.
- 단순 누적이 아닌 현재 기준으로 유효한 작업만 유지한다.
기술 명세
- 파일: docs/spec.md
- API, 화면 동작, 데이터 구조 변경 시 반영한다.
- 외부 인터페이스가 바뀌면 반드시 갱신한다.
코딩 컨벤션
- 파일: docs/convention.md
- 반복적으로 적용되는 규칙만 기록한다.
의사결정 이력
- 파일: docs/history.md
- 구조 변경 및 중요한 기술 선택을 기록한다.
- 반드시 이유를 함께 남긴다.
docs/history.md는 서술형 기록을 허용한다.- 가장 최신 항목이 항상 문서 상단에 오도록 유지한다.
- 항목 제목에는 날짜와 버전을 함께 표시한다.
파일-화면 매핑
- 파일: docs/map.md
- 파일과 URL, 기능 연결 관계를 기록한다.
배포 가이드
- 파일: docs/deploy.md
공개 변경 요약
- 파일: docs/changelog.md
- 외부 공유용 변경 요약이 필요할 때만 간결하게 정리한다.
Git 및 버전 관리 규칙
- Git 작성자 정보는 프로젝트 기준 계정으로 통일한다.
- Git 작성자 이름은
zenn, 이메일은zenn.message@gmail.com을 사용한다. - 원격 저장소는
https://git.sori.studio/zenn/sori.studio.git을 사용한다. - 커밋 메시지는 반드시 한국어로 작성한다.
- 버전 변경 시 docs/update.md 먼저 반영한다.
- 작업이 끝나 변경사항을 커밋할 때마다 버전을 증가시킨다.
- 버전은
v0.0.1,v0.0.2처럼v접두사를 포함해 순차 증가시킨다. - 원격 저장소에 푸시하기 전 민감 정보 포함 여부를 반드시 확인한다.
- 커밋까지 완료한 작업은 사용자가 중단을 요청하지 않는 한
git push로 원격에 반영해 푸시 누락을 피한다.
민감 정보 예시:
- 실명
- 개인 이메일
- 비밀키 / 토큰
- 로컬 경로
- 내부 서버 주소
코드 작성 규칙
공통
- 기존 코드 스타일을 우선 따른다.
- 불필요한 리팩토링을 하지 않는다.
- 요청받지 않은 대규모 구조 변경을 하지 않는다.
- 작은 수정으로 해결 가능한 문제를 전면 재구성하지 않는다.
Vue / Nuxt
- layouts/default.vue, post.vue, admin.vue 사용
- components/site/: SiteHeader, LeftSidebar, RightSidebar, MainColumn, PostCard, TagHeader
- components/content/: ContentRenderer, ProseHeading, ProseImage, ProseList, ProseBlockquote, ProseButton, ProseCallout, ProseToggle, ProseVideo, ProseAudio, ProseFile, ProseProduct, ProseHeaderCard, ProseEmbed
- SSR이 필요한 공개 페이지는 Nuxt 서버 렌더링 우선
- 관리자 페이지는 기능보다 유지보수성과 단순성 우선
상태 관리
- 기존 상태 관리 방식을 따른다.
- 동일 데이터를 중복 관리하지 않는다.
- posts와 pages는 별도 관리 (목록 노출 여부 다름)
- pages는 헤더와 사이드바 없이 본문 중심 전체 화면으로 표시한다.
API / 데이터 처리
- 기존 API 호출 패턴을 따른다.
- 응답 구조 변경 시 docs/spec.md를 반드시 갱신한다.
- 하드코딩된 값 사용을 금지한다.
- 초기 백엔드는 별도 앱으로 분리하지 않고 Nuxt
server/api를 사용한다. - 개발 환경과 운영 환경의 데이터베이스 연결 문자열을 혼용하지 않는다.
- 운영 DB는 로컬 개발 서버에서 직접 사용하지 않는다.
스타일
- Tailwind CSS를 기본으로 사용한다.
- 임시 이름 사용을 금지한다.
네이밍 규칙
- 의미가 드러나는 이름을 사용한다.
- 축약어 남용을 금지한다.
- 임시 이름 사용을 금지한다.
주석 규칙
- JSDoc 형식으로 작성한다.
- 함수/클래스 앞에는 반드시 문서화 주석을 작성한다.
- 한국어로 작성한다.
/**
* 게시물 목록 조회
* @param {Object} options - 조회 옵션
* @param {number} options.page - 페이지 번호
* @param {number} options.limit - 페이지당 개수
* @returns {Promise<Post[]>} 게시물 목록
*/
검증 규칙
- 가능한 범위에서 검증을 수행한다.
- 실패 케이스를 확인한다.
- 검증하지 못한 경우 명시한다.
문서 업데이트 기준
- 기능 변경 → docs/spec.md
- 버그 수정 → docs/update.md
- 이슈 발견 → docs/todo.md
- 구조 변경 → docs/history.md
- 화면 변경 → docs/map.md
- 배포 변경 → docs/deploy.md
금지 사항
- docs 업데이트 누락
- 기존 스타일 무시
- 대규모 리팩토링
- 하드코딩 추가
- 민감 정보 커밋
- 검증 없이 완료 처리
의사결정 원칙
- 기존 패턴 우선
- 최소 수정
- 유지보수 용이성
- 구조 파악 용이성
작업 결과 보고 형식
- 수정 내용
- 변경 파일
- 검증 내용
- 문서 반영 여부
- 남은 이슈
최종 체크리스트
- docs 확인 여부
- 코드 수정 완료 여부
- 검증 수행 여부
- 문서 반영 여부
- 민감 정보 포함 여부