Skip to content

Commit f405216

Browse files
dev-wooyeon박은우
dev-wooyeon
authored and
박은우
committed
docs(adr): 홈과 Resume 정보 구조 결정 기록
홈·Archive shell, Resume 요약과 회고 링크, 경로 오류 상태의 선택 기준을 ADR로 남기고 인덱스를 갱신했습니다.
1 parent 5531b31 commit f405216

12 files changed

Lines changed: 569 additions & 0 deletions

‎docs/README.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,16 @@ Last updated: 2026-07-20
3434
- `docs/adr/0033-use-a-white-canvas-without-content-cards.md`
3535
- `docs/adr/0034-adopt-the-graphite-ink-palette.md`
3636
- `docs/adr/0035-prioritize-mobile-archive-reading-order.md`
37+
- `docs/adr/0036-separate-philosophy-home-from-content-archive.md`
38+
- `docs/adr/0037-adopt-zero-log-grid-site-shell.md`
39+
- `docs/adr/0038-use-jetbrains-mono-for-home-statement.md`
40+
- `docs/adr/0039-use-summary-grid-for-public-resume.md`
41+
- `docs/adr/0040-keep-external-links-in-sticky-identity-rail.md`
42+
- `docs/adr/0041-use-two-level-project-summaries-in-resume.md`
43+
- `docs/adr/0042-use-textual-route-error-state.md`
44+
- `docs/adr/0043-include-one-evidence-backed-personal-project-in-resume.md`
45+
- `docs/adr/0044-link-direct-project-retrospectives-from-resume.md`
46+
- `docs/adr/0045-use-team-context-in-resume-company-column.md`
3747
- `docs/blog-quality-guide.md`
3848
- `docs/content-publication-candidates.md`
3949
- `docs/database/db-schema.md`

‎docs/adr/0036-separate-philosophy-home-from-content-archive.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# 0036. 철학 우선 홈과 콘텐츠 Archive를 분리한다
2+
3+
Date: 2026-07-20
4+
Status: Accepted
5+
6+
## 배경
7+
8+
기존 홈은 최신 글을 바로 훑는 날짜와 제목의 아카이브였다. 이 구조는 글을
9+
찾아 읽는 방문자에게는 효율적이지만, 처음 방문한 사람이 Ark를 만든 사람의
10+
관점과 역할을 파악할 단서를 제공하지 못했다.
11+
12+
Ark의 정체성은 불필요한 복잡함을 줄이면서 신뢰할 수 있는 서버 시스템을
13+
만드는 엔지니어링 철학에 있다. 첫 화면은 그 관점을 짧게 전달하고, 더 알고
14+
싶은 사람에게 글과 이력서라는 두 가지 검증 경로를 명시적으로 제공해야 한다.
15+
16+
## 결정
17+
18+
- `/`는 두 문장의 철학 중심 랜딩으로 둔다. 홈은 글 목록이나 카테고리 필터를
19+
렌더링하지 않는다.
20+
- 기존 홈의 All, Tech, Life 필터와 날짜·제목 행 목록은 `/archive`로 옮긴다.
21+
- 전역 주요 탐색에는 `Archive`와 `Resume`만 노출한다. `ark` 워드마크는 홈으로
22+
연결한다.
23+
- 기존 `/engineering`, `/life`, `/blog/[slug]` route는 직접 URL로 계속 접근할 수
24+
있으며, 이 route에서는 `Archive`를 활성 상태로 표시한다.
25+
- `/blog`는 중복된 목록 대신 `/archive`로 이동한다.
26+
- `/series`는 기존처럼 Engineering의 시리즈 필터로 이동한다.
27+
- 데스크톱의 GitHub, Email, RSS는 화면 좌하단 보조 링크로 유지한다. 모바일은
28+
`Archive`, `Resume`을 상단에 바로 노출하고 외부 링크는 하단에 둔다.
29+
- 이력서의 본문과 레이아웃은 이 결정의 범위에 포함하지 않는다.
30+
31+
## 결과
32+
33+
- 첫 방문자는 짧은 문장으로 Ark의 관점을 먼저 읽고, 필요할 때만 Archive 또는
34+
Resume로 이동한다.
35+
- 글을 자주 찾는 방문자는 `/archive`에서 이전과 동일한 최소 행 아카이브와
36+
카테고리 필터를 사용한다.
37+
- 데스크톱과 모바일 모두 메뉴를 열거나 여러 분류를 해석하기 전에 두 핵심
38+
목적지에 도달할 수 있다.
39+
40+
## 검토한 대안
41+
42+
- 홈 상단에 짧은 소개와 아카이브를 함께 둔다: 철학 문장과 글 목록이 첫 화면의
43+
주목을 경쟁하게 된다.
44+
- 프로젝트 카드 중심의 포트폴리오 홈을 만든다: 이력서와 글에 이미 있는 증거를
45+
중복하고, 현재의 간결한 사이트 정체성과 맞지 않는다.
46+
- 모바일에서도 주요 목적지를 드로어에 숨긴다: 화면은 단순하지만 Archive와
47+
Resume로 가는 의도가 한 단계 늦어진다.
48+
49+
## 검증
50+
51+
- HomePage unit test로 철학 문장만 렌더링하고 아카이브 필터가 없음을 검증한다.
52+
- ArchivePageClient와 archive-feed unit test로 기존 필터와 날짜·제목 목록
53+
동작을 검증한다.
54+
- Playwright smoke test로 데스크톱과 모바일의 Archive, Resume 노출과
55+
`/archive` 필터 동작을 검증한다.
56+
57+
## Related History
58+
59+
- [ADR 0030](0030-use-date-title-rows-for-home-archive.md): 날짜와 제목만의
60+
아카이브 행은 Archive route에서 유지한다.
61+
- [ADR 0032](0032-reduce-desktop-rail-to-home-wordmark-and-utilities.md):
62+
레일 탐색 범위를 Archive와 Resume으로 다시 정의한다.
63+
- [ADR 0035](0035-prioritize-mobile-archive-reading-order.md): 모바일 드로어
64+
대신 상단의 명시적 주요 탐색을 사용한다.

‎docs/adr/0037-adopt-zero-log-grid-site-shell.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# 0037. zero.log 형태의 2-6-4 사이트 shell을 사용한다
2+
3+
Date: 2026-07-20
4+
Status: Accepted
5+
6+
## 배경
7+
8+
Ark의 철학 우선 홈과 Archive 분리는 완료했지만, 헤더와 본문이 일반적인 가로
9+
내비게이션과 중앙 컨테이너에 남아 있었다. 이 구조는 소개 문장, 글 아카이브,
10+
Resume의 관계를 한 화면에서 같은 위계로 보이지 못하게 했다.
11+
12+
참조한 zero.log는 데스크톱에서 정체성, 콘텐츠, 주요 탐색을 하나의 2-6-4
13+
그리드에 두고, 모바일에서는 정체성과 주요 탐색을 왼쪽 열에 쌓아 콘텐츠 열을
14+
보존한다. Ark도 같은 정보 구조에 맞는 shell이 필요하다.
15+
16+
## 결정
17+
18+
- 전역 shell은 데스크톱에서 `2fr 6fr 4fr` 세 열과 40px 열 간격을 사용한다.
19+
- shell의 바깥 여백은 데스크톱 32px, 모바일 16px이며 상하 여백은 40px으로
20+
둔다.
21+
- 첫 열에는 `ark` 워드마크를 둔다. 둘째 열에는 현재 route의 콘텐츠를 둔다.
22+
셋째 열에는 `Resume`, `Archive` 순서의 주요 탐색을 둔다.
23+
- 모바일에서는 `1fr 4fr` 두 열로 전환한다. 주요 탐색은 워드마크 아래로
24+
이동하고, route 콘텐츠는 오른쪽 열의 상단에서 시작한다.
25+
- 외부 링크는 화면 또는 문서의 좌하단에서 세로로 쌓는다. route 콘텐츠가
26+
길면 footer는 문서 흐름 아래로 이동한다.
27+
- 홈은 둘째 열에서 두 줄의 소개 문장만 렌더링한다. Archive는 같은 열에서
28+
카테고리 필터 없이 날짜와 제목 행만 렌더링한다.
29+
- 문서 흐름 스크롤을 사용한다. `data-page-scroll-container`는 읽기 진행도
30+
소비자에게 문서 스크롤 모드를 명시한다.
31+
- Resume의 내용 구성은 바꾸지 않는다. Resume은 새 shell의 콘텐츠 열 안에서
32+
기존 데이터를 계속 렌더링한다.
33+
34+
## 결과
35+
36+
- 데스크톱과 모바일 모두 정체성, 증거, 다음 행동이 동일한 좌표 체계를
37+
공유한다.
38+
- 홈과 Archive는 별도의 페이지 목적을 가지면서도 같은 콘텐츠 열을 사용한다.
39+
- 기존 `/archive`, `/resume`, 상세 글, Engineering, Life route는 유지된다.
40+
41+
## 검토한 대안
42+
43+
- 이전의 가로 헤더를 유지한다: 주요 탐색은 빠르지만 소개 문장과 Archive가
44+
서로 다른 레이아웃 체계에 남는다.
45+
- 홈만 참조 레이아웃으로 바꾼다: Archive와 Resume에서 사이트 정체성이
46+
끊긴다.
47+
- 모바일에서 주요 탐색을 가로 헤더에 둔다: 짧은 화면에서 소개 문장에 쓸
48+
오른쪽 열의 폭을 줄인다.
49+
50+
## 검증
51+
52+
- AppShell 컴포넌트 테스트로 Resume과 Archive 순서 및 활성 상태를 검증한다.
53+
- Playwright smoke test로 데스크톱의 2-6-4 좌표와 모바일의 1-4 좌표를
54+
검증한다.
55+
- Playwright 회귀 테스트로 문서 스크롤 기반 읽기 진행도가 유지되는지
56+
검증한다.
57+
58+
## Related History
59+
60+
- [ADR 0030](0030-use-date-title-rows-for-home-archive.md): 날짜와 제목만의
61+
Archive 행
62+
- [ADR 0036](0036-separate-philosophy-home-from-content-archive.md): 철학 우선
63+
홈과 Archive route 분리

‎docs/adr/0038-use-jetbrains-mono-for-home-statement.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# 0038. 홈 소개 문장에 JetBrains Mono를 사용한다
2+
3+
Date: 2026-07-20
4+
Status: Accepted
5+
6+
## 배경
7+
8+
Ark의 홈은 두 줄의 소개 문장만으로 현재의 작업과 다음 탐색을 전달한다. 기본
9+
Pretendard만 사용하면 shell의 다른 텍스트와 같은 밀도로 읽혀, 개발자로서의
10+
정체성과 서비스 링크가 첫 화면에서 충분히 구분되지 않는다.
11+
12+
저장소에는 이미 자체 호스팅한 JetBrains Mono 서체와 `--font-mono` 토큰이
13+
있다. 새 외부 폰트를 추가하지 않고도, 기술적인 문장을 한정된 범위에서 다르게
14+
보이게 할 수 있다.
15+
16+
## 결정
17+
18+
- 홈의 소개 문장만 `--font-mono`를 사용한다. 본문, Archive, Resume의 기본
19+
Pretendard 서체는 유지한다.
20+
- 소개 문장은 14px, medium weight, 24px line-height로 둔다. 데스크톱 1200px
21+
기준 콘텐츠 열에서 첫 문장과 현재 작업 문장이 각각 한 줄에 머물도록 한다.
22+
- `@9.81park`는 밑줄 링크로 표현하고 `https://www.981park.com`을 새 창에서
23+
연다. 새 창 링크에는 `noopener noreferrer`를 설정한다.
24+
25+
## 결과
26+
27+
- 첫 화면의 소개 문장은 단순한 인터페이스 레이블과 구분되며, 서버 시스템을
28+
만드는 정체성을 짧고 기술적인 인상으로 전달한다.
29+
- 전체 사이트의 읽기용 기본 서체와 콘텐츠 밀도는 바뀌지 않는다.
30+
- 서비스의 실제 웹사이트는 현재 페이지를 이탈하지 않고 확인할 수 있다.
31+
32+
## 검토한 대안
33+
34+
- 기본 Pretendard를 유지한다: 현재 shell과 자연스럽지만 소개 문장의 구분감이
35+
약하다.
36+
- 홈 전체를 16px JetBrains Mono로 둔다: 더 강한 인상은 만들지만 1200px
37+
콘텐츠 열에서 첫 문장이 줄바꿈되어 두 줄 구성이 깨진다.
38+
- 다른 외부 monospace 서체를 로드한다: 별도 네트워크 비용과 fallback 검증이
39+
필요하지만, 이미 검증된 자체 호스팅 서체로 얻는 이점보다 작다.
40+
41+
## 검증
42+
43+
- HomePage 컴포넌트 테스트로 서비스 링크 URL, 새 창 이동, 보안 rel 속성을
44+
검증한다.
45+
- Playwright smoke test로 렌더된 소개 문장이 JetBrains Mono를 사용하는지와
46+
서비스 링크의 새 창 이동을 검증한다.
47+
48+
## Related History
49+
50+
- [ADR 0019](0019-use-content-first-typography-scale.md): 콘텐츠 읽기용 기본
51+
typography scale
52+
- [ADR 0036](0036-separate-philosophy-home-from-content-archive.md): 철학 우선
53+
홈 구성
54+
- [ADR 0037](0037-adopt-zero-log-grid-site-shell.md): 홈 소개 문장이 놓이는
55+
2-6-4 shell

‎docs/adr/0039-use-summary-grid-for-public-resume.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# 0039. 공개 Resume은 요약 4열 그리드로 제공한다
2+
3+
Date: 2026-07-20
4+
Status: Accepted
5+
6+
## 배경
7+
8+
기존 Resume은 프로젝트의 문제, 결정, 구현, 검증, 결과와 보조 이력을 한 페이지에
9+
모두 노출했다. 내용 자체는 상세 이력서에 보존할 가치가 있지만, 채용담당자와
10+
개발자가 처음 방문했을 때 역할과 적합성을 빠르게 파악하기에는 밀도가 높았다.
11+
12+
참조한 zero.log Resume은 콘텐츠 열에서 신원, 역할, 연락처를 먼저 보여준 뒤 회사와
13+
핵심 결과를 일정한 열에 배치한다. Ark도 상세 이력서의 대체물이 아니라, 대화와
14+
상세 검토로 이어지기 위한 공개 요약본이 필요하다.
15+
16+
## 결정
17+
18+
- 공개 `/resume`은 shell의 콘텐츠 열에 4열 요약 그리드를 사용한다. 모바일에서는
19+
2열로 전환한다.
20+
- 첫 행은 ID, Role, Focus, Contact만 표시한다. 생년월일, 전화번호, 블로그 URL은
21+
공개 요약본에서 제외한다.
22+
- 경력은 모노리스와 엑심베이 두 회사만 표시한다. 각 회사에는 역할, 기간, 세 개의
23+
결과 키워드만 둔다.
24+
- 핵심 결과는 검증 가능한 변화나 범위를 짧게 적는다. 긴 프로젝트 단계와 서술형
25+
자기소개는 이 화면에서 렌더링하지 않는다.
26+
- 역량은 Server systems, Data platform, Operations automation 세 묶음으로만
27+
정리한다.
28+
- 이력 원본 데이터는 `resume/model/resume-data.ts`에 유지한다. 공개 요약본은
29+
별도의 summary data를 사용한다.
30+
31+
## 결과
32+
33+
- 첫 화면에서 백엔드, 데이터 플랫폼, 운영 자동화의 적합성을 빠르게 판단할 수
34+
있다.
35+
- 상세 이력의 내용은 삭제되지 않으며, 별도의 상세 이력서나 후속 대화에 사용할 수
36+
있다.
37+
- Resume은 홈과 Archive가 사용하는 동일한 2-6-4 shell 안에서 더 짧은 문서로
38+
읽힌다.
39+
40+
## 검토한 대안
41+
42+
- 기존 상세 Resume을 유지한다: 이력의 증거는 풍부하지만 첫 화면의 판단 비용이
43+
높다.
44+
- 상세 정보를 아코디언으로 접는다: 정보량은 유지하지만 사용자가 무엇을 열어야
45+
하는지 먼저 판단해야 한다.
46+
- 공개 Resume을 요약 그리드로 바꾼다: 정보량을 의도적으로 줄이지만 역할, 도메인,
47+
성과를 한 번에 비교할 수 있다.
48+
49+
## 검증
50+
51+
- ResumePage 컴포넌트 테스트로 역할, 연락처, 두 회사, 핵심 결과를 검증한다.
52+
- 컴포넌트 테스트로 기존 장문 섹션이 렌더링되지 않는 것을 검증한다.
53+
- Playwright로 데스크톱 4열과 모바일 2열 레이아웃을 확인한다.
54+
55+
## Related History
56+
57+
- [ADR 0027](0027-use-resume-specific-editorial-grid.md): 이전 Resume의
58+
에디토리얼 그리드
59+
- [ADR 0037](0037-adopt-zero-log-grid-site-shell.md): 전역 2-6-4 shell

‎docs/adr/0040-keep-external-links-in-sticky-identity-rail.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# 0040. 외부 링크는 sticky 정체성 레일에 둔다
2+
3+
Date: 2026-07-20
4+
Status: Accepted
5+
6+
## 배경
7+
8+
Ark의 외부 링크는 문서 흐름의 footer에 있었다. Home처럼 짧은 route에서는
9+
좌하단에 보이지만, Archive처럼 콘텐츠가 긴 route에서는 모든 글 목록 뒤에
10+
배치되어 연락 경로를 바로 찾을 수 없었다.
11+
12+
Ark의 `ark` 워드마크는 좌측 열에서 사이트 정체성을 전달한다. GitHub, Email,
13+
RSS도 같은 정체성 레일 안에 두면 콘텐츠 길이와 무관하게 처음부터 확인할 수
14+
있다.
15+
16+
## 결정
17+
18+
- 외부 링크는 문서 흐름의 footer에서 제거하고, `ark` 워드마크와 같은 좌측
19+
identity rail에 둔다.
20+
- identity rail은 shell의 상하 여백을 제외한 viewport 높이를 사용하고 sticky로
21+
고정한다.
22+
- 워드마크는 rail 상단에, GitHub, Email, RSS는 rail 하단에 세로로 쌓는다.
23+
- 데스크톱에서는 2-6-4 shell의 첫 열을 사용한다. 모바일에서는 기존 1-4 grid의
24+
첫 열을 사용하며, 주요 탐색은 워드마크 아래에 그대로 둔다.
25+
26+
## 결과
27+
28+
- Archive의 길이와 관계없이 외부 링크가 첫 화면 좌하단에 표시된다.
29+
- 사이트 정체성, 주요 탐색, 외부 연락 경로의 역할이 각각 좌측, 우측, 좌측에
30+
고정되어 읽기 순서가 예측 가능해진다.
31+
- footer를 기다리지 않아도 GitHub와 Email로 이동할 수 있다.
32+
33+
## 검토한 대안
34+
35+
- footer를 유지한다: 문서의 끝에는 자연스럽지만 긴 Archive에서 발견이 늦다.
36+
- 외부 링크를 우측 주요 탐색 아래에 둔다: 탐색과 연락의 역할이 섞이고, Resume과
37+
Archive의 우선순위가 약해진다.
38+
- 별도 floating 버튼을 둔다: 즉시성은 높지만 Paper shell의 정적인 편집 구조와
39+
맞지 않는다.
40+
41+
## 검증
42+
43+
- AppShell 테스트로 외부 링크가 identity rail 안에 있고 footer가 없는지
44+
검증한다.
45+
- Playwright로 Archive에서 데스크톱과 모바일 모두 외부 링크가 좌하단에
46+
표시되는 좌표를 검증한다.
47+
48+
## Related History
49+
50+
- [ADR 0009](0009-use-app-shell-for-primary-navigation.md): AppShell의
51+
주요 탐색 책임
52+
- [ADR 0037](0037-adopt-zero-log-grid-site-shell.md): 2-6-4 shell과
53+
좌측 외부 링크 배치

‎docs/adr/0041-use-two-level-project-summaries-in-resume.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# 0041. Resume 프로젝트는 짧은 소개와 상세 설명을 나눠 제공한다
2+
3+
Date: 2026-07-20
4+
Status: Accepted
5+
6+
## 배경
7+
8+
요약 Resume은 핵심 키워드를 빠르게 보여주지만, `CDC analytics`나
9+
`Platform redesign` 같은 영문 성과 라벨만으로는 실제로 무엇을 했는지 알기
10+
어려웠다. 회사 열의 `Backend Engineer · IoT Systems`도 좁은 열에서 자연스럽지
11+
않게 줄바꿈됐다.
12+
13+
공개 Resume은 상세 이력서보다 짧아야 하지만, 각 성과의 문제와 수행 내용을
14+
질문할 수 있을 만큼의 문맥은 남겨야 한다.
15+
16+
## 결정
17+
18+
- 회사 메타 정보는 역할과 도메인을 별도 줄로 나눈다. 모노리스는 `백엔드
19+
엔지니어`, `IoT 시스템`으로, 엑심베이는 `소프트웨어 엔지니어`, `PG 플랫폼`으로
20+
표시한다.
21+
- 각 프로젝트는 Resume 콘텐츠 열의 2열에 제목과 한 줄 소개를 둔다.
22+
- 프로젝트의 상세 설명은 3-4열을 사용해 한국어 문장으로 표시한다.
23+
- 중앙 콘텐츠 폭이 좁아지는 1,024px 미만에서는 4열 구성을 2열로 전환해
24+
한국어 단어가 글자 단위로 끊기지 않게 한다.
25+
- 상세 설명에는 어떤 흐름을 바꿨는지와 검증 가능한 결과를 함께 쓴다. 긴
26+
문제·결정·구현·검증 단계 전체는 공개 Resume에 다시 도입하지 않는다.
27+
28+
## 결과
29+
30+
- 첫 훑기에서는 프로젝트 제목과 한 줄 소개를 읽고, 필요할 때만 같은 행의
31+
상세 설명을 이어 읽을 수 있다.
32+
- 영문 기술 키워드만 나열하는 것보다 실제 업무 범위와 성과를 이해하기 쉽다.
33+
- 공개 Resume은 요약본의 밀도를 유지하면서 면접 후속 질문에 답할 수 있는
34+
최소 문맥을 제공한다.
35+
36+
## 검토한 대안
37+
38+
- 성과 키워드만 유지한다: 가장 빠르지만 실제 수행 내용을 이해하기 어렵다.
39+
- 기존 상세 이력처럼 단계별 서술을 전부 표시한다: 증거는 많지만 첫 화면이
40+
다시 길어진다.
41+
- 프로젝트별 짧은 소개와 상세 설명을 한 행에 나눈다: 읽기 단계는 늘지만
42+
필요한 문맥을 가장 작은 범위에서 제공한다.
43+
44+
## 검증
45+
46+
- ResumePage 컴포넌트 테스트로 한국어 프로젝트 제목, 간략 소개, 상세 설명을
47+
검증한다.
48+
- Playwright로 데스크톱 4열과 모바일 2열 전환에서 프로젝트 설명이 보이는지
49+
검증한다.
50+
51+
## Related History
52+
53+
- [ADR 0039](0039-use-summary-grid-for-public-resume.md): 공개 Resume의
54+
요약 4열 그리드

0 commit comments

Comments
 (0)