[Obsidian] 문서 구조에 대한 고민 (feat.PARA 방법론)

PARA

 

원래도 문서를 많이 남기려고 하는 편이지만, 작성이나 정리가 쉽지가 않았다. 또한 어느 순간 AI를 쓰다 보니, 생성되는 md 파일들이 너무나 많아지고, 이를 직접 필요할 때 찾기가 어려워지기 시작했다. 물론 AI는 알아서 컨텍스트를 잘 찾고 참고하지만, 정작 내가 볼 때는? 어디에 있는지 찾기 조차 어렵다. 분명 어디서 봤는데, 어디에 써놓은 것 같은데, 정확한 문구나 단어가 생각나지 않으면 전체 검색도 어려울뿐더러, 검색한다 해도 연관된 파일이 너무나도 많다. (현재 프로젝트 폴더 내에 문서 폴더를 만든 것도 영향이 큼.)

 

이런저런 고민을 하던 차에, 폴더 구조부터 개선하고 싶었고, 어떻게 개선하면 좋을까 고민해 보게 되었다.

 

현재 폴더 구조는 아래와 같다.

최상위 폴더들

 

• 분석: 코드나, 기능에 대한 설명들을 모은 곳
• 가이드: 기능 개발이 끝나면 해당 기능에 대한 문서를 작성한 곳
• 업무일지: 회의나, 특정 기능 개발, 이슈에 대한 작업을 할 때 기록한 문서들 (최근엔 데일리노트를 작성 중)
• 인수인계: 휴가나, 업무를 인수인계 하기 위한 문서를 작성한 곳
• 인프라: 인프라는 별도의 레포로 관리되어있고, 현재 프로젝트에서 바로 확인하기 어려운 내용들을 정리+공부하기 위한 목적의 폴더
• TF: 현재 작업하는 추가 업무
• 계획: 코드 리뷰, 품질 개선으로 통해 해야할 것들에 대한 계획 문서를 모은 곳
• plans: 동일한데, 명칭만 다름. 내부는 실제로 생성된 plans의 집합
• v3.0.5.2: 신규 버전 릴리즈에 관련한 문서
• README: 아마도 이러한 폴더에 대한 설명을 위해 넣은. 그렇지만 의미 없다. 이 파일조차 업데이트를 하지 않아서, 현재 구조와 다르기 때문.

 

현재 README.md

# docs 목차

프로젝트 문서는 **기능/분야별**로 아래 폴더에 정리되어 있습니다.

---

## 폴더 구조

```
docs/
├── 00-분석/                   # 기술 분석
│
├── 01-권한/                   # 프로젝트 권한
│
├── 02-로그인인증/              # 로그인 정책, 임시 비밀번호
│
├── 03-기능검토/               # 기능별 검토·버그 분석·플로우
│
├── 04-인수인계/               # 인수인계·운영 문서
│
├── 05-가이드/                 # 외부 가이드 PDF, 테스트 가이드
│
├── 06-업무일지/               # 업무일지·투두 템플릿
│
├── 07-데이터/                 # CSV·Excel 등 분석 산출물
│
├── 08-개선안및기타/            # 제안·정리·개선안·기타
│
├── 09-인프라/                 # ★ 인프라·배포·CI/CD 관련 문서
│   ├── infra-guide.md                          # CI/CD & 인프라 전체 가이드 (Mermaid 다이어그램)
│   ├── infra-architecture.excalidraw           # 전체 아키텍처 도식 (Excalidraw)
│   ├── nexus-harbor-가이드.md                  # Nexus / Harbor 레지스트리 가이드
│   ├── build-gradle-history.md                 # Gradle 빌드 이력
│   ├── deploy-information-performance-analysis.md
│   ├── minio-기능검토서.md           # (기획용) MinIO 기능 현황·제한 정리
│   └── minio-개발구현검토.md         # (개발용) 업로드·폴더 API·스트리밍 다운로드
│
├── 10-GS인증/                 # GS 인증 보안·라이선스 검증
│   ├── (현행 버전 문서)
│   ├── 원본/                  # 원본 GS인증 문서
│   └── 업그레이드비교/         # 의존성 업그레이드 전후 비교
│
├── 11-파이프라인/             # 3.0.5.2 아키텍처 및 구현 계획
│
├── 12-TF/                    # TF 관련 분석·미들웨어 연동 가이드
│
└── 13-계획/                  # 설계·구현 계획 문서 (날짜별)
```

---

## 폴더별 설명

| 폴더 | 설명 |
|------|------|
| **00-분석** | 인증 헤더 플로우 분석, core 사용 현황 등 기술 분석 |
| **01-권한** | 메뉴/페이지 권한, 프로젝트 내부 역할, 성능 개선 |
| **02-로그인인증** | 임시 비밀번호(해시/암호화, DDL, 테스트), 로그인 정책 기능 진척도 |
| **03-기능검토** | 간트차트 히스토리백, 대결 종료 처리, 대결 이벤트 플로우 |
| **04-인수인계** | 2026 인수인계(SonarQube 등), 라이선스 관리 인수인계 |
| **05-가이드** | 상세검색 백엔드 가이드 PDF, 테스트 가이드 |
| **06-업무일지** | 업무일지 템플릿·실적, 투두 정리 프롬프트 |
| **07-데이터** | 메뉴/페이지 콤포넌트 정보 CSV·Excel, Jira KPI 등 참고 데이터 |
| **08-개선안및기타** | 개선 제안, 작업 요약, RBAC 전환, 권한 미적용 목록, 암호화/이메일 검색 개선안 등 |
| **09-인프라** | CI/CD 파이프라인, Kubernetes, Jenkins, Argo CD, Harbor 등 인프라 전체 가이드 |
| **10-GS인증** | GS 인증 라이브러리 오픈소스 점검, OWASP 취약점 개선, 의존성 업그레이드 |
| **11-파이프라인** | 3.0.5.2 아키텍처, Redpanda 브로커, 구현 계획 |
| **12-TF** | TF 인프라·미들웨어 현행 분석, 라이선스 검토 |
| **13-계획** | 설계·구현 계획 문서 |

 

위 구조가 폴더가 너무 많은 것 같아서, 최근 축소를 진행했고 나름 정리한다고 구분했지만, 실제로 펼쳐보면 대환장이다.

 

폴더 내부에 또 폴더, 이름 규칙 없고 파일명 규칙도 없고 문서가 추가될 때마다 루트 폴더도 추가해버림 🤦🏻‍♀️

 

 

정리에 관해 고민하던 차, 우연히 PARA를 알게 되었다. (구글에서 검색만 해도 바로 보이는!)

구글 검색 결과

 

 

PARA란?

티아고 포르테(Tiago Forte)가 고안한 PARA 방법론이다. 지식 관리와 워크스페이스 구성에 널리 쓰이며, 특히 AI(Cursor, Claude Projects 등)에게 명확한 컨텍스트(Context)를 제공해야 할 때 매우 효과적인 구조라고 한다.

 

PARA 구조

1. Projects (프로젝트): 명확한 목표와 기한이 있는 실행 단위

구성 예시: MonoFlow 서비스 웹 개발, 앱 초기 기획, 이번 주 스프린트 작업

AI 활용: 현재 진행 중인 작업에 대한 프롬프트, AI가 생성한 임시 코드, 요구사항 명세서를 둔다. AI 툴에서 특정 프로젝트 폴더만 Context로 지정해 환각(Hallucination)을 방지한다.

2. Areas (영역): 기한은 없지만 지속적으로 관리하고 유지해야 하는 책임 분야

구성 예시: 프론트엔드 아키텍처 가이드, 자격증 공부

AI 활용: AI에게 코딩 컨벤션이나 팀의 표준 설정(System Prompt)을 지시할 때 참조할 마스터 파일들을 보관한다.

3. Resources (자원): 당장 프로젝트에 쓰진 않지만 나중에 유용할 수 있는 관심 자료

구성 예시: React/TypeScript 성능 최적화 패턴, 재테크 및 투자 관련 스크랩, 유용한 오픈소스 라이브러리 목록

AI 활용: AI가 생성한 유용한 스니펫이나, 나중에 다른 프로젝트에 재사용할 수 있는 범용적인 코드 조각들을 모아둔다.

4. Archives (보관소): 완료되었거나 당장 중단된 1, 2, 3의 항목들

구성 예시: 종료된 프로젝트, 작년도 기술 검토 문서

• AI 활용: AI의 검색 범위(Search Index)에서 제외하여, 불필요한 과거 코드가 현재 작업에 섞여 들어오는 것을 차단한다.

 

 

구조 전환

전환된 PARA 폴더 구조

구조 전환을 진행한 후, 기존의 파일명들도 규칙 없이 중구난방이라, 파일명 규칙을 정했다.

 

 

추가작업

파일명 개선

기존에는 마크다운 `preview`로 문서를 보는 경우가 많았어서, 문서 작성일을 보기가 어려우니 파일명에 넣었다. 

근데 조금 더 적극적으로 옵시디언을 쓰기로 마음 먹어서, 기존 문서 파일명에서 일자를 제거하고 frontmatter를 적용하기로 했다.

파일명 규칙은 일단 `kebab-case`을 쓰기로 했다.

 

frontmatter

문서 최상단에 아래 정보를 추가한다.

---
created: 2026-03-09
tags: [area/infrastructure, topic/auth]
---

• Obsidian Properties 패널에서 작성일 확인 가능
• 파일명이 짧아지고 wikilink가 읽기 쉬워짐
• 2026.03.09_auth-ingress.md → auth-ingress.md + created: 2026-03-09

 

항목	규칙	예시
구분자	kebab-case (하이픈)	결재-종료-처리-버그-분석.md
언더스코어	금지	결재_종료 → 결재-종료
공백	금지	MinIO 사용 현황 → minio-사용현황
날짜	파일명 제거 → frontmatter	created: 2026-03-09

 

그래프뷰 / 세컨드 브레인

wikilink, tag가 제대로 정의되어있지 않아 이를 개선하고자 했다.

작업 전

 

MOC (Map of Content)

각 주제의 허브 파일. 예를 들어 MOC-artifact-storage.md 파일이 MinIO, Nexus 관련 문서 전체로 wikilink를 가지면 → 그래프 뷰에서 그 파일이 클러스터 중심 노드로 표시된다.

MOC 적용 후

 

 

데일리노트

템플릿+스크립트로 매일 오전에 자동 생성되게했다.

그리고 깃 훅을 걸어서, 커밋별로 데일리노트에 작성되게 하였다.

스킬로 해도 되지만, 또 데일리노트를 내가 실시간으로 보면서 작업할 수도 있다는 생각이 들어서, 그냥 깃 훅을 유지했다.

## 오늘 목표
- [ ]

## 할 일
- [ ]

## 업무 로그
-

## 메모
-

## 관련 문서
<!-- 그래프 뷰 연결을 위해 관련 문서를 아웃링크로 추가 (예: [[1-Projects/artifact-storage-tf/nexus/nexus-기능검토]]) -->

## 산출물
<!-- scripts/generate-daily-note.sh 실행 시 자동 채워짐 (docs/ 신규·수정 파일) -->

## 내일 할 일
- [ ]

## 이월

## 커밋
<!-- scripts/generate-daily-note.sh 실행 시 자동 채워짐 -->

## 작업 파일
<!-- scripts/generate-daily-note.sh 실행 시 자동 채워짐 -->

 

후기

후기는 좀 더 써보고 업데이트할 예정