# 신규 프로젝트, Codex 스킬, 프로젝트별 데이터베이스 설계

> https://bookfactory.kr/board/publishers/28971
> 게시판: 출판사 공지수집
> 작성자: admin
> 작성일: 2026-05-04 13:59:25

---

```
# 프로젝트 문서 작성 가이드

작성일: 2026-05-04  
적용 대상: 신규 프로젝트, Codex 스킬, 프로젝트별 데이터베이스 설계

## 목적

이 문서는 프로젝트를 새로 만들 때 반드시 남겨야 할 개발 문서의 기준을 정의한다. 핵심은 프로젝트 구조, 사용하는 스킬, 데이터베이스 구성, 그리고 설계 시 결정한 내용을 나중에 다시 추적할 수 있게 정리하는 것이다.

문서는 단순 설명이 아니라 다음 역할을 해야 한다.

- 새 개발자가 프로젝트를 빠르게 이해할 수 있게 한다.
- 프로젝트 생성 당시의 설계 의도와 제약을 남긴다.
- 스킬, 자동화, 외부 도구가 어떤 책임을 갖는지 구분한다.
- 데이터베이스 테이블, 관계, 인덱스, 마이그레이션 기준을 명확히 한다.
- 향후 리팩터링이나 기능 추가 시 기존 설계를 검증할 기준이 된다.

## 권장 문서 구조

프로젝트 루트에는 최소한 다음 문서를 둔다.

| 문서 | 목적 |
| --- | --- |
| `README.md` | 프로젝트 개요, 실행 방법, 핵심 기능 |
| `docs/ARCHITECTURE.md` | 전체 구조, 모듈 책임, 주요 흐름 |
| `docs/DESIGN_NOTES.md` | 설계 결정, 대안, 선택 이유 |
| `docs/SKILLS.md` | 프로젝트에서 사용하는 Codex 스킬과 자동화 규칙 |
| `docs/DATABASE.md` | DB 구조, 테이블, 관계, 마이그레이션 정책 |
| `docs/RESOURCE_MAP.md` | 개발 리소스, 외부 API, 파일/폴더 역할 |
| `docs/CHANGELOG.md` | 주요 변경 이력 |

작은 프로젝트라면 `README.md`와 `docs/DATABASE.md`만 먼저 만들고, 구조가 커질 때 나머지를 분리한다.

## README.md 작성 기준

`README.md`는 실행과 이해를 위한 첫 진입점이다.

반드시 포함할 내용:

- 프로젝트 이름
- 프로젝트 목적
- 주요 기능
- 기술 스택
- 실행 방법
- 환경 변수
- 폴더 구조 요약
- 관련 문서 링크

예시:

```md
# 프로젝트명

## 개요

이 프로젝트는 ...

## 주요 기능

- ...
- ...

## 기술 스택

- Frontend:
- Backend:
- Database:
- Infra:

## 실행 방법

```bash
...
```

## 문서

- [아키텍처](docs/ARCHITECTURE.md)
- [데이터베이스](docs/DATABASE.md)
- [스킬 구성](docs/SKILLS.md)
```

## ARCHITECTURE.md 작성 기준

`ARCHITECTURE.md`는 전체 프로그램 구조와 책임 경계를 설명한다.

포함할 내용:

- 전체 시스템 구성
- 주요 모듈별 책임
- 데이터 흐름
- 외부 서비스 연동
- 프론트엔드/백엔드/DB 경계
- 배포 구조
- 에러 처리와 로깅 흐름

예시 섹션:

```md
# 아키텍처

## 전체 구조

...

## 모듈 책임

| 모듈 | 책임 | 주요 파일 |
| --- | --- | --- |
| auth | 인증/인가 | ... |
| api | HTTP API | ... |
| db | DB 접근 | ... |

## 주요 흐름

### 사용자 로그인

1. ...
2. ...

## 외부 연동

| 서비스 | 사용 목적 | 인증 방식 |
| --- | --- | --- |
| ... | ... | ... |
```

## DESIGN_NOTES.md 작성 기준

`DESIGN_NOTES.md`는 설계 당시의 판단을 남기는 문서다. 나중에 \"왜 이렇게 만들었는지\"를 확인하는 용도다.

포함할 내용:

- 설계 목표
- 선택한 구조
- 검토한 대안
- 선택 이유
- 포기한 범위
- 알려진 제약
- 추후 개선 방향

예시:

```md
# 설계 노트

## 설계 목표

- ...

## 주요 결정

### API 계층과 DB 계층 분리

결정:
...

이유:
...

대안:
- ...

영향:
- ...
```

## SKILLS.md 작성 기준

`SKILLS.md`는 프로젝트에서 사용하는 Codex 스킬, 자동화 규칙, 작업 보조 도구를 정리한다.

포함할 내용:

- 사용하는 스킬 목록
- 각 스킬의 사용 목적
- 스킬이 수정하거나 생성할 수 있는 파일 범위
- 스킬 사용 시 주의사항
- 프로젝트 전용 프롬프트나 규칙

예시:

```md
# 스킬 구성

## 사용 스킬

| 스킬 | 목적 | 적용 범위 |
| --- | --- | --- |
| frontend-skill | UI/프론트엔드 작업 | `src`, `app`, `components` |
| playwright | 브라우저 검증 | 로컬 개발 서버 |
| spreadsheets | 엑셀/CSV 산출물 | `data`, `exports` |

## 프로젝트 규칙

- 스킬이 생성한 산출물은 `docs` 또는 `artifacts`에 기록한다.
- DB 스키마 변경이 있으면 반드시 `docs/DATABASE.md`를 갱신한다.
- UI 구조 변경이 있으면 `docs/ARCHITECTURE.md`의 화면 흐름을 갱신한다.

## 금지 사항

- 인증 파일 내용을 문서에 직접 복사하지 않는다.
- 임시 캐시 파일을 기준 리소스로 문서화하지 않는다.
```

## DATABASE.md 작성 기준

`DATABASE.md`는 데이터베이스 설계를 추적하는 핵심 문서다. 실제 스키마와 문서가 어긋나면 안 된다.

반드시 포함할 내용:

- DB 종류
- 연결 방식
- 스키마 위치
- 마이그레이션 도구
- 테이블 목록
- 테이블별 컬럼 설명
- 관계
- 인덱스
- 제약 조건
- 초기 데이터
- 백업/복구 정책
- 개인정보/민감정보 처리 기준

예시:

```md
# 데이터베이스 설계

## 개요

| 항목 | 내용 |
| --- | --- |
| DB | PostgreSQL |
| ORM | Prisma |
| 스키마 위치 | `prisma/schema.prisma` |
| 마이그레이션 | `prisma/migrations` |

## 테이블

### users

사용자 계정 정보를 저장한다.

| 컬럼 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| id | uuid | yes | 사용자 ID |
| email | text | yes | 로그인 이메일 |
| created_at | timestamp | yes | 생성일 |

인덱스:

- `users_email_unique`: 이메일 중복 방지

관계:

- `users.id` -> `orders.user_id`

## ERD

```text
users 1 --- N orders
orders 1 --- N order_items
products 1 --- N order_items
```

## 마이그레이션 규칙

- 스키마 변경은 반드시 마이그레이션 파일로 남긴다.
- 컬럼 삭제는 먼저 deprecated 처리 후 별도 배포에서 제거한다.
- 운영 데이터에 영향을 주는 변경은 롤백 방법을 함께 작성한다.
```

## RESOURCE_MAP.md 작성 기준

`RESOURCE_MAP.md`는 프로젝트 개발에 필요한 리소스를 한곳에 모은다.

포함할 내용:

- 소스 코드 위치
- 문서 위치
- 디자인 파일
- API 문서
- DB 접속 정보의 참조 위치
- 배포 환경
- 외부 서비스
- 테스트 데이터
- 임시 산출물 위치

예시:

```md
# 개발 리소스 맵

## 코드

| 경로 | 설명 |
| --- | --- |
| `src` | 애플리케이션 소스 |
| `tests` | 테스트 |
| `docs` | 개발 문서 |

## 외부 리소스

| 리소스 | 위치 | 비고 |
| --- | --- | --- |
| 디자인 | ... | Figma/Canva 등 |
| API 문서 | ... | ... |
| DB 관리 | ... | 접속 정보 직접 기재 금지 |

## 환경

| 환경 | URL | 비고 |
| --- | --- | --- |
| local | `http://localhost:3000` | 개발 서버 |
| staging | ... | 테스트 |
| production | ... | 운영 |
```

## 프로젝트 생성 시 문서 작성 순서

1. `README.md`에 프로젝트 목적과 실행 방법을 먼저 작성한다.
2. `docs/ARCHITECTURE.md`에 전체 구조와 모듈 책임을 작성한다.
3. `docs/DESIGN_NOTES.md`에 생성 당시 설계 결정을 기록한다.
4. 사용하는 Codex 스킬이나 자동화가 있다면 `docs/SKILLS.md`에 정리한다.
5. DB를 사용한다면 `docs/DATABASE.md`를 스키마 작성과 동시에 만든다.
6. 외부 API, 디자인 파일, 배포 환경은 `docs/RESOURCE_MAP.md`에 정리한다.
7. 이후 구조가 바뀔 때마다 관련 문서를 함께 갱신한다.

## 설계 내역 반영 규칙

프로젝트 설계에서 결정한 내용은 반드시 문서에 반영한다.

| 설계 변경 | 갱신 문서 |
| --- | --- |
| 폴더 구조 변경 | `README.md`, `docs/ARCHITECTURE.md` |
| 모듈 책임 변경 | `docs/ARCHITECTURE.md`, `docs/DESIGN_NOTES.md` |
| 스킬 추가/변경 | `docs/SKILLS.md` |
| DB 테이블 추가 | `docs/DATABASE.md` |
| DB 컬럼/인덱스 변경 | `docs/DATABASE.md`, 마이그레이션 파일 |
| 외부 API 추가 | `docs/RESOURCE_MAP.md`, `docs/ARCHITECTURE.md` |
| 배포 방식 변경 | `README.md`, `docs/RESOURCE_MAP.md` |
| 인증/권한 정책 변경 | `docs/ARCHITECTURE.md`, `docs/DATABASE.md` |

## 문서 품질 기준

문서는 다음 기준을 만족해야 한다.

- 현재 코드와 일치해야 한다.
- 경로와 명령어는 실제 실행 가능한 값으로 적는다.
- 민감 정보는 직접 적지 않는다.
- 설계 이유를 생략하지 않는다.
- 변경된 내용은 관련 문서에 동시에 반영한다.
- 오래된 내용은 삭제하거나 deprecated 표시를 한다.

## 신규 프로젝트 문서 체크리스트

- [ ] `README.md`가 있다.
- [ ] 실행 방법이 실제로 동작한다.
- [ ] 폴더 구조가 설명되어 있다.
- [ ] 주요 모듈 책임이 정리되어 있다.
- [ ] 설계 결정과 대안이 기록되어 있다.
- [ ] 사용하는 스킬과 자동화 범위가 정리되어 있다.
- [ ] DB 종류와 스키마 위치가 적혀 있다.
- [ ] 테이블/컬럼/관계/인덱스가 정리되어 있다.
- [ ] 마이그레이션 규칙이 있다.
- [ ] 외부 API와 개발 리소스 위치가 정리되어 있다.
- [ ] 민감 정보가 문서에 직접 포함되지 않았다.

```