uniare.sori.studio/AGENTS.md

# AGENTS.md

## 목적

이 파일은 이 프로젝트에서 작업하는 AI 에이전트(Codex, Claude Code 등)가 반드시 따라야 하는 공통 작업 규칙을 정의한다.

모든 작업은 본 문서의 지침을 우선 적용한다.


## 기본 응답 원칙

* 모든 대화, 설명, 보고, 문서 작성은 한국어로 작성한다.
* 사용자가 별도 형식을 요구하지 않는 한 답변은 짧고 명확하게 작성한다.
* 추측성 답변을 하지 않는다.
* 불확실한 내용은 반드시 불확실하다고 명시한다.
* 작업 완료를 선언하기 전에 실제 수정 파일과 문서 반영 여부를 다시 확인한다.


## 프로젝트 기본 원칙

* 운영 환경은 Docker Compose 기반으로 구성한다.
* 환경 변수는 반드시 `.env`로 관리한다.
* 운영 URL, API Key, 비밀번호, DB 정보는 하드코딩하지 않는다.
* 개발 환경과 운영 환경은 분리한다.
* 로컬 개발 DB와 운영 DB는 반드시 분리한다.
* 사람이 구조를 빠르게 이해할 수 있도록 작성한다.
* 유지보수성을 우선 고려한다.


## 문서 구조

```text
docs/

spec.md
todo.md

update.md
history.md

deploy.md
widget.md

map.md

changelog.md
convention.md
```


## 문서 역할

### spec.md

현재 무엇이 구현되어 있는가
기록한다.

포함 내용
* 기능 명세
* API 명세
* 데이터 구조
* 화면 동작
* 권한 정책

작업 로그는 기록하지 않는다.

---

### update.md

이번 작업에서 무엇을 수정했는가
기록한다.

예시
```md
# v0.0.3

- 로그인 API 추가.
- 회원가입 화면 수정.
- 비밀번호 검증 로직 개선.
```

개발자 작업 로그이다.

---

### history.md

왜 그렇게 구현했는가
기록한다.
작업 로그를 기록하지 않는다.

형식
```md
## YYYY-MM-DD vX.X.X — 한 줄 요약

💡 결정 이유
🔧 실제 적용 내용
```

예시
```md
## 2026-06-16 v1.5.105 — 텍스트 색상은 제한된 인라인 토큰으로 저장

💡 다크모드 색상 보정과 라이브 편집 직렬화를 통합 관리하기 위함.
🔧 `::red[텍스트]` 형식 채택, 지원 색상은 gray, blue, green, yellow, red, purple.
```

규칙
* 장문의 서술형 작성 금지
* 3~5줄 이내 작성
* 회의록 작성 금지
* 최신 항목이 항상 상단

---

### todo.md

앞으로 해야 할 작업만 기록한다.

규칙
* 완료된 작업은 즉시 제거
* 더 이상 필요 없는 작업 제거
* 현재 기준 유효한 작업만 유지

---

### deploy.md

운영 서버 배포 방법을 기록한다.
비개발자도 복사 후 실행만 하면 배포할 수 있어야 한다.

반드시 포함
* 프로젝트 위치
* Git 저장소 주소
* 환경 변수 위치
* 개발 실행 방법
* 빌드 방법
* Docker 실행 방법
* Docker 재시작 방법
* 운영 배포 방법
* 롤백 방법

---

### widget.md

외부 서비스 연동 방법을 기록한다.

목적
* Homepage 위젯
* Grafana
* RSS
* OpenAPI
* Discord
* Telegram
* Webhook

등 외부 서비스와 연결하는 방법 제공

규칙
* 실제 사용 가능한 URL 제공
* curl 예시 제공
* YAML 예시 제공
* Docker 환경 주의사항 제공
* 비개발자도 따라할 수 있도록 작성

---

### map.md

어느 파일이 어느 기능을 담당하는가
기록한다.

예시
```md
/deckHistory.html
deckHistory.html

/login.html
login.html

SiteHeader
style/brand.css
```

---

### changelog.md

사용자에게 공개할 변경사항을 기록한다.
공지사항 또는 업데이트 게시글로 바로 사용할 수 있어야 한다.

규칙
* 개발 로그 작성 금지
* 사용자 관점으로 작성
* 기능 추가 시 사용 방법 포함
* UI 변경 시 변경 이유 포함
* 복사 후 공지사항으로 바로 게시 가능한 수준으로 작성

예시
```md
## v1.5.109

### 추천 사이트 영역 위치 변경

추천 사이트 목록을 왼쪽 사이드바로 이동하였습니다.

### 사이드바 구조 개선

광고와 게시물 목차가 보다 안정적으로 표시되도록 개선하였습니다.
```

---

### convention.md

프로젝트 규칙만 기록한다.
반복적으로 적용되는 규칙만 기록한다.


## 문서 관계

```text
spec.md
현재 무엇이 구현되어 있는가

update.md
이번 작업에서 무엇을 수정했는가

history.md
왜 그렇게 구현했는가

todo.md
앞으로 무엇을 해야 하는가

deploy.md
어떻게 배포하는가

widget.md
외부 서비스와 어떻게 연동하는가

map.md
어느 파일이 어느 기능을 담당하는가

changelog.md
사용자 입장에서 무엇이 변경되었는가

convention.md
프로젝트에서 어떤 규칙을 따라야 하는가
```


## 문서 선참조 규칙

코드를 작성하거나 수정하기 전에 아래 문서를 먼저 확인한다.

```text
docs/spec.md
docs/todo.md
docs/history.md
docs/convention.md
docs/map.md
docs/deploy.md
```

문서와 코드가 충돌하면
1. 실제 코드를 확인한다.
2. 코드를 기준으로 판단한다.
3. 문서를 최신 상태로 수정한다.


## 작업 수행 절차

모든 작업은 아래 순서를 따른다.
1. 관련 문서 확인
2. 관련 코드 확인
3. 기존 패턴 파악
4. 최소 범위 수정
5. 검증 수행
6. 문서 갱신
7. 결과 정리


## 버전 관리 규칙

프로젝트 루트에 VERSION 파일을 유지한다.

예시
```text
v0.0.1
```

작업 완료 후 커밋 시 반드시 버전을 증가시킨다.

예시
```text
v0.0.1 → v0.0.2
v0.0.2 → v0.0.3
```

버전 변경 시 반드시 갱신
* VERSION
* docs/update.md
* docs/changelog.md (필요 시)

Git 커밋 메시지는 반드시 한국어로 작성한다.

예시
```text
회원가입 검증 로직 개선
게시물 관리 기능 추가
```

민감 정보는 절대 커밋하지 않는다.

예시
* API Key
* 비밀키
* 토큰
* 비밀번호
* 내부 서버 주소
* 개인정보


## Homepage API 규칙

서비스가 운영 단계에 진입하면 Homepage(getHomepage.dev) 연동용 API 제공을 고려한다.

기본 엔드포인트
```http
GET /api/homepage
```

기본 응답 예시
```json
{
  "status": "online",
  "version": "1.0.0",
  "lastUpdated": "2026-06-23T00:00:00+09:00"
}
```

추가 데이터는 서비스 특성에 맞게 설계한다.

예시
* 방문자 수
* 게시물 수
* 회원 수
* 주문 수
* 활성 사용자 수
* 서버 상태
* 스토리지 사용량
* 백업 상태

AI는 프로젝트 특성에 맞는 운영 지표를 제안해야 한다.
Homepage 위젯에서 사용할 수 있는 YAML 예시를 widget.md에 함께 작성한다.


## Docker 규칙

* Docker Compose 사용을 기본으로 한다.
* compose.yml 또는 docker-compose.yml 사용
* 가능한 경우 서비스 분리

예시
```text
app
db
redis
nginx
```

* 컨테이너 이름
* 포트
* 볼륨
* URL

은 환경 변수로 관리한다.

배포 문서에는 실제 서버에서 사용하는 명령어를 기록한다.
sudo 사용 여부는 서버 환경을 따른다.


## 코드 작성 규칙

### 공통

* 기존 코드 스타일을 우선 따른다.
* 불필요한 리팩토링 금지
* 요청받지 않은 대규모 구조 변경 금지
* 작은 수정으로 해결 가능한 문제를 전면 재구성하지 않는다.
* 의미 없는 이름 사용 금지
* 하드코딩 금지

---

### JavaScript

* JavaScript 사용 시 JSDoc 작성
* 함수 및 클래스는 문서화 주석 작성

예시

```javascript
/**
 * 게시물 목록 조회
 * @param {Object} options 조회 옵션
 * @returns {Promise<Array>}
 */
```

---

### 스타일

* Tailwind CSS를 기본으로 사용한다.
* Tailwind Utility Class를 우선 사용한다.
* 단순 스타일을 위해 별도 CSS 파일을 생성하지 않는다.
* 반복되는 스타일은 컴포넌트화 또는 공통 클래스화한다.
* 의미 없는 클래스명 사용 금지

금지 예시

```text
box1
box2
temp
test
```

* 의미 있는 고유 클래스명을 사용한다.
* 전역 스타일 사용을 최소화한다.
* 다크모드를 고려한다.
* 기본 폰트는 Pretendard를 사용한다.


## 검증 규칙

가능한 범위 내에서 반드시 검증한다.

예시

* 빌드 확인
* API 동작 확인
* 실패 케이스 확인

검증하지 못한 경우 명시한다.


## 작업 결과 보고 형식

반드시 아래 형식으로 보고한다.

1. 수정 내용
2. 변경 파일
3. 실행 방법
4. 빌드 방법
5. 배포 방법
6. 검증 결과
7. 문서 반영 여부
8. 남은 이슈


## 최종 체크리스트

* docs 확인 여부
* 코드 수정 완료 여부
* 검증 수행 여부
* VERSION 증가 여부
* update.md 기록 여부
* history.md 기록 여부
* deploy.md 갱신 여부
* widget.md 갱신 여부
* Homepage API 갱신 여부
* 문서 반영 여부
* 민감 정보 포함 여부
* Git 커밋 여부
* Git Push 여부