sam-docs/plans/docs-update-plan.md

docs/architecture 문서 업데이트 계획

작성일: 2025-12-26 목적: 현재 시스템 상태와 문서 동기화 기준 문서: docs/INDEX.md 상태: 🔄 진행중

---

📍 현재 진행 상태

항목	내용
마지막 완료 작업	Phase 4 전체 완료
다음 작업	없음 (완료)
진행률	13/13 (100%) ✅
마지막 업데이트	2025-12-26

---

1. 개요

1.1 배경

• 2025-12-13 admin 프로젝트 → mng 프로젝트 전환 완료
• 문서에 아직 admin 참조가 남아있어 동기화 필요
• 기술 스택 버전 업데이트 반영 필요

1.2 기준 원칙

┌─────────────────────────────────────────────────────────────────┐
│  🎯 문서 업데이트 원칙                                           │
├─────────────────────────────────────────────────────────────────┤
│  - 현재 시스템 상태와 100% 동기화                                │
│  - admin → mng 전환 완전 반영                                   │
│  - 버전 정보 최신화 (React 19.2.1, Next.js 15.5.7)             │
│  - 상호 참조 링크 일관성 유지                                    │
└─────────────────────────────────────────────────────────────────┘

1.3 변경 승인 정책

분류	예시	승인
✅ 즉시 가능	날짜 갱신, 오타 수정, 버전 업데이트	불필요
⚠️ 컨펌 필요	구조 변경, 새 섹션 추가, 문서 삭제	필수
🔴 금지	비즈니스 로직 변경, 정책 변경	별도 협의

1.4 준수 규칙

• docs/INDEX.md - 문서 인덱스
• docs/standards/quality-checklist.md - 품질 체크리스트

---

2. 대상 범위

2.1 Phase 1: 핵심 문서 업데이트

#	작업 항목	상태	비고
1.1	system-overview.md - admin→mng 전환	✅	완료
1.2	dev-commands.md - admin→mng 변경	✅	완료
1.3	quick-start.md - claudedocs→docs 경로 수정	✅	완료

2.2 Phase 2: 보조 문서 업데이트

#	작업 항목	상태	비고
2.1	INDEX.md - 프로젝트 구조 미세 조정	✅	Admin 참조 제거
2.2	quality-checklist.md - 날짜 갱신	✅	2025-12-26
2.3	swagger-guide.md - 날짜 갱신	✅	2025-12-26

2.3 Phase 3: 검증 및 정리

#	작업 항목	상태	비고
3.1	security-policy.md - 날짜 갱신	✅	2025-12-26
3.2	database-schema.md - 테이블 수 업데이트	✅	92개→171개

2.4 Phase 4: 오래된 파일 정리/아카이브

#	작업 항목	상태	비고
4.1	history/2025-09/ 문서 검토	✅	참조용 유지
4.2	history/2025-11/ 문서 검토	✅	아카이브로 적절
4.3	admin 참조 파일 식별 및 정리	✅	4개 파일 수정 완료
4.4	완료된 plans/ 문서 정리	✅	D0.8→history, index 업데이트
4.5	중복/불필요 문서 정리	✅	빈 디렉토리 6개 삭제

---

3. 작업 절차

3.1 단계별 절차

Step 1: Phase 1 - 핵심 문서 업데이트
├── 1.1 system-overview.md 전면 업데이트
│   ├── admin/ 설명 → mng/ 설명
│   ├── Filament v4 → Pure Blade + Tailwind
│   ├── Docker 서비스 구성 업데이트
│   └── 저장소 구조 업데이트
├── 1.2 dev-commands.md 수정
│   ├── Admin Application → MNG Application
│   └── admin/ 경로 → mng/ 경로
└── 1.3 quick-start.md 수정
    ├── claudedocs/ → docs/ 경로
    └── 프로젝트 구조 업데이트

Step 2: Phase 2 - 보조 문서 업데이트
├── 2.1 INDEX.md 미세 조정
├── 2.2 quality-checklist.md 날짜 갱신
└── 2.3 swagger-guide.md 날짜 갱신

Step 3: Phase 3 - 검증 및 정리
├── 3.1 security-policy.md 날짜 갱신
├── 3.2 database-schema.md 테이블 수 확인
└── 3.3 모든 문서 일관성 검증

Step 4: Phase 4 - 오래된 파일 정리/아카이브
├── 4.1 history/2025-09/ 문서 검토
│   └── 구버전 스키마, 체크포인트 확인
├── 4.2 history/2025-11/ 문서 검토
│   └── item-master 관련 아카이브 정리
├── 4.3 admin 참조 파일 정리
│   └── mng로 미전환된 파일 식별/수정
├── 4.4 완료된 plans/ 문서 정리
│   └── 완료된 계획 문서 삭제/아카이브
└── 4.5 중복/불필요 문서 정리
    └── 통합 가능 문서 식별 및 처리

3.2 문서 업데이트 템플릿

### [항목 ID] 항목명

**현재 상태:**
- [현재 상태 설명]

**목표 상태:**
- [목표 상태 설명]

**변경 사항:**
- [ ] ✅ [즉시 가능 항목]
- [ ] ⚠️ [컨펌 필요 항목]

---

4. 상세 작업 내용

4.1 Phase 1: 핵심 문서 업데이트

1.1 system-overview.md

• 상태: ⏳ 대기
• 주요 변경:
  • admin/ 섹션 → mng/ 섹션으로 전환
  • 기술 스택: Filament v4 → Pure Blade + Tailwind CSS 3.x
  • Docker 서비스: design, php73 추가
  • React 버전: 19.2.0 → 19.2.1
  • Next.js 버전: 15 → 15.5.7
  • 도메인 매핑: admin.sam.kr → mng 서비스 설명
  • 저장소 구조: admin → mng

1.2 dev-commands.md

• 상태: ⏳ 대기
• 주요 변경:
  • "Admin Application (admin/)" → "MNG Application (mng/)"
  • admin/ 경로 → mng/ 경로
  • 업데이트 날짜 갱신

1.3 quick-start.md

• 상태: ⏳ 대기
• 주요 변경:
  • claudedocs/SAM/ 경로 → docs/ 경로
  • 프로젝트 구조에 mng, design, planning 추가
  • admin/ 참조 → mng/ 참조
  • 업데이트 날짜 갱신

4.2 Phase 4: 오래된 파일 정리/아카이브

4.1 history/2025-09/ 문서 검토

• 상태: ⏳ 대기
• 대상 파일:
  • history/2025-09/checkpoint.md - 구버전 체크포인트
  • history/2025-09/database-schema.md - 구버전 스키마 (참조용 유지 검토)
• 조치: 아카이브 적합성 검토, 불필요시 삭제

4.2 history/2025-11/ 문서 검토

• 상태: ⏳ 대기
• 대상 파일:
  • history/2025-11/item-master-gap-analysis.md
  • history/2025-11/item-master-spec.md
  • history/2025-11/front-requests/ 디렉토리
  • history/2025-11/item-master-archived/ 디렉토리
• 조치: 현재 유효성 검토, 아카이브 정리

4.3 admin 참조 파일 식별 및 정리

• 상태: ⏳ 대기
• 검색 대상: docs/ 전체에서 "admin" 키워드 포함 파일
• 조치: mng로 전환 또는 deprecated 표시

4.4 완료된 plans/ 문서 정리

• 상태: ⏳ 대기
• 대상 파일:
  • 완료된 계획 문서 식별
  • 현재 진행중인 문서 유지
• 조치: 완료된 계획은 삭제 또는 history/로 이동

4.5 중복/불필요 문서 정리

• 상태: ⏳ 대기
• 검토 대상:
  • 내용이 중복된 문서
  • 더 이상 유효하지 않은 문서
  • 통합 가능한 문서
• 조치: 통합, 삭제, 또는 아카이브

---

5. 컨펌 대기 목록

구조 변경 등 승인 필요 항목

#	항목	변경 내용	영향 범위	상태
-	-	-	-	-

---

6. 변경 이력

날짜	항목	변경 내용	파일	승인
2025-12-26	-	계획 문서 초안 작성	-	-
2025-12-26	Phase 4	오래된 파일 정리/아카이브 작업 추가	docs-update-plan.md	-
2025-12-26	Phase 1	핵심 문서 3개 업데이트 완료	system-overview.md, dev-commands.md, quick-start.md	✅
2025-12-26	Phase 2	보조 문서 3개 업데이트 완료	INDEX.md, quality-checklist.md, swagger-guide.md	✅
2025-12-26	Phase 3	검증 및 정리 완료	security-policy.md, database-schema.md	✅
2025-12-26	Phase 4.1-4.2	history/ 문서 검토 완료	-	✅
2025-12-26	Phase 4.4	plans/ 정리 완료	D0.8→history, index_plans.md 업데이트	✅
2025-12-26	Phase 4.3	admin 참조 파일 정리	docker-setup, git-conventions, project-launch-roadmap, remote-work-setup	✅

---

7. 참고 문서

• 문서 인덱스: docs/INDEX.md
• 품질 체크리스트: docs/standards/quality-checklist.md
• Serena 메모리: docs-update-analysis.md

---

8. 세션 관리 정책

8.1 세션 시작 시

list_memories() → 기존 상태 확인
read_memory("docs-update-analysis") → 분석 결과 로드
이 계획 문서 읽기 → 컨텍스트 로드

8.2 작업 중

• 변경 이력 실시간 업데이트
• Phase/항목별 상태 업데이트
• 컨펌 필요 시 대기 목록 추가

8.3 세션 종료 시

변경 이력에 최종 업데이트 기록
write_memory("docs-update-progress") → Serena에 저장

8.4 Serena 메모리 구조

docs-update-analysis.md    # 분석 결과 (완료)
docs-update-progress.md    # 진행 상황 (작업 중 업데이트)

---

9. 검증 결과

작업 완료 후 이 섹션에 검증 결과 추가

9.1 문서 일관성 체크

문서	admin 참조	mng 반영	날짜 최신화	링크 유효
system-overview.md
dev-commands.md
quick-start.md
INDEX.md
quality-checklist.md
swagger-guide.md
security-policy.md
database-schema.md

9.2 성공 기준 달성 현황

기준	달성	비고
admin 참조 완전 제거
mng 반영 완료
버전 정보 최신화
상호 참조 링크 유효

---

이 문서는 /plan 스킬로 생성되었습니다.