동블

그래프 뷰

00. 학습 문서 개선 기준

12 min read

Spring 학습 문서 개선 기준

한 줄 결론

깊은 내용을 모두 펼쳐 두는 것이 아니라, 다시 볼 때는 압축본으로 회수하고 깊게 공부할 때는 같은 순서의 상세본으로 들어가게 만든다.

3줄 요약

  • 파일이 지나치게 많고 계층이 깊다면 먼저 하나의 압축본으로 합친다.
  • 압축본은 제목, 3줄 요약, 핵심 정리, 헷갈리는 지점, 확인 질문만 남긴다.
  • 압축본의 순서를 그대로 따르는 상세본을 같은 폴더에 두고, 상세본에는 공식 문서 기준, 원리, 코드, 실전 팁을 담는다.

파일럿 적용 결과

AOP 영역은 다음 원칙으로 먼저 개선한다.

확장 적용 결과

Spring 핵심 주제는 AOP와 같은 방식으로 확장한다.

  • 각 주제 폴더는 00. 주제 압축 정리.md와 압축본 순서를 따르는 상세본 4개를 기본 구조로 둔다.
  • 압축본은 다시 보기와 기억 회수를 담당하고, 상세본은 공식 문서 기준, 원리, 코드, 실전 팁, 위험 신호를 담당한다.
  • 기존 MVC, Security 문서의 핵심 내용은 새 얕은 폴더의 압축본과 상세본에 흡수한다.
  • 새 주제 폴더 안에는 archive 폴더나 깊은 하위 계층을 만들지 않는다.
  • 상세본 하단에는 오래된 흐름 내비게이션 대신 참고 문서만 둔다.

확장 대상:

공식 문서 기준

문서의 기술적 기준은 Spring 공식 reference를 우선한다. 블로그, 강의, 예제 코드는 판단을 돕는 자료로만 쓰고, 동작 원리나 버전 차이를 단정할 때는 공식 문서 링크로 다시 확인한다.

버전 의존 설명은 문장 안에 조건을 드러낸다. 예를 들어 Spring 6, Spring 6.2, Spring Security 6, Spring Boot 3/4처럼 버전에 따라 달라질 수 있는 내용은 숫자 버전이나 조건을 함께 적는다.

프로젝트에서 실제 사용하는 Spring 버전이 다르면 이 문서의 결론을 그대로 적용하지 말고, 해당 버전의 공식 문서에서 다음 항목을 다시 확인한다.

  • AOP proxy와 @Transactional method visibility
  • Transaction rollback 기본 정책과 propagation 동작
  • Spring Security filter 구성, CSRF 기본 동작, SecurityContext 저장 방식
  • Spring Boot test slice, @MockitoBean, Testcontainers @ServiceConnection

완료 잠금 체크리스트

문서 세트를 완료 상태로 보기 전에는 다음을 확인한다.

  • 대상 폴더의 파일 수와 압축본/상세본 구조가 기준과 맞는가?
  • archive 폴더나 깊은 하위 계층이 다시 생기지 않았는가?
  • 오래된 관련 문서, 같은 묶음, 전체 흐름, 통합 목차 섹션이 남아 있지 않은가?
  • Obsidian 내부 링크가 실제 파일로 해석되는가?
  • 외부 공식 문서 링크가 정상 응답하는가?
  • 파일명 변경은 git에서 삭제와 신규 파일로 방치되지 않고 rename 의도가 추적 가능한가?

회독 테스트

압축본은 읽는 문서가 아니라 기억을 되살리는 문서다. 각 압축본은 다음 질문에 답할 수 있어야 한다.

  • 이 주제의 핵심 문제를 30초 안에 설명할 수 있는가?
  • 상세본 4개의 순서를 보지 않고도 흐름으로 복원할 수 있는가?
  • 헷갈리는 지점을 읽고 실무에서 어떤 실수를 피해야 하는지 말할 수 있는가?
  • 확인 질문의 답을 가리고도 개념의 경계와 선택 기준을 설명할 수 있는가?
  • 공식 문서나 버전 차이를 다시 확인해야 하는 위험 문장을 구분할 수 있는가?

문서 계층

1. 압축본

목적은 “무엇을 이해해야 하는가?”를 한 번에 회수하게 만드는 것이다. 단순 목차가 아니라 핵심 판단 기준을 중심으로 구성한다.

포함할 내용:

  • 제목
  • 3줄 요약
  • 핵심 정리
  • 헷갈리는 지점
  • 확인 질문

구조 규칙:

  • 압축본의 각 큰 주제는 # 주제명으로 독립시킨다.
  • 3줄 요약, 핵심 정리, 헷갈리는 지점, 확인 질문은 ### 소제목으로 둔다.
  • 별도의 최상위 통합 제목은 두지 않는다.

2. 상세본

목적은 압축본의 순서를 그대로 따라가면서 공식 문서 기준, 원리, 코드 예제, 실전 고수 팁을 깊게 공부하게 만드는 것이다.

포함할 내용:

  • success callout으로 제시하는 답할 수 있는 질문
  • 개요
  • 원리 또는 주제별 원리 설명
  • 코드 예제
  • 실전 팁
  • 위험 신호
  • 확인 질문
  • 참고 문서

구조 규칙:

  • 파일명이 제목 역할을 하므로 본문 최상단에 별도 H1 제목을 두지 않는다.
  • 첫 블록은 >[!success] 이 문서를 통해 아래 질문들에 답할 수 있게 됩니다. callout으로 시작한다.
  • 본문 섹션은 ## 단일 계층으로 평평하게 둔다.
  • 공식 문서 기준보다 개요, 실전 고수 팁보다 실전 팁처럼 짧은 섹션명을 우선한다.
  • 확인 질문은 질문 bullet 아래에 답변 bullet을 들여쓴다.
  • 하단에는 ## 참고 문서만 두고, 오래된 관련 문서나 흐름 내비게이션을 붙이지 않는다.

3. 헷갈리는 지점

목적은 오해가 생기는 지점을 그냥 나열하지 않고, 왜 헷갈리는지와 어떻게 생각해야 하는지를 함께 남기는 것이다.

작성 방식:

  • 바깥 bullet에는 헷갈리는 내용과 헷갈리는 이유를 함께 쓴다.
  • 들여쓴 bullet에는 핵심 판단 포인트를 분리해서 쓴다.
  • 필요하면 들여쓴 bullet을 2개까지 둔다.
  • 소제목의 소제목이나 화살표 구조는 쓰지 않는다.

4. 확인 질문

목적은 질문만 남기지 않고, 복습자가 바로 자기 답을 검증할 수 있게 만드는 것이다.

작성 방식:

  • 바깥 bullet에는 확인 질문: ...만 쓴다.
  • 바로 아래 들여쓴 줄에 답변: ...을 쓴다.
  • 질문은 개념의 경계나 선택 기준을 묻는다.
  • 답변은 짧지만 판단 근거가 드러나야 한다.
  • 소제목의 소제목이나 화살표 구조는 쓰지 않는다.

삭제할 내비게이션 항목

압축본과 상세본에서 다음 항목은 다시 보기 비용을 늘리므로 제거한다.

  • 같은 묶음
  • 전체 흐름 이전
  • 전체 흐름 다음
  • 통합 목차
  • 잘못된 절대성 경로 링크

Security 문서에 적용한 기준

Security 영역의 긴 문서는 새 얕은 구조로 흡수한다.

적용 방식:

  1. Security FilterChain과 요청 흐름에서 Controller 이전 FilterChain 구조를 정리한다.
  2. Authentication 구조에서 Controller 직접 로그인과 Security 인증 구조의 책임 이동을 정리한다.
  3. Authorization과 권한 규칙에서 인증과 인가, 401과 403, role prefix 문제를 정리한다.
  4. Session JWT Cookie CSRF에서 세션, JWT, 토큰, 쿠키, CSRF의 역할 층위를 정리한다.

Security에서 먼저 던질 질문:

  • Servlet Container와 FilterChain은 Controller 앞에서 무엇을 처리하는가?
  • Session, JWT, Token, Cookie는 각각 저장 방식, 값, 운반 수단 중 무엇에 해당하는가?
  • MVC 방식 로그인에서 Security 방식 로그인으로 바뀔 때 책임은 어디로 이동하는가?
  • 인증과 인가의 경계는 어느 필터와 어느 객체에서 드러나는가?

결론

이 기준의 목적은 글을 무작정 짧게 만드는 것이 아니라, 다시 읽는 비용을 낮추는 것이다. 압축본은 기억 회수용이고, 상세본은 깊은 이해용이다. 상세본을 만들더라도 archive처럼 깊은 계층을 만들지 않고 압축본과 같은 순서로 같은 폴더에 둔다.

관련 문서

백링크