공개 문서
docs/code-review-2026-03-11-install-layout.md
아래는 docs/code-review-2026-03-11-install-layout.md 와 동일한 원문입니다. Markdown과 HTML 변환 결과를 각각 복사할 수 있습니다.
공개 문서 원문 (Markdown)
# Code Review Report — 설치 레이아웃·코드 블록 수정
> 검토 대상: 02-installation / 06 / 10 / 13 설치 링크 60·40 레이아웃, 코드 블록 가독성, globals.css·page.tsx 변경
> 검토일: 2026-03-11
---
## Summary
| 항목 | 내용 |
|------|------|
| **검토 파일 수** | 7 (MDX 4, page.tsx, globals.css, public/images/README.md) |
| **이슈** | Critical 0, Major 0, Minor 2 |
| **종합 점수** | 88/100 |
전반적으로 **보안·일관성·접근성**이 잘 지켜졌고, 수정 범위도 명확합니다. Minor 이슈 2건만 반영하면 됩니다.
---
## 잘된 점
### 1. 보안
- **외부 링크**: 모든 설치 링크에 `target="_blank"` + `rel="noopener noreferrer"` 적용 (02, 06, 10, 13 전부).
- **입력 소스**: 링크·이미지 경로가 콘텐츠 고정값이라 XSS/입력 검증 이슈 없음.
### 2. 접근성
- **대체 텍스트**: 모든 설치용 `<img>`에 의미 있는 `alt` 지정 (예: "Node.js 공식 사이트 — Run JavaScript Everywhere, Get Node.js 다운로드").
- **브레드크럼·네비**: `page.tsx`에 `aria-label="breadcrumb"`, `aria-current="page"` 유지.
### 3. 일관성
- **레이아웃 패턴**: 모든 설치 블록이 동일한 구조 사용.
- `float-right w-full md:w-[40%] md:ml-6 mb-4 flex-shrink-0 not-prose`
- `<a>` 스타일: `block rounded-lg overflow-hidden border border-slate-200 shadow-sm hover:shadow-md transition-shadow`
- **이미지 공유**: `homebrew-install.png`를 02·13에서 재사용해 중복 없음.
### 4. 유지보수성
- **이미지 목록**: `public/images/README.md`에 파일명·사용 위치·URL 표로 정리되어 추적 용이.
- **코드 블록 스타일**: `globals.css`에서 `.prose pre` / `.prose pre code`로 한 곳에서 관리.
### 5. 성능·렌더
- MDX 내 `<img>`는 `page.tsx`의 `components={{ img: MdxImage }}`로 `next/image` 적용되어 로컬 이미지 최적화·LCP에 유리.
---
## Minor Issues
### 1. [public/images/README.md] 이미지 없을 때 표현 오류
**현재 문구:**
"없으면 레이아웃은 유지되고 이미지만 비어 보입니다."
**사실:**
파일이 없으면 브라우저는 **깨진 이미지 아이콘(404)**을 표시합니다. "비어 보인다"는 사용자 기대와 다를 수 있음.
**제안:**
다음 중 하나로 수정 권장.
- "없으면 해당 위치에 **깨진 이미지 아이콘이 보일 수 있습니다.** 스크린샷을 추가하면 됩니다."
- 또는 공용 placeholder 이미지(예: `placeholder-install.png`)를 두고, README에 "이미지가 없을 때 placeholder가 표시됩니다"라고 안내.
---
### 2. [접근성] 외부 링크 포커스 링
**현재:**
설치용 `<a>`에 `hover:shadow-md`만 있고, 키보드 포커스 시 시각적 표시가 없음.
**제안:**
Tailwind로 포커스 링 추가 (선택).
```html
className="... transition-shadow focus:outline-none focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-offset-2"
```
탭으로 이동 시 포커스가 보이면 키보드·스크린리더 사용자에게 유리합니다. 적용 시 모든 설치 블록 `<a>`에 동일 클래스 적용 권장.
---
## Recommendations
1. **이미지 placeholder**
`nodejs-download.png`만 있는 상태에서 나머지 7개 경로는 404 가능성이 있으므로,
- 실제 스크린샷을 채우거나,
- 단색/로고 placeholder를 두고 `src`를 조건부로 바꾸는 방식도 고려할 수 있음 (구현 비용 대비 선택).
2. **코드 블록 CSS 범위**
`.prose pre, .prose pre code`는 현재 챕터 본문(`article.prose`)에만 쓰이므로 문제 없음.
추후 다른 `.prose` 컨테이너를 쓰면 코드 블록 스타일이 동일 적용됨을 인지하고, 필요 시 선택자를 더 좁히면 됨 (예: `.prose.prose-slate pre`).
3. **MdxImage 래퍼 마진**
설치 블록 이미지는 MDX에서 `<img>`로 쓰이므로 `MdxImage`가 렌더되며, 기본 `my-4`가 적용됩니다.
float 레이아웃 안에서는 영향이 크지 않으나, 나중에 레이아웃을 더 조정할 때는 `MdxImage`에 `layout="install"` 같은 prop을 두고 `my-4`를 제거하는 옵션을 고려할 수 있음.
---
## Files Reviewed
| 파일 | 변경 요약 |
|------|------------|
| `content/courses/02-installation.mdx` | Homebrew, Cursor, Node.js, Git 섹션에 60/40 이미지 블록 추가 |
| `content/courses/06-claude-code-install.mdx` | 설치 섹션에 이미지 블록 추가 |
| `content/courses/10-gemini-install.mdx` | 설치 섹션에 이미지 블록 추가 |
| `content/courses/13-google-workspace-cli-install.mdx` | Homebrew, gws, gcloud 섹션에 이미지 블록 추가 |
| `app/courses/[slug]/page.tsx` | 단일 article 클래스 사용 (slug 분기 제거) |
| `app/globals.css` | `.prose pre` / `.prose pre code` 전역 가독성 스타일 |
| `public/images/README.md` | 설치 레이아웃용 이미지 목록 표 |
---
## 결론
수정 방향과 구현이 안정적이며, Critical/Major 이슈는 없습니다.
위 Minor 2건(README 문구 수정, 필요 시 포커스 링 추가)만 반영해도 프로덕션 배포에 무리 없습니다.
공개 문서 변환 코드 (HTML)
<h1>Code Review Report — 설치 레이아웃·코드 블록 수정</h1>
<blockquote>
<p>검토 대상: 02-installation / 06 / 10 / 13 설치 링크 60·40 레이아웃, 코드 블록 가독성, globals.css·page.tsx 변경<br>검토일: 2026-03-11</p>
</blockquote>
<hr>
<h2>Summary</h2>
<table>
<thead>
<tr>
<th>항목</th>
<th>내용</th>
</tr>
</thead>
<tbody><tr>
<td><strong>검토 파일 수</strong></td>
<td>7 (MDX 4, page.tsx, globals.css, public/images/README.md)</td>
</tr>
<tr>
<td><strong>이슈</strong></td>
<td>Critical 0, Major 0, Minor 2</td>
</tr>
<tr>
<td><strong>종합 점수</strong></td>
<td>88/100</td>
</tr>
</tbody></table>
<p>전반적으로 <strong>보안·일관성·접근성</strong>이 잘 지켜졌고, 수정 범위도 명확합니다. Minor 이슈 2건만 반영하면 됩니다.</p>
<hr>
<h2>잘된 점</h2>
<h3>1. 보안</h3>
<ul>
<li><strong>외부 링크</strong>: 모든 설치 링크에 <code>target="_blank"</code> + <code>rel="noopener noreferrer"</code> 적용 (02, 06, 10, 13 전부).</li>
<li><strong>입력 소스</strong>: 링크·이미지 경로가 콘텐츠 고정값이라 XSS/입력 검증 이슈 없음.</li>
</ul>
<h3>2. 접근성</h3>
<ul>
<li><strong>대체 텍스트</strong>: 모든 설치용 <code><img></code>에 의미 있는 <code>alt</code> 지정 (예: "Node.js 공식 사이트 — Run JavaScript Everywhere, Get Node.js 다운로드").</li>
<li><strong>브레드크럼·네비</strong>: <code>page.tsx</code>에 <code>aria-label="breadcrumb"</code>, <code>aria-current="page"</code> 유지.</li>
</ul>
<h3>3. 일관성</h3>
<ul>
<li><strong>레이아웃 패턴</strong>: 모든 설치 블록이 동일한 구조 사용.<ul>
<li><code>float-right w-full md:w-[40%] md:ml-6 mb-4 flex-shrink-0 not-prose</code></li>
<li><code><a></code> 스타일: <code>block rounded-lg overflow-hidden border border-slate-200 shadow-sm hover:shadow-md transition-shadow</code></li>
</ul>
</li>
<li><strong>이미지 공유</strong>: <code>homebrew-install.png</code>를 02·13에서 재사용해 중복 없음.</li>
</ul>
<h3>4. 유지보수성</h3>
<ul>
<li><strong>이미지 목록</strong>: <code>public/images/README.md</code>에 파일명·사용 위치·URL 표로 정리되어 추적 용이.</li>
<li><strong>코드 블록 스타일</strong>: <code>globals.css</code>에서 <code>.prose pre</code> / <code>.prose pre code</code>로 한 곳에서 관리.</li>
</ul>
<h3>5. 성능·렌더</h3>
<ul>
<li>MDX 내 <code><img></code>는 <code>page.tsx</code>의 <code>components={{ img: MdxImage }}</code>로 <code>next/image</code> 적용되어 로컬 이미지 최적화·LCP에 유리.</li>
</ul>
<hr>
<h2>Minor Issues</h2>
<h3>1. [public/images/README.md] 이미지 없을 때 표현 오류</h3>
<p><strong>현재 문구:</strong><br>"없으면 레이아웃은 유지되고 이미지만 비어 보입니다."</p>
<p><strong>사실:</strong><br>파일이 없으면 브라우저는 **깨진 이미지 아이콘(404)**을 표시합니다. "비어 보인다"는 사용자 기대와 다를 수 있음.</p>
<p><strong>제안:</strong><br>다음 중 하나로 수정 권장.</p>
<ul>
<li>"없으면 해당 위치에 <strong>깨진 이미지 아이콘이 보일 수 있습니다.</strong> 스크린샷을 추가하면 됩니다."</li>
<li>또는 공용 placeholder 이미지(예: <code>placeholder-install.png</code>)를 두고, README에 "이미지가 없을 때 placeholder가 표시됩니다"라고 안내.</li>
</ul>
<hr>
<h3>2. [접근성] 외부 링크 포커스 링</h3>
<p><strong>현재:</strong><br>설치용 <code><a></code>에 <code>hover:shadow-md</code>만 있고, 키보드 포커스 시 시각적 표시가 없음.</p>
<p><strong>제안:</strong><br>Tailwind로 포커스 링 추가 (선택).</p>
<pre><code class="language-html">className="... transition-shadow focus:outline-none focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-offset-2"
</code></pre>
<p>탭으로 이동 시 포커스가 보이면 키보드·스크린리더 사용자에게 유리합니다. 적용 시 모든 설치 블록 <code><a></code>에 동일 클래스 적용 권장.</p>
<hr>
<h2>Recommendations</h2>
<ol>
<li><p><strong>이미지 placeholder</strong><br><code>nodejs-download.png</code>만 있는 상태에서 나머지 7개 경로는 404 가능성이 있으므로, </p>
<ul>
<li>실제 스크린샷을 채우거나, </li>
<li>단색/로고 placeholder를 두고 <code>src</code>를 조건부로 바꾸는 방식도 고려할 수 있음 (구현 비용 대비 선택).</li>
</ul>
</li>
<li><p><strong>코드 블록 CSS 범위</strong><br><code>.prose pre, .prose pre code</code>는 현재 챕터 본문(<code>article.prose</code>)에만 쓰이므로 문제 없음.<br>추후 다른 <code>.prose</code> 컨테이너를 쓰면 코드 블록 스타일이 동일 적용됨을 인지하고, 필요 시 선택자를 더 좁히면 됨 (예: <code>.prose.prose-slate pre</code>).</p>
</li>
<li><p><strong>MdxImage 래퍼 마진</strong><br>설치 블록 이미지는 MDX에서 <code><img></code>로 쓰이므로 <code>MdxImage</code>가 렌더되며, 기본 <code>my-4</code>가 적용됩니다.<br>float 레이아웃 안에서는 영향이 크지 않으나, 나중에 레이아웃을 더 조정할 때는 <code>MdxImage</code>에 <code>layout="install"</code> 같은 prop을 두고 <code>my-4</code>를 제거하는 옵션을 고려할 수 있음.</p>
</li>
</ol>
<hr>
<h2>Files Reviewed</h2>
<table>
<thead>
<tr>
<th>파일</th>
<th>변경 요약</th>
</tr>
</thead>
<tbody><tr>
<td><code>content/courses/02-installation.mdx</code></td>
<td>Homebrew, Cursor, Node.js, Git 섹션에 60/40 이미지 블록 추가</td>
</tr>
<tr>
<td><code>content/courses/06-claude-code-install.mdx</code></td>
<td>설치 섹션에 이미지 블록 추가</td>
</tr>
<tr>
<td><code>content/courses/10-gemini-install.mdx</code></td>
<td>설치 섹션에 이미지 블록 추가</td>
</tr>
<tr>
<td><code>content/courses/13-google-workspace-cli-install.mdx</code></td>
<td>Homebrew, gws, gcloud 섹션에 이미지 블록 추가</td>
</tr>
<tr>
<td><code>app/courses/[slug]/page.tsx</code></td>
<td>단일 article 클래스 사용 (slug 분기 제거)</td>
</tr>
<tr>
<td><code>app/globals.css</code></td>
<td><code>.prose pre</code> / <code>.prose pre code</code> 전역 가독성 스타일</td>
</tr>
<tr>
<td><code>public/images/README.md</code></td>
<td>설치 레이아웃용 이미지 목록 표</td>
</tr>
</tbody></table>
<hr>
<h2>결론</h2>
<p>수정 방향과 구현이 안정적이며, Critical/Major 이슈는 없습니다.<br>위 Minor 2건(README 문구 수정, 필요 시 포커스 링 추가)만 반영해도 프로덕션 배포에 무리 없습니다.</p>