Haeyul Blog

2. 지시 문서

3 min read

지시 문서는 AI Agnet가 작업을 하기전에 보는 작업 설명서 같은 것입니다.

# Agent.md
 
## 프로젝트 개요
- 목적 : 실시간 맞춤법 교정 AI 백엔드 서버
- 언어 : Python 3.14
- 프레임 워크 : FastAPI
  
  
## 디렉토리 구조
src/  
├── api/ # 라우터만. 비즈니스 로직 금지  
├── services/ # 비즈니스 로직  
├── models/ # DB 모델  
└── utils/ # 순수 함수만
 
 
## 코드 규칙
- 함수명: snake_case
- 클래스명: PascalCase
- 한 함수는 하나의 역할만 수행한다
- 타입 힌트 필수
 
## 절대 금지
- `src/core/` 파일 수정 금지 (레거시, 건드리면 장애 발생)
- `print()` 사용 금지 → `logger.info()` 사용
- 직접 DB 쿼리 금지 → 반드시 서비스 레이어 경유
 
## PR 규칙
- PR 하나에 하나의 변경만
- 테스트 없는 PR은 올리지 않는다
 
## Commit Convention
- 커밋 메시지: conventional commit
- 사용 언어: 한국어
- 형식:
<타입>[적용 범위]: <1줄 설명>
 
## Test
- 테스트 파일 위치 : `tests/` 디렉토리
- 실행 명령 : `pytest tests/`
- 새 기능에는 반드시 테스트 추가

디렉토리별 지시 문서

프로젝트의 규모가 처시면 Agents.md 파일 하나로는 부족합니다. 다라서 각 디렉토리 마다 분리해줘야 합니다.

프로젝트 루트/
├── AGENTS.md          ← 전체 규칙
├── src/
│   ├── api/
│   │   └── AGENTS.md  ← API 레이어 전용 규칙
│   └── services/
│       └── AGENTS.md  ← 서비스 레이어 전용 규칙
└── tests/
    └── AGENTS.md      ← 테스트 작성 규칙

# src/api/AGENTS.md
 
## 이 디렉토리의 역할
라우터 정의만 담당합니다.
 
## 규칙
- 비즈니스 로직은 services/로 위임할 것
- 응답 형식은 항상 `ResponseModel`을 사용할 것
- 인증이 필요한 엔드포인트는 `@require_auth` 데코레이터 필수

자주 등장하는 실수

  • 너무 추상적인 규칙
- 읽기 좋은 코드를 작성한다.
- 좋은 네이밍을 사용한다.
  • 너무 구체적인 규칙
- 변수명은 역할을 명확히 드러낸다. (ex. `user_id`, not `id`)
- 불리언 변수는 `is_`, `has_` 접두사를 사용한다.

Graph View