<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:media="http://search.yahoo.com/mrss/">
  <channel>
    <title>Hugo · 인재덕</title>
    <link>https://jared.lynskey.co.nz/ko/tags/hugo/</link>
    <description>소프트웨어 엔지니어링과 개발 조직 리더십에 대한 이야기. 성과 리뷰, 채용과 팀 확장, CI/CD, 데브옵스 모니터링, 에이전틱 AI. 서울에서 씁니다.</description>
    <generator>Hugo</generator>
    <language>ko</language>
    <copyright>© 2026 인재덕</copyright>
    <lastBuildDate>Sat, 07 Nov 2026 00:00:00 +1300</lastBuildDate>
    <atom:link href="https://jared.lynskey.co.nz/ko/tags/hugo/index.xml" rel="self" type="application/rss+xml" />
    <item>
      <title>GitHub Actions CI에서 Docker Compose 대신 쓰는 것, 그리고 지금 돌리는 파이프라인</title>
      <link>https://jared.lynskey.co.nz/ko/posts/2026/2026-10-22-docker-compose-ci-github-actions/</link>
      <guid isPermaLink="true">https://jared.lynskey.co.nz/ko/posts/2026/2026-10-22-docker-compose-ci-github-actions/</guid>
      <pubDate>Thu, 22 Oct 2026 00:00:00 +1300</pubDate>
      <dc:creator>Jared Lynskey</dc:creator>
      <category>CI/CD</category>
      <category>GitHub Actions</category>
      <category>Docker</category>
      <category>DevOps</category>
      <category>Deployment</category>
      <category>Fly.io</category>
      <category>Cloudflare</category>
      <category>Django</category>
      <category>PostgreSQL</category>
      <category>Hugo</category>
      <category>Python</category>
      <description>2026년에 제가 돌리는 GitHub Actions CI/CD: CI에서는 Docker Compose 대신 서비스 컨테이너, 캐시는 단계별 소요 시간을 보고 고르고, 배포는 스크립트로.</description>
      <content:encoded><![CDATA[<p>CI/CD 파이프라인은 변경 사항이 <code>git push</code>에서 프로덕션까지 가는 자동화된 경로입니다. CI는 모든 push를 깨끗한 머신에서 빌드하고 테스트하고, CD는 통과한 것을 반복 가능한 단계 하나로 릴리스합니다. GitHub Actions에서는 <code>.github/workflows/</code> 아래의 YAML 파일이 그것이고, 제 것은 일부러 얇게 만들었습니다. 체크는 제 노트북에서 돌리는 명령 그대로이고, 배포는 전부 GitHub 없이도 똑같이 동작할 스크립트나 CLI입니다.</p>
<p>GitHub Actions에서 Docker Compose를 돌리는 법을 찾아 오셨다면, 결론부터. 저는 그걸 2년 하다가 그만뒀습니다. 지금 CI는 같은 Postgres와 Valkey 이미지를 <code>services:</code>로 선언하고, 같은 <code>uv run …</code>과 <code>npm run …</code> 명령을 러너에서 바로 돌립니다. Compose는 개발자가 로컬에서 돌리는 것으로 남았고요. 나머지는 그 이유와 실제 파일들입니다.</p>
<p>2024년에 <a href="https://jared.lynskey.co.nz/ko/posts/2024/2024-06-02-simplifyingcicd/" >플랫폼 종속 YAML 대신 Docker Compose로 CI/CD 하기</a>라는 글을 썼습니다. 빌드 로직은 Compose에 두고 CI 도구는 그걸 호출하는 일만 하게 하라는 내용이었죠. 2년이 지나 제가 실제로 배포하는 저장소를 전부 다시 훑어봤습니다. 워크플로가 있는 저장소는 넷이고, 커미터는 모두 저 한 명입니다. 그리고 그 워크플로 중 <code>docker compose</code>를 호출하는 건 이제 하나도 없습니다. 원칙은 살아남았고, 방법은 살아남지 못했습니다. 아래는 그 자리를 대신한 것들입니다. 줄여서 예제로 만든 파일, GitHub가 기록한 단계별 소요 시간, 그리고 CI/CD 다이어그램이 바라는 것보다 덜 자동화된 부분까지 적었습니다.</p>

<h2 class="relative group">제가 돌리는 파이프라인 전부, 표 하나로
    <div id="제가-돌리는-파이프라인-전부-표-하나로" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%a0%9c%ea%b0%80-%eb%8f%8c%eb%a6%ac%eb%8a%94-%ed%8c%8c%ec%9d%b4%ed%94%84%eb%9d%bc%ec%9d%b8-%ec%a0%84%eb%b6%80-%ed%91%9c-%ed%95%98%eb%82%98%eb%a1%9c" aria-label="앵커">#</a>
    </span>
    
</h2>
<table>
	<thead>
			<tr>
					<th>파이프라인</th>
					<th>시작하는 쪽</th>
					<th>CI가 확인하는 것</th>
					<th>가는 곳</th>
					<th>릴리스하는 사람</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>이 블로그와 클라이언트의 Hugo 사이트 하나</td>
					<td>모든 push, 브랜치 무관</td>
					<td><code>hugo --gc</code> 빌드가 되는지</td>
					<td>Cloudflare Pages: <code>main</code>은 프로덕션, 다른 브랜치는 미리보기 URL</td>
					<td>없음. push가 곧 릴리스</td>
			</tr>
			<tr>
					<td>제 마켓플레이스 앱의 API</td>
					<td>배포 스크립트, 수동</td>
					<td><code>main</code>에 push할 때마다 린트, 타입 체크, Django 테스트</td>
					<td>Fly.io, 롤링 배포</td>
					<td>저</td>
			</tr>
			<tr>
					<td>같은 앱의 프런트엔드: 웹, OTA 업데이트, 스토어 빌드</td>
					<td>릴리스 스크립트와 로컬 스토어 빌드, 수동</td>
					<td><code>main</code>에 push할 때마다 TypeScript와 Jest</td>
					<td>오브젝트 스토리지, OTA 업데이트 서비스, 두 앱 스토어</td>
					<td>저</td>
			</tr>
			<tr>
					<td>제 오픈소스 Python 패키지 pyhtml2text</td>
					<td>모든 push, 풀 리퀘스트, 태그</td>
					<td>빌드 타깃 15개용 wheel, 대부분에서 테스트</td>
					<td>PyPI, 태그를 달 때</td>
					<td>태그</td>
			</tr>
	</tbody>
</table>
<p>교과서 용어로 말하면 두 Hugo 사이트는 지속적 배포이고, 앱(제가 만드는 마켓플레이스 겸 커뮤니티 앱)은 지속적 통합에 명령 한 줄짜리 릴리스를 더한 지속적 전달입니다. 체크는 뭔가 잘못됐다고 알려 줄 뿐, 배포를 막지는 않습니다. 일부러 이렇게 나눴습니다. OTA 업데이트는 대상 바이너리 버전을 쓰는 모든 휴대폰에 닿으니, 머지의 부작용이 아니라 결정이어야 합니다. 그리고 API는 데이터베이스 마이그레이션이 실행되는 곳입니다. 제 나머지 Django 앱 두 개에는 워크플로가 아예 없습니다.</p>

<h2 class="relative group">CI 쪽: 워크플로 하나, 잡 두 개
    <div id="ci-쪽-워크플로-하나-잡-두-개" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#ci-%ec%aa%bd-%ec%9b%8c%ed%81%ac%ed%94%8c%eb%a1%9c-%ed%95%98%eb%82%98-%ec%9e%a1-%eb%91%90-%ea%b0%9c" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>앱의 CI는 <code>.github/workflows/checks.yml</code> 파일 하나입니다. 10월 11일 전까지는 이것조차 없었습니다. 아래는 그 구조를 줄여서 만든 예제입니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="c"># Lint, types and tests on every push and pull request to main.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># Nothing here deploys.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Checks</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">on</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">push</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">branches</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="l">main]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">pull_request</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">branches</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="l">main]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">concurrency</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">group</span><span class="p">:</span><span class="w"> </span><span class="l">checks-${{ github.ref }}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">cancel-in-progress</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">jobs</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">python</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">runs-on</span><span class="p">:</span><span class="w"> </span><span class="l">ubuntu-latest</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">timeout-minutes</span><span class="p">:</span><span class="w"> </span><span class="m">30</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">services</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">postgres</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">image</span><span class="p">:</span><span class="w"> </span><span class="l">postgres:17</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">env</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">POSTGRES_USER</span><span class="p">:</span><span class="w"> </span><span class="l">myapp</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">POSTGRES_PASSWORD</span><span class="p">:</span><span class="w"> </span><span class="l">myapp</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">POSTGRES_DB</span><span class="p">:</span><span class="w"> </span><span class="l">myapp</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">ports</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">&#34;5432:5432&#34;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">options</span><span class="p">:</span><span class="w"> </span><span class="p">&gt;-</span><span class="sd">
</span></span></span><span class="line"><span class="cl"><span class="sd">          --health-cmd &#34;pg_isready -U myapp&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">          --health-interval 5s --health-timeout 5s --health-retries 20</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">valkey</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">image</span><span class="p">:</span><span class="w"> </span><span class="l">valkey/valkey:8-alpine</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">ports</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">&#34;6379:6379&#34;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">env</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">DEBUG</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;True&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">DATABASE_URL</span><span class="p">:</span><span class="w"> </span><span class="l">postgresql://myapp:myapp@localhost:5432/myapp</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">REDIS_URL</span><span class="p">:</span><span class="w"> </span><span class="l">redis://localhost:6379</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">PYTHON_JIT</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;0&#34;</span><span class="w">   </span><span class="c"># match production</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">steps</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">uses</span><span class="p">:</span><span class="w"> </span><span class="l">actions/checkout@v7</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">uses</span><span class="p">:</span><span class="w"> </span><span class="l">astral-sh/setup-uv@v10</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">with</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">enable-cache</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">prune-cache</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">run</span><span class="p">:</span><span class="w"> </span><span class="l">uv sync --locked</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">run</span><span class="p">:</span><span class="w"> </span><span class="l">uv run ruff check .</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">run</span><span class="p">:</span><span class="w"> </span><span class="l">uv run mypy myapp/</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">run</span><span class="p">:</span><span class="w"> </span><span class="l">uv run python manage.py test --parallel 4 --noinput</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">app</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">runs-on</span><span class="p">:</span><span class="w"> </span><span class="l">ubuntu-latest</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">timeout-minutes</span><span class="p">:</span><span class="w"> </span><span class="m">20</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">defaults</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">run</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">working-directory</span><span class="p">:</span><span class="w"> </span><span class="l">frontend</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">steps</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">uses</span><span class="p">:</span><span class="w"> </span><span class="l">actions/checkout@v7</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">uses</span><span class="p">:</span><span class="w"> </span><span class="l">actions/setup-node@v7</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">with</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">node-version</span><span class="p">:</span><span class="w"> </span><span class="m">24</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">cache</span><span class="p">:</span><span class="w"> </span><span class="l">npm</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">cache-dependency-path</span><span class="p">:</span><span class="w"> </span><span class="l">frontend/package-lock.json</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">run</span><span class="p">:</span><span class="w"> </span><span class="l">npm ci</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="c"># Expo writes this on `expo start` and it is gitignored,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="c"># so a fresh checkout doesn&#39;t have it.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">run</span><span class="p">:</span><span class="w"> </span><span class="l">printf &#39;/// &lt;reference types=&#34;expo/types&#34; /&gt;\n&#39; &gt; expo-env.d.ts</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">run</span><span class="p">:</span><span class="w"> </span><span class="l">npm run typecheck</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">run</span><span class="p">:</span><span class="w"> </span><span class="l">npx jest --ci</span></span></span></code></pre></div></div>
<p>두 잡은 나란히 돕니다. 지금까지 성공한 35번의 실행에서 앱 잡의 중앙값은 7분쯤, Python 잡은 12분 반쯤입니다.</p>
<p><code>services:</code> 블록이 바로 Compose 파일이 옮겨 간 자리인데, 다음 절에서 다룹니다. 환경 변수는 몇 개와 플래그 하나뿐입니다. 나머지는 전부 개발자가 <code>docker compose up</code>에서 받는 개발용 기본값으로 떨어지기 때문에, 테스트에는 시크릿이 하나도 필요 없습니다. 정말 그런지 보려고 딱 그 환경만, 다른 건 아무것도 없이 테스트 일부를 돌려 확인했습니다.</p>
<p>CI는 제 노트북, 프로덕션 이미지와 같은 인터프리터, 즉 uv가 직접 빌드한 Python 3.15.0으로 돕니다. <code>uv sync</code>가 <code>.python-version</code>을 읽고 정확히 그 빌드를 내려받기 때문입니다. (실제 파일에서는 setup-uv에 <code>python-version-file</code> 입력도 넘기는데, 이건 아무 일도 하지 않습니다. setup-uv v6에는 그런 입력이 없고, 매 실행마다 그렇다는 경고가 붙어 있습니다. 이 글을 쓰다가야 알았습니다.)</p>
<p>인터프리터를 맞춘 보람은 워크플로를 넣은 지 8일 만에 나타났습니다. 10월 19일에 3.15의 JIT 컴파일러를 켰더니, 켠 뒤 첫 실행에서 테스트 하나가 실패했습니다. 앱이 저장할 때마다 지나가는 코드 경로의 평범한 <code>yield from</code>이 <code>AttributeError: 'list' object has no attribute 'send'</code>를 던진 겁니다. 같은 커밋을 JIT를 끄고 돌리면 통과했습니다. 제 Mac은 arm64라서 이 문제를 한 번도 만나지 않았고, 러너는 프로덕션 머신과 같은 x86_64입니다. JIT는 CI에서도 Dockerfile에서도 다시 꺼 두었고, 버그는 프로덕션에 닿지 않았습니다. python/cpython#155823로 올라가 있던 버그로, 3.15.0이 나온 뒤인 10월 13일에 업스트림에서 고쳐졌습니다.</p>
<p>사실 맨 첫 실행도 실패했는데, 이유는 더 시시했습니다. Expo는 <code>expo start</code>를 할 때 <code>expo-env.d.ts</code>를 만들고 이 파일은 gitignore되어 있습니다. 그래서 제가 쓰던 작업 사본에는 모두 있었고, 새로 받은 체크아웃에는 없었죠. TypeScript가 로컬에서는 한 번도 보지 못한 오류 다섯 개를 냈습니다. 그 파일을 써 주는 단계가 해결책입니다.</p>
<p><code>concurrency</code>는 같은 브랜치에 더 새로운 push가 오면 이전 실행을 취소합니다. 지금까지 취소된 12번의 실행은 모두 이렇게 끝났습니다. 커밋 전 훅(pre-commit hook)이 린터를 돌리고, Python이나 TypeScript가 스테이징돼 있으면 타입 체커도 돌리기 때문에 실수는 대부분 push까지 가지도 않습니다.</p>

<h2 class="relative group">Docker Compose 파일은 어디로 갔나
    <div id="docker-compose-파일은-어디로-갔나" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#docker-compose-%ed%8c%8c%ec%9d%bc%ec%9d%80-%ec%96%b4%eb%94%94%eb%a1%9c-%ea%b0%94%eb%82%98" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>앱의 <code>docker-compose.yml</code>에서 CI와 관련된 부분을 예제로 옮긴 것입니다. 실제 파일에는 서비스도 더 있고 환경 변수도 훨씬 많습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">services</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">valkey</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">image</span><span class="p">:</span><span class="w"> </span><span class="l">valkey/valkey:8-alpine</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">ports</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="s2">&#34;6379:6379&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="c"># Host port 55432, not 5432, so it can&#39;t collide with a local Postgres.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">postgres</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">image</span><span class="p">:</span><span class="w"> </span><span class="l">postgres:17-alpine</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">environment</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="l">POSTGRES_USER=myapp</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="l">POSTGRES_PASSWORD=myapp</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="l">POSTGRES_DB=myapp</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">ports</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="s2">&#34;55432:5432&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">volumes</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="l">postgres_data:/var/lib/postgresql/data</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">healthcheck</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">test</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">&#34;CMD-SHELL&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;pg_isready -U myapp -d myapp&#34;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">interval</span><span class="p">:</span><span class="w"> </span><span class="l">5s</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">retries</span><span class="p">:</span><span class="w"> </span><span class="m">10</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">api</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">build</span><span class="p">:</span><span class="w"> </span><span class="l">.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">command</span><span class="p">:</span><span class="w"> </span><span class="l">python manage.py runserver 0.0.0.0:8000</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">volumes</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="l">.:/app</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">ports</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="s2">&#34;8000:8000&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">environment</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="l">DATABASE_URL=postgresql://myapp:myapp@postgres:5432/myapp</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="l">REDIS_URL=redis://valkey:6379</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">depends_on</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">postgres</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">condition</span><span class="p">:</span><span class="w"> </span><span class="l">service_healthy</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">valkey</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">condition</span><span class="p">:</span><span class="w"> </span><span class="l">service_started</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">volumes</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="l">postgres_data:</span></span></span></code></pre></div></div>
<p><code>checks.yml</code>의 <code>services:</code> 블록 옆에 놓고 보면 같은 이미지 두 개입니다. Postgres 17(여기서는 Alpine 빌드, CI에서는 Debian 빌드)과 <code>valkey/valkey:8-alpine</code>. 지금의 관계는 이렇습니다. Compose 파일은 개발자가 돌리는 것이고, CI는 같은 이미지를 서비스 컨테이너로 선언한 다음 개발자가 돌리는 것과 같은 명령, <code>uv run …</code>과 <code>npm run …</code>을 러너에서 바로 돌립니다.</p>
<p>2024년 글과 비교하면, 제가 가장 신경 쓰던 부분은 살아남았습니다. CI 도구는 얇고, 체크와 배포는 제가 직접 돌릴 수 있는 명령입니다. 살아남지 못한 건 CI가 Compose를 호출하는 방식입니다.</p>
<p>앱의 CI는 Docker 이미지를 아예 빌드하지 않습니다. 이미지는 배포할 때 Fly의 빌더가 한 번 빌드하고, CI는 코드가 괜찮은지만 말해 주면 됩니다. 툴체인이 캐시돼 있으면 그건 6초짜리 설치로 끝납니다. 게다가 Compose 파일은 작업 사본을 바인드 마운트하고 데이터를 시드하는데, 테스트 실행이 할 일은 아닙니다. 그러니 CI용 Compose 파일이 따로 필요했을 테고, 그건 같은 서비스를 두 번째로 정의해 손으로 맞춰 가야 한다는 뜻입니다.</p>
<p>그리고 2024년 예제에는 당시 눈치채지 못한 버그가 있었습니다. <code>docker compose build</code>는 이미지를 빌드할 뿐 서비스의 <code>command</code>를 실행하지 않습니다. 그러니 그 파일의 <code>npm test</code>는 CI에서 한 번도 돌지 않았고, 워크플로는 테스트가 통과하든 말든 초록불이었습니다.</p>
<p>그 글이 가장 걱정했던 위험, 즉 CI 업체를 바꾸는 일은 결국 일어나지 않았습니다. 실제로 일어난 이동은 반대쪽 끝에서였습니다. 이 블로그와 그 클라이언트 사이트가 호스팅을 Cloudflare Pages로 옮겼는데, 블로그 쪽은 45줄짜리 워크플로 하나를 새로 쓰는 걸로 끝났습니다. 빌드가 원래 명령 한 줄이었기 때문이죠. 그리고 제가 경고했던 300줄짜리 워크플로요? 하나 있습니다. pyhtml2text의 워크플로입니다. wheel을 Linux, macOS, Windows 러너에서 각각 여러 아키텍처로 빌드해야 해서 긴 건데, 그래서 플랫폼 전용 YAML이 맞는 도구인 유일한 작업이기도 합니다.</p>

<h2 class="relative group">캐싱: 단계별 소요 시간부터 읽기
    <div id="캐싱-단계별-소요-시간부터-읽기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%ba%90%ec%8b%b1-%eb%8b%a8%ea%b3%84%eb%b3%84-%ec%86%8c%ec%9a%94-%ec%8b%9c%ea%b0%84%eb%b6%80%ed%84%b0-%ec%9d%bd%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>GitHub는 모든 단계의 소요 시간을 기록해 두고, <code>gh api repos/&lt;owner&gt;/&lt;repo&gt;/actions/runs/&lt;run-id&gt;/jobs</code>로 꺼내 볼 수 있습니다. 아래는 10월 20일, 앱의 가장 최근 성공 실행입니다.</p>
<table>
	<thead>
			<tr>
					<th>잡</th>
					<th>단계</th>
					<th>초</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Python</td>
					<td>Postgres와 Valkey 시작</td>
					<td>18</td>
			</tr>
			<tr>
					<td>Python</td>
					<td><code>uv sync --locked</code>, 캐시 있음</td>
					<td>6</td>
			</tr>
			<tr>
					<td>Python</td>
					<td>mypy</td>
					<td>27</td>
			</tr>
			<tr>
					<td>Python</td>
					<td>Django 테스트</td>
					<td>761</td>
			</tr>
			<tr>
					<td>App</td>
					<td><code>npm ci</code>, 캐시 있음</td>
					<td>60</td>
			</tr>
			<tr>
					<td>App</td>
					<td>Jest</td>
					<td>333</td>
			</tr>
	</tbody>
</table>
<p>의존성 캐시 두 개는 모두 켜져 있고, 둘 다 저렴한 부분입니다. GitHub가 이 저장소용으로 보관하는 uv 캐시는 200KB 정도인데, setup-uv가 다시 내려받으면 되는 것들은 정리해 버리기 때문입니다. npm 캐시는 400MB에 가깝습니다. 시간이 드는 곳은 테스트이고, 테스트는 이미 4갈래로 병렬 실행됩니다. 실행을 더 빠르게 하고 싶다면 캐시가 아니라 테스트 스위트를 손보겠습니다.</p>
<p>블로그는 정반대입니다. Hugo가 처리한 이미지는 gitignore된 <code>resources/_gen</code>에 있어서, 새 러너마다 커버, 본문 이미지, 플레이스홀더를 전부 다시 인코딩했습니다. 아래 워크플로는 <code>actions/cache</code>로 이것을 복원합니다. 키는 사진 자체의 해시이고, 키가 맞지 않으면 가장 최근의 이전 캐시로 대신합니다. Hugo는 빠진 것만 처리하니까요. 캐시를 넣기 전 마지막 8번의 실행에서 빌드 단계는 33<del>76초 걸렸고, 넣은 뒤 26번은 6</del>20초였습니다. 94초가 한 번 있었을 뿐이고, 같은 커밋에서 플레이스홀더와 두 번째 카드 크기까지 추가했는데도 그렇습니다.</p>
<p>앱의 이미지는 Fly의 빌더에서 빌드되고, 의존성 파일을 코드보다 먼저 복사하며 uv의 다운로드 캐시는 BuildKit 캐시 마운트(<code>RUN --mount=type=cache,target=/root/.cache/uv</code>)에 둡니다. 하지만 더 큰 개선은 캐시가 아니었습니다. 예전 <code>.dockerignore</code>는 블록리스트였는데, 추가 git worktree들을 모아 둔 폴더를 빠뜨렸습니다. worktree마다 자기 의존성과 빌드 산출물이 들어 있었죠. 그래서 파일 27만 7천 개, 7.7GB가 배포할 때마다 빌더로 올라갔습니다. 허용 목록으로 다시 쓴 지금은 빌드 컨텍스트가 40MB 정도입니다. 그 패턴을 예제로 보면 이렇습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl"># Exclude everything, then let back in only what the Dockerfile COPYs.
</span></span><span class="line"><span class="cl">*
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">!pyproject.toml
</span></span><span class="line"><span class="cl">!uv.lock
</span></span><span class="line"><span class="cl">!manage.py
</span></span><span class="line"><span class="cl">!myapp
</span></span><span class="line"><span class="cl">!static
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"># Rules match the whole relative path and the last match wins,
</span></span><span class="line"><span class="cl"># so these re-excludes apply inside the allowed directories too.
</span></span><span class="line"><span class="cl">**/__pycache__/
</span></span><span class="line"><span class="cl">**/*.pyc
</span></span><span class="line"><span class="cl">**/.DS_Store
</span></span><span class="line"><span class="cl">**/*.log</span></span></code></pre></div></div>

<h2 class="relative group">시크릿은 최대한 적은 곳에
    <div id="시크릿은-최대한-적은-곳에" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%8b%9c%ed%81%ac%eb%a6%bf%ec%9d%80-%ec%b5%9c%eb%8c%80%ed%95%9c-%ec%a0%81%ec%9d%80-%ea%b3%b3%ec%97%90" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>시크릿은 세 군데에 있습니다. GitHub Actions 시크릿은 워크플로가 하는 일을 위한 것이고, 두 Hugo 저장소에는 <code>CLOUDFLARE_API_TOKEN</code> 딱 하나씩만 있습니다. Fly 시크릿은 앱의 런타임 설정으로 <code>flyctl secrets set</code>으로 넣고, Actions를 거치지 않습니다. 그리고 제 노트북의 gitignore된 <code>.env</code>에는 배포 스크립트가 Cloudflare 캐시를 비울 때 쓰는 토큰이 있습니다.</p>
<p>PyPI에는 시크릿이 아예 필요 없습니다. pyhtml2text는 신뢰할 수 있는 게시(trusted publishing)를 씁니다. PyPI가 GitHub이 워크플로에 발급하는 수명 짧은 OIDC 토큰을 받아 주기 때문에, 릴리스 잡은 <code>id-token: write</code>만 요청하고 저장소의 시크릿 페이지는 비어 있습니다. 샐 것도, 교체할 것도 없죠.</p>
<p>토큰에는 필요한 만큼만 줍니다. GitHub에 있는 앱의 Fly 토큰은 머신 목록만 조회하는 예약 체크용이라 <code>fly tokens create readonly</code>로 만들었습니다. Pages 배포는 <code>contents: read</code>와 <code>deployments: write</code>만 요청하고 그 이상은 없습니다.</p>
<p>입력값은 스크립트에 바로 넣지 않고 반드시 <code>env:</code>를 거칩니다. OTA 워크플로는 자유롭게 쓰는 릴리스 노트를 받습니다. 이걸 <code>run:</code> 안에 <code>${{ inputs.notes }}</code>로 쓰면 bash가 읽기 전에 텍스트가 스크립트에 그대로 붙여 넣어지니, 따옴표와 세미콜론이 든 노트는 코드가 되어 버립니다. 환경 변수로 넘기면 데이터로 남습니다. 패턴을 예제로 보면 이렇습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Publish</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">env</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">OTA_API_TOKEN</span><span class="p">:</span><span class="w"> </span><span class="l">${{ secrets.OTA_API_TOKEN }}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">INPUT_PLATFORM</span><span class="p">:</span><span class="w"> </span><span class="l">${{ inputs.platform }}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">INPUT_ROLLOUT</span><span class="p">:</span><span class="w"> </span><span class="l">${{ inputs.rollout }}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">INPUT_NOTES</span><span class="p">:</span><span class="w"> </span><span class="l">${{ inputs.notes }}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">run</span><span class="p">:</span><span class="w"> </span><span class="p">|</span><span class="sd">
</span></span></span><span class="line"><span class="cl"><span class="sd">          args=(&#34;$INPUT_PLATFORM&#34;)
</span></span></span><span class="line"><span class="cl"><span class="sd">          [ -n &#34;$INPUT_ROLLOUT&#34; ] &amp;&amp; args+=(--rollout &#34;$INPUT_ROLLOUT&#34;)
</span></span></span><span class="line"><span class="cl"><span class="sd">          [ -n &#34;$INPUT_NOTES&#34; ] &amp;&amp; args+=(--notes &#34;$INPUT_NOTES&#34;)
</span></span></span><span class="line"><span class="cl"><span class="sd">          ./scripts/publish-ota.sh &#34;${args[@]}&#34;</span></span></span></code></pre></div></div>
<p>아예 GitHub 밖에 두는 키도 있습니다. 예약 리포트 하나에는 앱의 로그인 백엔드에 대한 관리자 권한이 있는 키가 필요해서, 그 리포트는 예약 워크플로에서 제 Mac의 예약 작업으로 옮겼습니다. 워크플로는 수동 예비용으로 남아 있고, 그 키가 필요한 섹션은 빼고 게시합니다.</p>

<h2 class="relative group">배포: push마다, 스크립트로, 태그로
    <div id="배포-push마다-스크립트로-태그로" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%eb%b0%b0%ed%8f%ac-push%eb%a7%88%eb%8b%a4-%ec%8a%a4%ed%81%ac%eb%a6%bd%ed%8a%b8%eb%a1%9c-%ed%83%9c%ea%b7%b8%eb%a1%9c" aria-label="앵커">#</a>
    </span>
    
</h2>

<h3 class="relative group">Hugo 사이트는 push마다 배포됩니다
    <div id="hugo-사이트는-push마다-배포됩니다" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#hugo-%ec%82%ac%ec%9d%b4%ed%8a%b8%eb%8a%94-push%eb%a7%88%eb%8b%a4-%eb%b0%b0%ed%8f%ac%eb%90%a9%eb%8b%88%eb%8b%a4" aria-label="앵커">#</a>
    </span>
    
</h3>
<p>블로그 워크플로를 예제로 옮긴 것입니다. Pages 프로젝트를 처음 만드는 단계는 뺐습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Deploy to Cloudflare Pages</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">on</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">push</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">workflow_dispatch</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">env</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">HUGO_VERSION</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;0.165.0&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">PAGES_PROJECT</span><span class="p">:</span><span class="w"> </span><span class="l">my-site</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">concurrency</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">group</span><span class="p">:</span><span class="w"> </span><span class="l">deploy-${{ github.ref }}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">cancel-in-progress</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">jobs</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">deploy</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">runs-on</span><span class="p">:</span><span class="w"> </span><span class="l">ubuntu-latest</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">permissions</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">contents</span><span class="p">:</span><span class="w"> </span><span class="l">read</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">deployments</span><span class="p">:</span><span class="w"> </span><span class="l">write</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">steps</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">uses</span><span class="p">:</span><span class="w"> </span><span class="l">actions/checkout@v7</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">with</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">submodules</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">uses</span><span class="p">:</span><span class="w"> </span><span class="l">peaceiris/actions-hugo@v3</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">with</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">hugo-version</span><span class="p">:</span><span class="w"> </span><span class="l">${{ env.HUGO_VERSION }}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">extended</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="c"># Processed images are gitignored; restore them so Hugo only</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="c"># re-encodes what is new. An older cache still helps.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">uses</span><span class="p">:</span><span class="w"> </span><span class="l">actions/cache@v6</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">with</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="l">resources/_gen</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">key</span><span class="p">:</span><span class="w"> </span><span class="l">hugo-resources-${{ hashFiles(&#39;content/**/*.jpg&#39;, &#39;content/**/*.png&#39;, &#39;assets/img/**&#39;) }}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">restore-keys</span><span class="p">:</span><span class="w"> </span><span class="p">|</span><span class="sd">
</span></span></span><span class="line"><span class="cl"><span class="sd">            hugo-resources-</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="c"># A multilingual site has no root 404.html; without one, Pages</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="c"># answers unknown paths with index.html and a 200.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Build</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">run</span><span class="p">:</span><span class="w"> </span><span class="p">|</span><span class="sd">
</span></span></span><span class="line"><span class="cl"><span class="sd">          hugo --gc
</span></span></span><span class="line"><span class="cl"><span class="sd">          cp public/en/404.html public/404.html</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="c"># ...</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Deploy</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">uses</span><span class="p">:</span><span class="w"> </span><span class="l">cloudflare/wrangler-action@v4</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">with</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">apiToken</span><span class="p">:</span><span class="w"> </span><span class="l">${{ secrets.CLOUDFLARE_API_TOKEN }}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">accountId</span><span class="p">:</span><span class="w"> </span><span class="l">${{ vars.CLOUDFLARE_ACCOUNT_ID }}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">command</span><span class="p">:</span><span class="w"> </span><span class="l">pages deploy public --project-name=${{ env.PAGES_PROJECT }} --branch=${{ github.ref_name }}</span></span></span></code></pre></div></div>
<p><code>--branch=${{ github.ref_name }}</code> 덕분에 <code>main</code>은 프로덕션이 되고 다른 브랜치는 모두 미리보기 URL을 받습니다. 클라이언트 사이트의 워크플로는 이것과 같은 구조에 빌드 전 <code>rm -rf public</code> 한 줄이 더 있습니다. 그쪽은 <code>public/</code>이 커밋되어 있어서, 안 그러면 삭제한 페이지가 업로드에 계속 남기 때문입니다.</p>
<p>Hugo 버전은 여기에서만 고정합니다. 10월에 패키지 매니저 업그레이드로 제 노트북의 Hugo가 0.168이 됐는데, 테마가 지원하는 최신 버전보다 하나 높습니다. 배포는 0.165에 머물렀고 아무 일도 없었습니다.</p>
<p>그리고 빌드가 곧 테스트입니다. 9월 14일, 한 브랜치의 미리보기 배포가 세 번 연달아 실패했습니다. 그 브랜치의 글 하나가 Hugo의 <code>ref</code>로 아직 초안인 글을 가리키고 있었거든요. CI는 프로덕션이 빌드하는 것과 똑같이, 초안을 빼고 빌드합니다. 그러니 링크는 아무것도 가리키지 않았고 Hugo는 <code>REF_NOT_FOUND</code>로 멈췄습니다. 그동안에도 <code>main</code>은 계속 배포되고 있었습니다.</p>

<h3 class="relative group">앱의 API는 스크립트로 배포합니다
    <div id="앱의-api는-스크립트로-배포합니다" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%95%b1%ec%9d%98-api%eb%8a%94-%ec%8a%a4%ed%81%ac%eb%a6%bd%ed%8a%b8%eb%a1%9c-%eb%b0%b0%ed%8f%ac%ed%95%a9%eb%8b%88%eb%8b%a4" aria-label="앵커">#</a>
    </span>
    
</h3>
<p>배포 스크립트의 핵심을 예제로 옮긴 것입니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="nv">IMAGE_LABEL</span><span class="o">=</span><span class="s2">&#34;deploy-</span><span class="k">$(</span>git rev-parse --short HEAD<span class="k">)</span><span class="s2">-</span><span class="k">$(</span>date +%Y%m%d%H%M%S<span class="k">)</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Build first, then wake a spare machine, then roll out exactly that image.</span>
</span></span><span class="line"><span class="cl">flyctl deploy --config fly.toml --build-only --push --image-label <span class="s2">&#34;</span><span class="nv">$IMAGE_LABEL</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">curl -fsS --retry <span class="m">5</span> https://myapp.fly.dev/health &gt; /dev/null
</span></span><span class="line"><span class="cl">flyctl deploy --config fly.toml --image <span class="s2">&#34;registry.fly.io/myapp:</span><span class="nv">$IMAGE_LABEL</span><span class="s2">&#34;</span></span></span></code></pre></div></div>
<p>그리고 <code>fly.toml</code>에서 짝이 되는 부분입니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-toml" data-lang="toml"><span class="line"><span class="cl"><span class="p">[</span><span class="nx">deploy</span><span class="p">]</span>
</span></span><span class="line"><span class="cl">  <span class="c"># max_unavailable only counts machines that are running,</span>
</span></span><span class="line"><span class="cl">  <span class="c"># which is why the script wakes one first.</span>
</span></span><span class="line"><span class="cl">  <span class="nx">strategy</span> <span class="p">=</span> <span class="s2">&#34;rolling&#34;</span>
</span></span><span class="line"><span class="cl">  <span class="nx">max_unavailable</span> <span class="p">=</span> <span class="mi">1</span></span></span></code></pre></div></div>
<p>이미지는 한 번 빌드해서 커밋과 시각으로 만든 라벨을 붙여 Fly 레지스트리에 올리고, 그 라벨로 배포합니다. 그래서 롤아웃되는 건 정확히 빌드한 그것입니다.</p>
<p>무중단 배포를 가능하게 하는 건 예비 머신을 먼저 깨우는 단계입니다. <code>max_unavailable = 1</code>은 실행 중인 머신만 셉니다. 그런데 앱은 한가할 때 실행 중인 머신을 하나도 두지 않습니다(일시 정지된 머신은 1초 남짓이면 깨어납니다). 그래서 깨어 있던 머신 하나가 잠든 머신들과 같은 묶음에서 교체되곤 했고, 그 뒤에는 따뜻한 머신이 하나도 없었습니다. 9월 28일에 오리진에 프로브를 계속 보내 봤더니, 그냥 <code>flyctl deploy</code>를 할 때는 타임아웃 7번과 7.3초의 공백이 있었고, 먼저 빌드하고 롤아웃 전에 머신 하나를 깨워 두는 스크립트 배포로는 요청 2,514개 중 실패가 하나도 없었습니다.</p>
<p>스크립트의 나머지는 오류 알림이 오는 팀 채팅 채널에 배포 표시를 남깁니다. 그래야 오류가 몰렸을 때 방금 무엇이 바뀌었는지와 맞춰 볼 수 있죠. 그리고 Cloudflare 캐시를 비우고 머신들을 데워 둡니다. 웹 프런트엔드는 이미지를 아예 거치지 않는데, 그건 <a href="https://jared.lynskey.co.nz/ko/posts/2026/2026-09-14-web-releases-without-redeploying/" >프론트엔드와 백엔드 따로 배포하기</a>에 적었습니다.</p>
<p>마이그레이션은 파이프라인 단계가 아닙니다. Fly의 <code>release_command</code>가 제 환경에서는 멈춰 버려서, 새 이미지로 처음 부팅하는 머신이 락을 잡고 마이그레이션하는 동안 나머지는 기다립니다. 그러니 모든 마이그레이션은 아직 돌고 있는 코드와도 맞아야 합니다. 컬럼은 한 배포에서 추가하고, 다음 배포에서 쓰지 않게 하고, 세 번째 배포에서 지웁니다.</p>
<p>이 스크립트에 꼭 제 노트북이어야 하는 부분은 없지만, 노트북에만 있는 파일 몇 개가 스크립트를 거기 묶어 둡니다. Cloudflare 자격 증명, 그리고 마지막으로 무엇을 배포했는지 적어 둔 기록입니다. 새 러너에는 이 파일들이 없죠. 커밋하지 않은 변경도 배포해 버리고 채팅 채널에 그렇다고 알리는데, 웹 릴리스 스크립트는 더러운 작업 트리를 거부합니다.</p>
<p><a href="https://jared.lynskey.co.nz/ko/posts/2026/2026-09-19-ephemeral-dev-environments-on-fly/" >브랜치별 프리뷰 환경</a>에서 저는 이걸 손으로 하는 건 혼자일 때는 괜찮지만, 두 번째 개발자부터는 git에서 뭔가 일어났기 때문에 일어나야 한다고 썼습니다. 앱의 개발자는 아직 한 명입니다. 그 글의 브랜치 환경 워크플로는 제가 만들었던 브랜치에 그대로 있습니다.</p>
<p>OTA 워크플로는 수동 전용입니다. 게시는 결정이어야 하고, 업데이트 서비스는 부분 롤아웃이 열려 있는 동안 새 릴리스를 거부하기 때문에 push 트리거라면 카나리 배포 때마다 걸릴 테니까요. 이 워크플로는 한 번도 실행된 적이 없습니다. 지금까지 OTA 업데이트는 전부 제 노트북에서, 워크플로가 호출하는 것과 같은 스크립트로 나갔습니다. 얇은 워크플로를 쓰는 이유가 한 줄로 이겁니다. 릴리스를 어떻게 시작하든 같은 스크립트죠.</p>

<h3 class="relative group">pyhtml2text는 태그로 릴리스합니다
    <div id="pyhtml2text는-태그로-릴리스합니다" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#pyhtml2text%eb%8a%94-%ed%83%9c%ea%b7%b8%eb%a1%9c-%eb%a6%b4%eb%a6%ac%ec%8a%a4%ed%95%a9%eb%8b%88%eb%8b%a4" aria-label="앵커">#</a>
    </span>
    
</h3>
<p>릴리스 잡입니다. 패키지 이름은 일반적인 이름으로 바꿨습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="w">  </span><span class="nt">release</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">runs-on</span><span class="p">:</span><span class="w"> </span><span class="l">ubuntu-latest</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">if</span><span class="p">:</span><span class="w"> </span><span class="l">${{ startsWith(github.ref, &#39;refs/tags/&#39;) || github.event_name == &#39;workflow_dispatch&#39; }}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">needs</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="l">linux, macos, windows, sdist]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">environment</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">pypi</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">url</span><span class="p">:</span><span class="w"> </span><span class="l">https://pypi.org/p/mypackage</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">permissions</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">id-token</span><span class="p">:</span><span class="w"> </span><span class="l">write      </span><span class="w"> </span><span class="c"># trusted publishing and signing</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">contents</span><span class="p">:</span><span class="w"> </span><span class="l">write</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">attestations</span><span class="p">:</span><span class="w"> </span><span class="l">write</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">steps</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">uses</span><span class="p">:</span><span class="w"> </span><span class="l">actions/download-artifact@v8</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">uses</span><span class="p">:</span><span class="w"> </span><span class="l">actions/attest@v4</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">with</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">subject-path</span><span class="p">:</span><span class="w"> </span><span class="s1">&#39;wheels-*/*&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">uses</span><span class="p">:</span><span class="w"> </span><span class="l">astral-sh/setup-uv@v10</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">if</span><span class="p">:</span><span class="w"> </span><span class="l">${{ startsWith(github.ref, &#39;refs/tags/&#39;) }}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">with</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">prune-cache</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Publish to PyPI</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">if</span><span class="p">:</span><span class="w"> </span><span class="l">${{ startsWith(github.ref, &#39;refs/tags/&#39;) }}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">run</span><span class="p">:</span><span class="w"> </span><span class="l">uv publish --trusted-publishing always &#39;wheels-*/*&#39;</span></span></span></code></pre></div></div>
<p>릴리스 잡은 모든 빌드 잡을 기다리고, 실제 게시는 태그일 때만 합니다. 수동 실행은 빌드하고 증명(attestation)까지 만들지만 아무것도 올리지 않습니다. <code>actions/attest</code>는 어느 워크플로가 각 wheel을 빌드했는지 기록하고, <code>uv publish --trusted-publishing always</code>는 비밀번호 대신 OIDC 토큰으로 업로드합니다. 패키지 자체에 대해서는 <a href="https://jared.lynskey.co.nz/ko/posts/2026/2026-10-18-pyhtml2text/" >닫힌 풀 리퀘스트, 포크, 그리고 PyPI 패키지</a>에 썼습니다.</p>

<h2 class="relative group">예약 워크플로는 최선을 다할 뿐입니다
    <div id="예약-워크플로는-최선을-다할-뿐입니다" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%98%88%ec%95%bd-%ec%9b%8c%ed%81%ac%ed%94%8c%eb%a1%9c%eb%8a%94-%ec%b5%9c%ec%84%a0%ec%9d%84-%eb%8b%a4%ed%95%a0-%eb%bf%90%ec%9e%85%eb%8b%88%eb%8b%a4" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>앱에는 예약 워크플로가 하나 있습니다. Fly가 기준치보다 머신을 더 띄우지 않았는지 보는 체크로, 그냥 두면 청구서에서 처음 알게 될 일입니다. 알림은 일부러 실패하는 방식으로 보냅니다. 예약 실행이 실패하면 GitHub이 소유자에게 메일을 보내니까요.</p>
<p>설정은 <code>cron: '*/15 * * * *'</code>, 하루 96번입니다. 그런데 지난 2주 동안은 하루 3~8번만 돌았고, 실행 간격의 중앙값은 3시간 40분쯤이었습니다. GitHub 문서가 내놓는 설명은 부하뿐입니다. Actions가 바쁘면 예약 실행이 늦어질 수 있고, 아주 바쁘면 빠질 수도 있다는 거죠. 계속되는 스케일 아웃이라면 몇 시간이면 충분합니다. 몇 분 안에 울려야 하는 것이라면 GitHub의 cron은 모니터링이 아닙니다.</p>

<h2 class="relative group">파이프라인에 던져 볼 질문
    <div id="파이프라인에-던져-볼-질문" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ed%8c%8c%ec%9d%b4%ed%94%84%eb%9d%bc%ec%9d%b8%ec%97%90-%eb%8d%98%ec%a0%b8-%eb%b3%bc-%ec%a7%88%eb%ac%b8" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>파이프라인을 만들고 있거나 이미 있는 걸 들여다보고 있다면:</p>
<ol>
<li>GitHub Actions가 하루 동안 멈추면 그래도 릴리스할 수 있나요? 못 한다면 릴리스 로직이 YAML 안에 있는 것이고, 2024년 글이 여전히 유효합니다.</li>
<li>CI가 프로덕션과 같은 인터프리터, 같은 CPU 아키텍처, 같은 데이터베이스 메이저 버전으로 도나요? 제 CI가 컴파일러 버그를 잡은 건 러너와 프로덕션은 둘 다 x86_64이고 제 노트북은 아니었기 때문입니다.</li>
<li>새로 받은 체크아웃이 통과하나요? 안 된다면 대개 생성되고 gitignore된 파일 때문입니다.</li>
<li>실행 시간은 실제로 어디에 쓰이나요? 캐시를 넣기 전에 단계별 소요 시간부터 읽어 보세요.</li>
<li>시크릿마다 몇 군데에 있나요? 그리고 정말 GitHub에 있어야 하나요?</li>
</ol>
]]></content:encoded>
      <media:content url="https://jared.lynskey.co.nz/en/posts/2026/2026-10-22-docker-compose-ci-github-actions/featured.jpg" medium="image" type="image/jpeg" />
    </item>
    <item>
      <title>ChatGPT에 인용되려면: 작은 블로그에서 한 일과 로그가 보여 준 것</title>
      <link>https://jared.lynskey.co.nz/ko/posts/2026/2026-09-16-blog-as-a-source-for-ai-assistants/</link>
      <guid isPermaLink="true">https://jared.lynskey.co.nz/ko/posts/2026/2026-09-16-blog-as-a-source-for-ai-assistants/</guid>
      <pubDate>Wed, 16 Sep 2026 00:00:00 +1200</pubDate>
      <dc:creator>Jared Lynskey</dc:creator>
      <category>SEO</category>
      <category>Crawlers</category>
      <category>LLM</category>
      <category>Hugo</category>
      <category>Cloudflare</category>
      <category>Content Strategy</category>
      <category>Writing</category>
      <description>ChatGPT 같은 AI 어시스턴트에 인용되려고(GEO) 이 블로그에서 한 일. 들여보내야 할 봇, 브라우저 없이 읽히는 HTML, 저자가 들어간 구조화 데이터, 그리고 아무도 읽지 않은 llms.txt.</description>
      <content:encoded><![CDATA[<p>ChatGPT 같은 AI 어시스턴트에 인용되고 싶다면 먼저 답변할 때 페이지를 가져가는 검색용 봇을 들여보내야 합니다. 학습용 크롤러와는 별개라서, 한쪽을 막아도 다른 쪽에는 아무 영향이 없습니다. 그다음은 JavaScript 없이도 읽히는 HTML을, 저자 이름이 든 구조화 데이터와 함께 내보내는 것입니다. llms.txt는 제 로그로 보면 요청하는 곳이 없어서 아무 효과가 없고, 가장 중요한 건 각 섹션이 첫 문장에서 주장을 밝히고 문단 하나를 따로 떼어 인용할 수 있게 쓰는 일입니다.</p>
<p>이 블로그의 검색 유입은 2년쯤 제자리이고, 이제는 움직이길 기대하지도 않습니다. 그래서 대신 방문자가 어디서 오는지, 그 안에 AI 어시스턴트도 있는지를 들여다봤습니다. 있긴 합니다. 간신히요. 2026년 9월 16일까지 열두 달 동안 방문 분석 도구가 센 세션은 5,372개였습니다. 그중 AI 어시스턴트에서 온 건 27개. chatgpt.com에서 12개, gemini.google.com에서 9개, Perplexity에서 6개, claude.ai에서는 하나도 없었습니다. 0.5퍼센트죠. 다만 ChatGPT에서 온 방문자는 좋은 쪽이었습니다. 직접 유입이 평균 27초, 구글이 3분 머무는 동안 이쪽은 평균 5분을 머물렀습니다. 이미 답을 읽고 자세한 내용을 보러 온 사람들이니까요.</p>
<p><figure><span class="mc-img"><img
    class="my-0 rounded-md"
    loading="lazy"
    decoding="async"
    fetchpriority="auto"
    alt="12개월간 유입 경로별 세션 수, AI 어시스턴트 강조"
    width="2400"
    height="1164"
    src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-16-blog-as-a-source-for-ai-assistants/chart-referrers_hu_590f408ed875db1f.webp"
    srcset="https://jared.lynskey.co.nz/en/posts/2026/2026-09-16-blog-as-a-source-for-ai-assistants/chart-referrers_hu_590f408ed875db1f.webp 800w, https://jared.lynskey.co.nz/en/posts/2026/2026-09-16-blog-as-a-source-for-ai-assistants/chart-referrers_hu_d8da7a3f1d1c9190.webp 1280w"
    sizes="(min-width: 768px) 50vw, 65vw"
    data-zoom-src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-16-blog-as-a-source-for-ai-assistants/chart-referrers_hu_b3dda7d23abf271d.webp"></span><figcaption>12개월간 유입 경로별 세션 수입니다. 파란 막대가 AI 어시스턴트로, 5,372세션 중 27세션입니다.</figcaption></figure>
</p>
<p>그래서 작은 블로그가 그런 답변의 출처로 뽑히려면 뭐가 필요한지 시간을 좀 들여 봤습니다. 이 글은 제가 이 사이트에 한 일과, 로그가 그에 대해 뭐라고 하는지입니다. 숫자가 있는 곳에는 숫자를 적고, 추측인 곳은 추측이라고 밝히겠습니다. 초고에 있던 문장 세 개는 막상 들여다보니 틀린 것으로 드러났는데, 고친 흔적은 그대로 남겨 뒀습니다.</p>

<h2 class="relative group">봇은 두 종류이고, 인용하는 쪽은 하나뿐입니다
    <div id="봇은-두-종류이고-인용하는-쪽은-하나뿐입니다" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%eb%b4%87%ec%9d%80-%eb%91%90-%ec%a2%85%eb%a5%98%ec%9d%b4%ea%b3%a0-%ec%9d%b8%ec%9a%a9%ed%95%98%eb%8a%94-%ec%aa%bd%ec%9d%80-%ed%95%98%eb%82%98%eb%bf%90%ec%9e%85%eb%8b%88%eb%8b%a4" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>먼저 짚고 갈 것은 &ldquo;AI 봇&quot;이라는 게 사실 서로 다른 유저 에이전트를 쓰는 두 가지 다른 일이고, 한쪽을 막아도 다른 쪽에는 아무 영향이 없다는 점입니다.</p>
<p>학습용 크롤러는 다음 모델을 만들려고 페이지를 대량으로 긁어 갑니다. OpenAI는 GPTBot, Anthropic은 ClaudeBot이고, 구글은 Google-Extended 토큰으로, 애플은 Applebot-Extended로 제어하며, Common Crawl의 CCBot은 공개 데이터셋 대부분에 들어갑니다. 이들이 가져간 건 가중치가 되어 끝이고, 여러분에게 돌아오는 링크는 없습니다. 이쪽을 막아야 한다는 주장에는 일리가 있고, 저도 터무니없는 얘기라고는 생각하지 않습니다.</p>
<p>검색용 봇은 다른 종류입니다. 누군가 ChatGPT나 Claude, Perplexity에 질문하면 어시스턴트는 검색을 돌리고, 그 자리에서 페이지 몇 개를 가져와 읽은 다음, 인용을 달아 답을 씁니다. 그 요청은 OAI-SearchBot과 ChatGPT-User, Claude-SearchBot과 Claude-User, PerplexityBot과 Perplexity-User로 들어옵니다. 구글의 AI 오버뷰는 그냥 Googlebot을 쓰기 때문에 따로 끌 스위치 자체가 없습니다. 방문자를 돌려보내 주는 건 이쪽 봇들입니다. 목표가 인용되는 거라면 최적화 대상은 이쪽이고, GPTBot을 막아도 ChatGPT 검색 결과에는 어느 방향으로도 아무 영향이 없다는 건 알아 둘 만합니다.</p>
<p>이 사이트의 robots.txt는 Hugo 기본값 그대로, 전부 허용입니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">User-agent: *
</span></span><span class="line"><span class="cl">Allow: /
</span></span><span class="line"><span class="cl">Sitemap: https://jared.lynskey.co.nz/sitemap.xml</span></span></code></pre></div></div>
<p>검색용 봇은 들이고 학습용은 막는 식으로 나눌까 생각해 봤지만, 읽히는 게 존재 이유의 전부인 블로그에서 그럴 만한 가치는 없다고 결론 내렸습니다. 굳이 하자면 아래 블록처럼 될 겁니다. 이걸 보여 드리는 이유는 <a href="https://jared.lynskey.co.nz/ko/posts/2026/2026-09-09-cloudflare-crawlers-cache/" >Cloudflare가 Googlebot에게 빈 페이지를 내줬다</a>에서와 같은 교훈 때문입니다. 목록에는 회사가 아니라 봇 이름을 적어야 합니다. &ldquo;OpenAI&quot;라고 쓸 수 있는 줄은 없습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">User-agent: GPTBot
</span></span><span class="line"><span class="cl">User-agent: ClaudeBot
</span></span><span class="line"><span class="cl">User-agent: Google-Extended
</span></span><span class="line"><span class="cl">User-agent: Applebot-Extended
</span></span><span class="line"><span class="cl">User-agent: CCBot
</span></span><span class="line"><span class="cl">Disallow: /
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">User-agent: *
</span></span><span class="line"><span class="cl">Allow: /</span></span></code></pre></div></div>
<p>사이트가 Cloudflare 뒤에 있다면 확인할 게 하나 있습니다. 2025년 중반부터 거기서 새로 만드는 존은 기본으로 AI 크롤러를 막고, 봇 설정에는 기존 존에도 같은 걸 적용하는 원클릭 토글이 있습니다. 두 종류를 다 막습니다. 이 블로그는 지난주에 Cloudflare Pages로 옮겼기 때문에 이것도 제 확인 목록에 있었습니다. &ldquo;AI 봇&quot;이라는 말이 막아야 할 무언가처럼 들려서 켰다면, 인용도 같이 꺼 버린 겁니다. 그 뒤로 Cloudflare는 자기가 관리하는 robots.txt 파일에 <code>search</code>, <code>ai-input</code>, <code>ai-train</code> 플래그를 따로 둔 <code>Content-Signal</code> 줄을 쓰기 시작했습니다. 아무도 지킬 의무는 없지만 어휘는 제대로 골랐습니다. 위와 같은 구분을 벽이 아니라 선호로 표현한 거니까요.</p>

<h2 class="relative group">실제로 문을 두드리는 건 누구인가
    <div id="실제로-문을-두드리는-건-누구인가" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%8b%a4%ec%a0%9c%eb%a1%9c-%eb%ac%b8%ec%9d%84-%eb%91%90%eb%93%9c%eb%a6%ac%eb%8a%94-%ea%b1%b4-%eb%88%84%ea%b5%ac%ec%9d%b8%ea%b0%80" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>Cloudflare로 옮긴 데는 부수 효과가 하나 있었습니다. 처음으로 모든 요청을 유저 에이전트별로 볼 수 있게 된 겁니다. 2026년 9월 13일부터 16일까지 나흘 동안 들어온 건 아래와 같습니다. 가짜는 걸러낸 숫자인데, 그 얘기는 곧 하겠습니다.</p>
<table>
	<thead>
			<tr>
					<th>봇</th>
					<th>요청 수</th>
					<th>한 일</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>ClaudeBot (학습용)</td>
					<td>1,777</td>
					<td>이틀 동안 서로 다른 페이지 1,380개, 다섯 개 언어 전부, 거기에 robots.txt 37번</td>
			</tr>
			<tr>
					<td>meta-externalagent (학습용)</td>
					<td>1,748</td>
					<td>같은 일을 하루 늦게</td>
			</tr>
			<tr>
					<td>OAI-SearchBot (ChatGPT 검색 인덱스)</td>
					<td>59</td>
					<td>다섯 개 언어의 페이지들, 그리고 robots.txt 16번</td>
			</tr>
			<tr>
					<td>ChatGPT-User (답변 중 가져감)</td>
					<td>20</td>
					<td>콜드 스타트 글의 일본어판, 직접 운영하는 업데이트 서버 글, 홈페이지</td>
			</tr>
			<tr>
					<td>Claude-User (답변 중 가져감)</td>
					<td>8</td>
					<td>업데이트 서버 글, 연락처 페이지, 홈페이지</td>
			</tr>
			<tr>
					<td>PerplexityBot</td>
					<td>2</td>
					<td>iOS 디버깅 글, 영어판과 베트남어판</td>
			</tr>
			<tr>
					<td>Claude-SearchBot, Perplexity-User</td>
					<td>0</td>
					<td></td>
			</tr>
			<tr>
					<td>Googlebot / Bingbot / Applebot / CCBot</td>
					<td>168 / 71 / 45 / 28</td>
					<td></td>
			</tr>
	</tbody>
</table>
<p>눈에 띄는 게 두 가지 있습니다. 검색용 봇이 페이지 수십 개를 읽는 사이 학습용 크롤러는 전부를 두 번씩 읽었습니다. 그리고 검색용 봇은 아무거나 가져가지 않습니다. ChatGPT-User와 Claude-User 둘 다 이 사이트에서 가장 구체적인 글인 업데이트 서버 글을 집어 갔고, 콜드 스타트 글은 일본어판으로 가져갔습니다.</p>
<p>이제 가짜 얘기입니다. GPTBot이라고 주장한 요청 20개 중 18개는 OpenAI가 공개한 IP 대역 밖에서 왔고, <code>/.env</code>, <code>/.git/HEAD</code>, <code>/firebase-adminsdk.json</code>을 달라고 했습니다. &ldquo;ChatGPT-User&rdquo; 요청 36개 중 15개도 같은 부류였습니다. &ldquo;PerplexityBot&rdquo; 트래픽은 대부분 <code>/id_ed25519</code>를 원했습니다. 유저 에이전트는 누구나 보낼 수 있는 문자열이고, 취약점 스캐너들은 AI 봇 이름을 달면 그냥 통과된다는 걸 눈치챘습니다. OpenAI, Anthropic, Perplexity 모두 IP 대역을 공개합니다. 봇을 어느 방향으로든 특별 취급할 거라면 이름이 아니라 주소를 확인해야 합니다. 위 표의 20, 59, 8은 제대로 된 주소에서 온 요청만 센 숫자입니다.</p>
<p><figure><span class="mc-img"><img
    class="my-0 rounded-md"
    loading="lazy"
    decoding="async"
    fetchpriority="auto"
    alt="OpenAI 사용자 에이전트를 내세운 요청을 OpenAI 공개 IP 대역에서 왔는지로 나눈 그래프"
    width="2400"
    height="722"
    src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-16-blog-as-a-source-for-ai-assistants/chart-spoofed_hu_e7035266dc7ce0b1.webp"
    srcset="https://jared.lynskey.co.nz/en/posts/2026/2026-09-16-blog-as-a-source-for-ai-assistants/chart-spoofed_hu_e7035266dc7ce0b1.webp 800w, https://jared.lynskey.co.nz/en/posts/2026/2026-09-16-blog-as-a-source-for-ai-assistants/chart-spoofed_hu_638e8c6286f5c91f.webp 1280w"
    sizes="(min-width: 768px) 50vw, 65vw"
    data-zoom-src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-16-blog-as-a-source-for-ai-assistants/chart-spoofed_hu_11d44262308d7c6c.webp"></span><figcaption>같은 사용자 에이전트 문자열을 출발지 주소로 나눈 것입니다. &lsquo;GPTBot&rsquo;이라 주장한 트래픽 대부분은 OpenAI에서 오지 않았습니다.</figcaption></figure>
</p>

<h2 class="relative group">페이지는 브라우저 없이도 읽혀야 합니다
    <div id="페이지는-브라우저-없이도-읽혀야-합니다" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ed%8e%98%ec%9d%b4%ec%a7%80%eb%8a%94-%eb%b8%8c%eb%9d%bc%ec%9a%b0%ec%a0%80-%ec%97%86%ec%9d%b4%eb%8f%84-%ec%9d%bd%ed%98%80%ec%95%bc-%ed%95%a9%eb%8b%88%eb%8b%a4" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>검색용 봇은 답변하는 그 시점에 타임아웃을 걸고 페이지를 가져오며, 대부분 JavaScript를 실행하지 않습니다. 번들이 로드되기 전까지 빈 div인 페이지는 그들이 읽지 않는 페이지입니다. Hugo는 완성된 HTML을 써 주니 이 블로그는 그걸 공짜로 얻고, 제가 더 영리한 무언가로 옮기고 싶었던 적이 한 번도 없는 주된 이유이기도 합니다. 제가 운영하는 마켓플레이스는 정반대 경우인 React Native 웹앱이라, 크롤러에게 제대로 된 문서를 주기까지 동적 렌더링 분기가 하나 필요했고, 그다음엔 그걸 조용히 되돌려 버린 캐싱 버그가 있었습니다. 위의 Cloudflare 글이 그 이야기입니다.</p>
<p>속도도 같은 식으로 셈에 들어가는데, 여기서 로그가 저를 바로잡았습니다. Cloudflare 뒤에 있는 정적 사이트는 가장 가까운 엣지에서 나간다고 넘겨짚고 있었거든요. 아닙니다. 이 블로그는 Cloudflare Pages에 있고, HTML은 캐시되지 않은 채 나가며, 서울에서 요청하면 응답이 로스앤젤레스에서 0.5초쯤 걸려 돌아옵니다. 타임아웃이 몇 초인 봇에게는 그래도 충분하지만, 제가 장담했을 법한 수십 밀리초는 아니고, 이걸 아는 것도 직접 재 봤기 때문입니다. 페이지 여섯 개로 답을 짜는 어시스턴트는 3초 걸리는 하나를 그냥 버립니다. 버렸다고 말해 주지도 않습니다.</p>

<h2 class="relative group">문단 하나를 그대로 떼어 갈 수 있게 쓰기
    <div id="문단-하나를-그대로-떼어-갈-수-있게-쓰기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%eb%ac%b8%eb%8b%a8-%ed%95%98%eb%82%98%eb%a5%bc-%ea%b7%b8%eb%8c%80%eb%a1%9c-%eb%96%bc%ec%96%b4-%ea%b0%88-%ec%88%98-%ec%9e%88%ea%b2%8c-%ec%93%b0%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>이 시스템들이 페이지를 쓰는 방식은 독자가 읽는 방식과 다릅니다. 페이지를 청크로 쪼개고, 청크마다 질문에 대해 점수를 매기고, 점수가 나오는 것을 인용합니다. 800단어에 걸쳐 요점을 향해 쌓아 올라가는 글은 모든 청크에서 점수가 낮습니다. 섹션마다 첫 문장에서 주장을 말하고 그다음에 뒷받침하는 글은 질문에 맞는 섹션에서 점수를 냅니다.</p>
<p>이게 어떤 기술적인 것보다 제가 여기 글을 쓰는 방식을 많이 바꿨습니다. 프런트매터의 description은 이제 읽어 보라고 낚는 문구가 아니라 글이 말하는 내용의 요약입니다. 어시스턴트가 보여 주는 게 description뿐인 경우가 많거든요. 섹션 제목은 그 섹션이 내리는 결론을 말합니다. 숫자는 차트가 아니라 단위와 함께 문장 안에 들어갑니다. 날짜는 풀어서 씁니다. 1년 뒤에 이 페이지를 읽는 모델에게 &ldquo;지난주&quot;는 아무 뜻도 없으니까요. 그리고 글 하나는 한 가지에 대해서만 씁니다.</p>
<p>나머지 절반은 인용할 만한 게 있느냐인데, 여기서는 데이터가 엇갈립니다. 로그를 보면 답변 시점에 봇이 가져가는 페이지는 구체적인 글들입니다. 콜드 스타트, 업데이트 서버, iOS 디버깅. 네이버 크롤러는 Yeti이고 다음 크롤러는 Daumoa다, 제가 쓰는 호스팅의 재시작은 504가 나는 30초짜리 구간이다, Cloudflare의 실시간 Brotli 압축은 제 번들에서 gzip보다 나쁘게 측정됐다. 이런 사실은 적혀 있는 곳이 많지 않아서, 그중 하나가 필요한 질문은 여기로 옵니다. 그런데 어시스턴트에서 클릭해 들어오는 사람들은 대부분 2023년과 2024년에 쓴 관리에 대한 글에 내려앉습니다. 글마다 한두 세션씩요. 구체적인 글은 기계가 읽고, 일반적인 글은 클릭을 받습니다. 이걸 깔끔하게 설명할 방법이 저한테는 없고, 지어내느니 그대로 보고하는 편을 택하겠습니다. 지렛대가 있다면 그건 여전히, 이번 주에 알아냈는데 검색했을 때는 찾을 수 없었던 그 구체적인 것을 적어 두는 겁니다. 기계가 실제로 읽는 건 그쪽이라는 게 로그에 보이니까요.</p>

<h2 class="relative group">누가 썼는지 밝히고, 계속 같은 말을 하기
    <div id="누가-썼는지-밝히고-계속-같은-말을-하기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%eb%88%84%ea%b0%80-%ec%8d%bc%eb%8a%94%ec%a7%80-%eb%b0%9d%ed%9e%88%ea%b3%a0-%ea%b3%84%ec%86%8d-%ea%b0%99%ec%9d%80-%eb%a7%90%ec%9d%84-%ed%95%98%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>페이지를 인용할지 결정하는 어시스턴트는 꼼꼼한 독자가 하는 것과 비슷한 일을 합니다. 누가 썼고, 언제 썼고, 내가 찾은 다른 것들과 맞아떨어지는가? 이 사이트에서 그 부분의 기계적인 처리는 대부분 테마가 해 줍니다. 모든 글에 저자, 게시일, 수정일이 든 Article 구조화 데이터가 붙고, 저자는 같은 공개 프로필들로 링크된 Person입니다. 템플릿 몇 줄이지만 &ldquo;페이지 하나&quot;와 &ldquo;이력이 있는 특정 사람이 쓴 페이지&quot;의 차이가 거기서 납니다.</p>
<p>테마가 해 주지 않는 부분은 일관성입니다. 소개 페이지, llms.txt, 공개 프로필, 모든 글 맨 위의 한 줄이 전부 같은 사람을 같은 경력으로 설명합니다. 뭔가 바뀌면 전부 바꿔야 하고, 아니면 깜빡한 하나가 틀린 하나가 됩니다. 까다롭게 들리지만, 한 페이지는 제가 엔지니어링 매니저라고 하고 다른 페이지는 프리랜서라고 하는 건 모델이 얼버무리거나 다른 사람을 고르게 만드는 바로 그런 종류의 모순입니다.</p>
<p>수정일도 정직해야 합니다. 내용이 바뀔 때 바뀌고, 그 외에는 손대지 않습니다. 신선해 보이려고 날짜를 올리는 건 한 번은 통하고 그다음엔 도메인 전체가 평가절하되는 종류의 일입니다.</p>

<h2 class="relative group">llms.txt란 무엇인가, 그리고 아무것도 읽지 않는다는 사실
    <div id="llmstxt란-무엇인가-그리고-아무것도-읽지-않는다는-사실" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#llmstxt%eb%9e%80-%eb%ac%b4%ec%97%87%ec%9d%b8%ea%b0%80-%ea%b7%b8%eb%a6%ac%ea%b3%a0-%ec%95%84%eb%ac%b4%ea%b2%83%eb%8f%84-%ec%9d%bd%ec%a7%80-%ec%95%8a%eb%8a%94%eb%8b%a4%eb%8a%94-%ec%82%ac%ec%8b%a4" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>llms.txt는 2024년 9월에 나온 제안으로, 사이트 루트에 언어 모델에게 사이트 요약과 골라 놓은 링크 목록을 주는 Markdown 파일을 두자는 겁니다. 저는 올해 2월에 하나 추가했습니다. 제가 누구인지 한 문단, 그다음 관리, 인프라, 모바일, 커뮤니티 섹션이 있고, 글마다 제목, URL, 그 글이 내리는 결론 한 문장으로 된 한 줄이 있습니다. 바쁜 사람을 위해 쓴 목차처럼 읽힙니다.</p>
<p>단서는, 아무것도 이 파일을 읽지 않는다는 겁니다. 제가 가진 나흘치 로그에서 <code>/llms.txt</code> 요청은 제가 보낸 것뿐이었습니다. Common Crawl은 2026년 8월 크롤에서 이 사이트의 페이지 76개를 담아 갔지만 그 파일은 한 번도 가져가지 않았습니다. 주요 어시스턴트 중 이 파일을 읽는다고 밝힌 곳도 없습니다. 그러니 여기 있는 뭔가가 인용되는 이유가 이 파일은 아니고, 그런 이유로 누군가에게 권하는 것도 삼가겠습니다. 그래도 두 가지 이유로 두고 있습니다. 한 시간 들었는데, 글마다 실제로 뭘 결론 내리는지 한 문장씩 쓰는 일이 파일 자체보다 값어치가 있었습니다. 어떤 글이 아무것도 결론 내리지 않는지 보여 줬거든요. 그리고 사이트가 뭘 위한 곳인지 기계에게 말해 주는 유일한 페이지라서, 필요 없더라도 있는 편이 낫습니다. 손으로 쓰다 보니 깜빡해서 그 뒤로 어긋나긴 했는데, 그게 Hugo 출력 포맷으로 프런트매터에서 생성하자는 쪽의 논거입니다. 할 일 목록에 있습니다.</p>

<h2 class="relative group">피드, 사이트맵, 그리고 다섯 개 언어
    <div id="피드-사이트맵-그리고-다섯-개-언어" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ed%94%bc%eb%93%9c-%ec%82%ac%ec%9d%b4%ed%8a%b8%eb%a7%b5-%ea%b7%b8%eb%a6%ac%ea%b3%a0-%eb%8b%a4%ec%84%af-%ea%b0%9c-%ec%96%b8%ec%96%b4" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>재미없는 기본 설비도 여전히 중요합니다. 크롤러가 올라간 당일에 새 글을 찾는 건 사이트맵을 통해서고, 글이 바뀐 걸 아는 건 RSS를 통해서입니다. 둘 다 Hugo 기본값이라 신경 써 본 적이 없습니다. ClaudeBot은 이틀 동안 사이트맵을 36번 읽었고, 페이지 1,380개를 그렇게 빨리 찾아낸 것도 그 덕입니다.</p>
<p>언어는 중요할 거라고 예상하지 못했던 부분입니다. 여기 있는 건 전부 영어, 일본어, 한국어, 중국어 간체, 베트남어로 있고, 크롤러가 같은 글이라는 걸 알 수 있도록 alternate 링크가 붙어 있습니다. 크롤러는 이걸 사이트 다섯 개로 취급합니다. ClaudeBot의 크롤은 다섯 언어에 거의 고르게 나뉘었고, Common Crawl이 8월에 가져간 글 페이지 73개 중 영어판은 네 개뿐이었습니다. 어시스턴트는 질문받은 언어로 답하고 그 언어로 된 출처를 선호하기 때문에, 콜드 스타트에 대한 한국어 질문은 영어 페이지를 즉석에서 번역한 것이 아니라 한국어 페이지로 답할 수 있고, ChatGPT가 실제로 가져간 것도 일본어 페이지였습니다. 조건은 번역이 그 언어로 쓴 것처럼 읽혀야 한다는 겁니다. 올해 초에 원어민 검토를 받아 가며 한 번 손본 건 사람 독자를 위해서였지만, 베트남어 페이지가 구경거리가 아니라 출처가 되는 것도 그 덕입니다.</p>

<h2 class="relative group">측정할 수 있는 것
    <div id="측정할-수-있는-것" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%b8%a1%ec%a0%95%ed%95%a0-%ec%88%98-%ec%9e%88%eb%8a%94-%ea%b2%83" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>추측을 그만두고 나니 생각보다 많았습니다. Cloudflare 무료 플랜은 유저 에이전트와 경로별 요청 로그를 한 번에 하루치씩 조회하게 해 주는데, 위의 봇 표는 거기서 나왔습니다. 리퍼러는 유료 플랜이 필요합니다. 리퍼러는 방문 분석 도구에 있고, 대시보드를 눈 찌푸리고 들여다보는 대신 리포트 API로 뽑아낸 게 맨 위의 숫자들입니다. 둘을 합치면 윤곽이 보입니다. 나흘 동안 검색용 봇은 OpenAI와 Anthropic 주소에서 페이지 90개쯤을 가져갔습니다. 지난 한 달 동안 ChatGPT에서 건너온 사람은 두 명입니다. 많이 읽히고, 가끔 인용되고, 클릭은 드물게. 페이지를 썼는데 클릭은 안 된 답변을 볼 방법은 여전히 제가 아는 한 없습니다. 가장 유용한 확인은 여전히 수동입니다. 내 글이 답하는 질문을 어시스턴트에게 물어보고 누구 페이지를 인용하는지 보는 거죠.</p>
<p><figure><span class="mc-img"><img
    class="my-0 rounded-md"
    loading="lazy"
    decoding="async"
    fetchpriority="auto"
    alt="13개월간 월별 AI 어시스턴트 유입 세션 수, 추세 없음"
    width="2400"
    height="968"
    src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-16-blog-as-a-source-for-ai-assistants/chart-monthly_hu_cd5dc99be8b0cfc3.webp"
    srcset="https://jared.lynskey.co.nz/en/posts/2026/2026-09-16-blog-as-a-source-for-ai-assistants/chart-monthly_hu_cd5dc99be8b0cfc3.webp 800w, https://jared.lynskey.co.nz/en/posts/2026/2026-09-16-blog-as-a-source-for-ai-assistants/chart-monthly_hu_7d401a84f177509c.webp 1280w"
    sizes="(min-width: 768px) 50vw, 65vw"
    data-zoom-src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-16-blog-as-a-source-for-ai-assistants/chart-monthly_hu_5c308d89ad110ef7.webp"></span><figcaption>AI 어시스턴트에서 넘어온 방문을 월별로 본 것입니다. 추세라 부를 만한 것이 없습니다.</figcaption></figure>
</p>
<p>이 중에 하나만 남겨야 한다면 글쓰기 규칙입니다. robots.txt, 구조화 데이터, llms.txt는 오후 한나절 일이고 그러면 끝납니다. 섹션마다 주장을 먼저 말하도록 쓰는 것, 일반적인 것 대신 구체적인 것에 대해 쓰는 것은 습관이고, 페이지가 인용할 가치가 있는지를 결정하는 건 그 습관입니다. 두 번째는 주장하기 전에 재 보는 겁니다. 기계에게 신뢰받는 건 알고 보면 사람에게 신뢰받는 것과 많이 닮았습니다. 내가 누구인지 말하고, 내가 아는 걸 말하고, 매번 같은 방식으로 말하는 것.</p>
]]></content:encoded>
      <media:content url="https://jared.lynskey.co.nz/en/posts/2026/2026-09-16-blog-as-a-source-for-ai-assistants/featured.jpg" medium="image" type="image/jpeg" />
    </item>
    <item>
      <title>Hugo에서 SCSS 사용하는 법: Hugo Pipes로 컴파일하기</title>
      <link>https://jared.lynskey.co.nz/ko/posts/2019/2019-08-06-understandingsass/</link>
      <guid isPermaLink="true">https://jared.lynskey.co.nz/ko/posts/2019/2019-08-06-understandingsass/</guid>
      <pubDate>Tue, 06 Aug 2019 00:00:00 +0000</pubDate>
      <dc:creator>Jared Lynskey</dc:creator>
      <category>CSS</category>
      <category>Frontend</category>
      <category>Web Development</category>
      <category>Hugo</category>
      <description>Hugo에서 SCSS(Sass)를 쓰는 방법입니다. 이 사이트에 Hugo Pipes로 SCSS 컴파일을 붙인 과정을 짧은 네 단계로 정리했습니다.</description>
      <content:encoded><![CDATA[<p>이 사이트의 CSS가 어느새 길고 반복투성이인 파일 하나로 자라 버려서, 드디어 SASS로 옮겼습니다. GoHugo로 사이트를 운영하고 있다면, 15분만 들이면 그 뒤로 스타일시트를 만질 때마다 본전을 뽑는 종류의 작업이죠.</p>
<p>제가 설정한 과정을 정리해 둡니다.</p>

<h2 class="relative group">굳이 SASS를 쓰는 이유
    <div id="굳이-sass를-쓰는-이유" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ea%b5%b3%ec%9d%b4-sass%eb%a5%bc-%ec%93%b0%eb%8a%94-%ec%9d%b4%ec%9c%a0" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>순수 CSS는 페이지가 조금만 늘어나도 금세 지저분해집니다. SASS를 쓰면 변수, 중첩 규칙, 믹스인, 함수를 쓸 수 있어서 색상이나 공통 레이아웃 정의를 여기저기 복붙하지 않고 한곳에 모아둘 수 있습니다. Hugo 사용자에게 제일 반가운 점은, Hugo Pipes가 SCSS를 알아서 컴파일해 준다는 것. 별도의 빌드 도구도, 워처 스크립트도 필요 없습니다.</p>
<p>작업하는 동안 열어두면 좋은 페이지 두 곳:</p>
<ul>
<li><a href="https://sass-lang.com/"  target="_blank" rel="noreferrer">SASS 공식 문서</a></li>
<li>Hugo의 <a href="https://gohugo.io/functions/css/sass/"  target="_blank" rel="noreferrer">SCSS/SASS 지원 문서</a></li>
</ul>

<h2 class="relative group">설정하기
    <div id="설정하기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%84%a4%ec%a0%95%ed%95%98%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h2>

<h3 class="relative group">1. assets 디렉토리 준비
    <div id="1-assets-디렉토리-준비" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#1-assets-%eb%94%94%eb%a0%89%ed%86%a0%eb%a6%ac-%ec%a4%80%eb%b9%84" aria-label="앵커">#</a>
    </span>
    
</h3>
<p>Hugo는 프로젝트 루트의 <code>assets</code> 폴더를 찾기 때문에, 그 위치에 폴더를 만들거나 옮겨 주세요. <code>resources</code> 폴더 안에 두고 싶다면 <code>config.toml</code>에서 경로를 알려주면 됩니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-toml" data-lang="toml"><span class="line"><span class="cl"><span class="nx">assetDir</span> <span class="p">=</span> <span class="s2">&#34;resources/assets&#34;</span></span></span></code></pre></div></div>

<h3 class="relative group">2. <code>sass</code> 폴더 만들기
    <div id="2-sass-폴더-만들기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#2-sass-%ed%8f%b4%eb%8d%94-%eb%a7%8c%eb%93%a4%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h3>
<p><code>assets</code> 안에 <code>sass</code>라는 폴더를 만듭니다. SCSS 파일은 전부 여기에 둡니다.</p>

<h3 class="relative group">3. 진입점 파일 추가
    <div id="3-진입점-파일-추가" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#3-%ec%a7%84%ec%9e%85%ec%a0%90-%ed%8c%8c%ec%9d%bc-%ec%b6%94%ea%b0%80" aria-label="앵커">#</a>
    </span>
    
</h3>
<p><code>sass</code> 폴더 안에 <code>main.scss</code>를 만듭니다. Hugo가 컴파일하는 파일이 바로 이것이니, 동작 확인 겸 SCSS 코드를 조금 넣어 봅시다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-scss" data-lang="scss"><span class="line"><span class="cl"><span class="c1">// assets/sass/main.scss
</span></span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">// 변수
</span></span></span><span class="line"><span class="cl"><span class="nv">$primary-color</span><span class="o">:</span> <span class="mh">#3498db</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">// 믹스인
</span></span></span><span class="line"><span class="cl"><span class="k">@mixin</span><span class="nf"> center</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="na">display</span><span class="o">:</span> <span class="ni">flex</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">  <span class="na">justify-content</span><span class="o">:</span> <span class="ni">center</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">  <span class="na">align-items</span><span class="o">:</span> <span class="ni">center</span><span class="p">;</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">// 스타일
</span></span></span><span class="line"><span class="cl"><span class="nt">body</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="na">font-family</span><span class="o">:</span> <span class="n">Arial</span><span class="o">,</span> <span class="ni">sans-serif</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">  <span class="na">background-color</span><span class="o">:</span> <span class="nv">$primary-color</span><span class="p">;</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nt">h1</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="k">@include</span><span class="nd"> center</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">  <span class="na">color</span><span class="o">:</span> <span class="ni">white</span><span class="p">;</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div></div>

<h3 class="relative group">4. 템플릿에 연결
    <div id="4-템플릿에-연결" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#4-%ed%85%9c%ed%94%8c%eb%a6%bf%ec%97%90-%ec%97%b0%ea%b2%b0" aria-label="앵커">#</a>
    </span>
    
</h3>
<p><code>head.html</code> 파셜에서 컴파일된 스타일시트를 불러와 압축합니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-go" data-lang="go"><span class="line"><span class="cl"><span class="p">{{</span><span class="w"> </span><span class="err">$</span><span class="nx">style</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="nx">resources</span><span class="p">.</span><span class="nx">Get</span><span class="w"> </span><span class="s">&#34;sass/main.scss&#34;</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nx">resources</span><span class="p">.</span><span class="nx">ToCSS</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nx">resources</span><span class="p">.</span><span class="nx">Minify</span><span class="w"> </span><span class="p">}}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="p">&lt;</span><span class="nx">link</span><span class="w"> </span><span class="nx">rel</span><span class="p">=</span><span class="s">&#34;stylesheet&#34;</span><span class="w"> </span><span class="nx">href</span><span class="p">=</span><span class="s">&#34;{{ $style.Permalink }}&#34;</span><span class="p">&gt;</span></span></span></code></pre></div></div>
<p>여기 적은 파일명이 실제 진입점(<code>main.scss</code>)과 일치하는지만 확인하면 됩니다.</p>

<h2 class="relative group">스타일 파일 쪼개기
    <div id="스타일-파일-쪼개기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%8a%a4%ed%83%80%ec%9d%bc-%ed%8c%8c%ec%9d%bc-%ec%aa%bc%ea%b0%9c%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>프로젝트가 커지면 SCSS를 파셜로 나누고 <code>main.scss</code>에서 임포트하세요.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-scss" data-lang="scss"><span class="line"><span class="cl"><span class="c1">// assets/sass/_variables.scss
</span></span></span><span class="line"><span class="cl"><span class="nv">$primary-color</span><span class="o">:</span> <span class="mh">#3498db</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">// assets/sass/_mixins.scss
</span></span></span><span class="line"><span class="cl"><span class="k">@mixin</span><span class="nf"> center</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="na">display</span><span class="o">:</span> <span class="ni">flex</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">  <span class="na">justify-content</span><span class="o">:</span> <span class="ni">center</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">  <span class="na">align-items</span><span class="o">:</span> <span class="ni">center</span><span class="p">;</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">// assets/sass/main.scss
</span></span></span><span class="line"><span class="cl"><span class="k">@import</span> <span class="s2">&#34;variables&#34;</span><span class="p">;</span>
</span></span><span class="line"><span class="cl"><span class="k">@import</span> <span class="s2">&#34;mixins&#34;</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nt">body</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="na">background-color</span><span class="o">:</span> <span class="nv">$primary-color</span><span class="p">;</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nt">h1</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="k">@include</span><span class="nd"> center</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">  <span class="na">color</span><span class="o">:</span> <span class="ni">white</span><span class="p">;</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div></div>
<p>정말 이게 전부입니다. 네 단계면 끝나고, 빌드할 때마다 Hugo가 스타일을 다시 컴파일해 줍니다. 에셋 파이프라인과 한바탕 씨름할 각오였는데, 허무할 만큼 순순히 돌아가더군요.</p>
]]></content:encoded>
      <media:content url="https://jared.lynskey.co.nz/en/posts/2019/2019-08-06-understandingsass/featured.jpeg" medium="image" type="image/jpeg" />
    </item>
  </channel>
</rss>
