📄 [문서][프로젝트] PRD참고해서 문서세분화

[EM-H20]

📝 현재 문제점

• 프로젝트 작업 전에 문서 세분화 작업이 필요함.

01_ARCHITECTURE.md
02_FOLDER_STRUCTURE.md
03_CODE_CONVENTIONS.md
04_CODE_GENERATION_GUIDE.md
05_WIDGETS_GUIDE.md
TOSS_UI_UX_DESIGN.md
기타 등)

🙋‍♂️ 담당자

• 백엔드: 이름
• 프론트엔드: @EM-H20
• 디자인: 이름

[Cassiiopeia]

Guide by SUH-LAB

브랜치

20260120_#10_PRD참고해서_문서세분화

커밋 메시지

PRD참고해서 문서세분화 : feat : {변경 사항에 대한 설명} https://github.com/MapSee-Lab/MapSy-FE/issues/10

[EM-H20]

PRD 참고해서 문서세분화 작업 완료 보고서

작업일: 2026-01-20
GitHub Issue: #10 - PRD참고해서 문서세분화
Branch: 20260120_#10_PRD참고해서_문서세분화

1. 작업 개요

통합 PRD(Mapsy_통합_PRD_v1.0.md)를 기반으로 생성된 문서들의 중복 제거 및 구조 최적화 작업을 완료했습니다.

주요 목표

• ✅ 문서 간 중복 내용 제거 (Single Source of Truth 원칙 적용)
• ✅ 더 이상 필요 없는 소스 문서 아카이빙
• ✅ 문서 간 참조 관계 명확화
• ✅ 빠른 참조 문서 압축 및 최적화

2. 작업 내용

2.1 소스 문서 아카이빙

생성: docs/archive/ 디렉토리

통합 PRD 작성에 사용된 원본 소스 문서 3개를 아카이빙:

docs/archive/
├── 20260119_Frontend_Page_Design.md          (1,552 lines)
├── 20260119_PRD_Part1_Part2_작성완료.md      (548 lines)
└── 20260119_PRD_기반_구현가이드.md            (1,028 lines)

이유: 통합 PRD에 모든 내용이 포함되어 더 이상 필요하지 않지만, 히스토리 보존을 위해 삭제 대신 아카이빙

2.2 디자인 시스템 중복 제거

파일: docs/00_QUICK_REFERENCE.md

변경 내역:

• Before: 771 lines (19.5 KB)
• After: 681 lines (17 KB)
• 감소: -90 lines (-11.7%)

주요 변경 사항:

디자인 시스템 섹션을 상세 내용에서 빠른 참조 형태로 압축:

## 🎨 디자인 시스템

**상세 내용**: [Mapsy_통합_PRD_v1.0.md > 2.6 디자인 시스템](./Mapsy_통합_PRD_v1.0.md#26-디자인-시스템)

### 빠른 참조 (핵심만)

#### 컬러
```dart
import 'package:mapsy/core/constants/app_colors.dart';

AppColors.primary500          // 주요 액션 (0xFFFF6B6B)
AppColors.secondary500        // 보조 액션 (0xFF4ECDC4)
AppColors.accent500           // 강조 (0xFFFFD93D)

**적용된 원칙**:
- Single Source of Truth: 상세 내용은 `Mapsy_통합_PRD_v1.0.md`에만 존재
- 빠른 참조: 5-10개 핵심 항목만 유지
- 명확한 참조: Markdown 앵커 링크로 상세 문서 연결

### 2.3 Clean Architecture 참조 추가

**파일**: `docs/02_FOLDER_STRUCTURE.md`

**변경 내역**:
- **Before**: 652 lines
- **After**: 658 lines
- **추가**: +6 lines

**주요 변경 사항**:

폴더 구조 문서에 Clean Architecture 개념 참조 및 간략 설명 추가:

```markdown
## 2. features/ 구조 (Clean Architecture)

**Clean Architecture 개념 상세**: [01_ARCHITECTURE.md > 3. Clean Architecture 레이어](./01_ARCHITECTURE.md#3-clean-architecture-레이어)

Mapsy 프로젝트는 Clean Architecture의 3-레이어 구조를 따릅니다:
- **Presentation Layer**: UI + State (pages, providers, widgets)
- **Domain Layer**: Business Logic (entities, repositories)
- **Data Layer**: Infrastructure (datasources, models, repository implementations)

적용된 원칙:

• 중복 제거: 상세 개념 설명은 01_ARCHITECTURE.md에만 존재
• 명확한 참조: 아키텍처 문서로 링크
• 간략 요약: 폴더 구조 이해에 필요한 핵심 정보만 제공

3. 작업 결과

3.1 문서 구조 최적화

최종 문서 구조:

docs/
├── Mapsy_통합_PRD_v1.0.md          (2,057 lines) - ✅ 비즈니스 로직 Single Source of Truth
├── 00_QUICK_REFERENCE.md           (681 lines)   - ✅ 빠른 참조 (압축 완료)
├── 01_ARCHITECTURE.md              (1,200 lines) - ✅ 아키텍처 상세
├── 02_FOLDER_STRUCTURE.md          (658 lines)   - ✅ 폴더 구조 (참조 추가)
├── 04_CODE_GENERATION_GUIDE.md     (1,100 lines) - ✅ 코드 생성 가이드
└── archive/                         - ✅ 원본 소스 문서 보관
    ├── 20260119_Frontend_Page_Design.md
    ├── 20260119_PRD_Part1_Part2_작성완료.md
    └── 20260119_PRD_기반_구현가이드.md

참조 관계 계층:

00_QUICK_REFERENCE.md
  └→ Mapsy_통합_PRD_v1.0.md (디자인 시스템 상세)

02_FOLDER_STRUCTURE.md
  └→ 01_ARCHITECTURE.md (Clean Architecture 개념)

3.2 중복 제거 결과

중복 유형	위치	해결 방법	상태
심각한 중복	디자인 시스템 (00_QUICK_REFERENCE ↔ 통합PRD)	빠른 참조로 압축 + 링크	✅ 완료
중간 중복	API 엔드포인트 (여러 문서)	수용 (각 문서 목적에 맞게 변형)	✅ 유지
경미한 중복	Clean Architecture 개념 (01 ↔ 02)	참조 링크 + 간략 요약	✅ 완료

3.3 정량적 결과

• 파일 감소: 771 lines → 681 lines (00_QUICK_REFERENCE.md)
• 파일 아카이빙: 3개 문서 (총 3,128 lines) → archive/
• 참조 링크 추가: 2개 (디자인 시스템, Clean Architecture)
• 문서 구조: 명확한 계층 구조 확립

4. 검증 결과

4.1 종합 평가

✅ Critical Issues: 0
✅ Major Issues: 0
⚠️  Minor Issues: 4 (모두 선택사항)

4.2 선택적 개선사항

다음 개선사항들은 필수가 아닌 선택사항입니다:

1. Markdown 앵커 링크 테스트

   • 한글 헤더 앵커 링크가 GitHub에서 올바르게 작동하는지 확인
   • 필요시 명시적 앵커 ID 사용

2. Archive README 추가

   • docs/archive/README.md 추가로 아카이브 목적 설명
   • 선택사항

3. 통합 PRD 헤더 개선

   • 분리된 문서들 참조 추가
   • 선택사항

4. 02 문서 다이어그램 추가

   • 간단한 폴더 구조 다이어그램 추가
   • 선택사항

5. 다음 단계

5.1 즉시 실행 가능

• 구현 완료 및 검증
• 보고서 작성
• Git 커밋 실행
• Pull Request 생성

5.2 선택적 개선 (우선순위 낮음)

1. Markdown 앵커 링크 테스트 및 검증
2. docs/archive/README.md 추가
3. 통합 PRD 헤더에 분리 문서 참조 추가
4. 02 문서에 간단한 Mermaid 다이어그램 추가

6. 커밋 정보

변경된 파일:

• docs/00_QUICK_REFERENCE.md (수정: -90 lines)
• docs/02_FOLDER_STRUCTURE.md (수정: +6 lines)
• docs/archive/ (3개 파일 이동)

커밋 메시지:

PRD참고해서 문서세분화 : feat : 문서 중복 제거 및 구조 최적화 완료 (디자인 시스템 압축, Clean Architecture 참조 추가, 소스 문서 아카이빙) https://github.com/MapSee-Lab/MapSy-FE/issues/10

---

7. 결론

Single Source of Truth 원칙을 적용하여 문서 간 중복을 제거하고, 명확한 참조 계층 구조를 확립했습니다.

핵심 성과:

• ✅ 90 lines 감소 (00_QUICK_REFERENCE.md)
• ✅ 3개 소스 문서 아카이빙으로 문서 구조 단순화
• ✅ 명확한 참조 관계 확립 (순환 참조 없음)
• ✅ 빠른 참조와 상세 문서의 명확한 역할 분리

문서 유지보수성과 가독성이 크게 향상되었으며, 개발자가 필요한 정보를 빠르게 찾을 수 있는 구조가 완성되었습니다.