<?xml version="1.0" encoding="utf-8"?><feed xmlns="http://www.w3.org/2005/Atom" xml:lang="ko"><generator uri="https://jekyllrb.com/" version="3.10.0">Jekyll</generator><link href="https://zeno0505.github.io/dev-articles/feed.xml" rel="self" type="application/atom+xml" /><link href="https://zeno0505.github.io/dev-articles/" rel="alternate" type="text/html" hreflang="ko" /><updated>2026-11-19T10:41:53+09:00</updated><id>https://zeno0505.github.io/dev-articles/feed.xml</id><title type="html">zeno-articles</title><subtitle>일일 회고와 인사이트 — 짧게 남기는 개발 교훈</subtitle><author><name>zeno0505</name></author><entry><title type="html">비즈니스 구조를 개선하는 사용자 AI 서비스 제작기</title><link href="https://zeno0505.github.io/dev-articles/2026/11/18/api-spec-in-the-browser/" rel="alternate" type="text/html" title="비즈니스 구조를 개선하는 사용자 AI 서비스 제작기" /><published>2026-11-18T00:00:00+09:00</published><updated>2026-11-18T00:00:00+09:00</updated><id>https://zeno0505.github.io/dev-articles/2026/11/18/api-spec-in-the-browser</id><content type="html" xml:base="https://zeno0505.github.io/dev-articles/2026/11/18/api-spec-in-the-browser/"><![CDATA[<p>경영진 세션에서, 비즈니스를 확장하기 위해 사람을 더 뽑아야만 확장되는 구조를 개선할 무언가를 만들면 좋겠다는 질문을 듣고 고민을 시작했습니다. 유저가 운영을 이어 갈 때 다음 행동을 찾고 실행하는 일에, 사람 손을 늘리지 않고도 도움을 줄 수 있을까 싶었습니다.</p>

<p>당시 제가 쓸 수 있다고 가정한 것은 프론트엔드 리소스뿐이었습니다. 서버 인력을 새로 쓰기보다, 프론트엔드 개발자로서 할 수 있는 최선이 무엇인지부터 천천히 따져 보았습니다. 백엔드 역할을 넘지 않고 MCP도 두지 않은 채, 이미 있는 API만으로 어디까지 갈 수 있을까가 출발점이었습니다.</p>

<p>유저 운영을 돕는 AI 에이전트를 만들며, 저는 확인 가능한 상태만 읽고 다음 일을 제안한 뒤, 사람이 승인한 범위만 실행하는 쪽으로 방향을 잡았습니다.</p>

<h2 id="api-명세만-넘기고-브라우저에서-실행하는-방식">API 명세만 넘기고 브라우저에서 실행하는 방식</h2>

<p>백엔드 역할을 넘지 않고 MCP도 새로 두지 않으려면, 유저가 실제로 호출할 수 있는 API를 에이전트에게 명세까지만 주고 실행은 브라우저에서 하는 편이 낫다고 봤습니다. 모델을 호출할 때는 기존 API의 타입 선언에서 뽑은 입력 스키마에, 기능마다 고른 호출 목록과 예시를 붙여 JSON으로 넘깁니다. 모델이 어떤 호출이 필요한지 고르면 웹 클라이언트가 그 API를 실행합니다. 모델이 서버를 직접 두드리지 않고, 호출할 API와 경로는 코드가 정하며, 모델이 채운 값은 보내기 전에 스키마로 한 번 더 검사합니다.</p>

<p>실행은 유저의 세션 권한을 그대로 탑니다. 에이전트를 위해 업무 API에 새 권한을 만들지 않아도 되고, 서버가 원래 하던 검증도 그대로 적용됩니다. 그래서 이 방식이 더 안전하다고 봤습니다. 모델 호출만은 키를 숨기려고 웹 서버에 얇은 프록시 하나를 두었고, 판단과 실행은 모두 브라우저에 있습니다. 그 밖에 서버 쪽으로 넓힌 것은 데모 단계에서 디버깅을 위해 턴 기록을 올려 두는 S3 저장소까지였습니다.</p>

<p>또 한 가지는, AI와 상관없는 신기능이 나와도 API는 원래 만들어집니다. 입력 스키마는 타입 선언에서 다시 생성되니, 어떤 호출을 열지와 되돌릴 수 있는지, 실행 뒤 무엇을 안내할지만 기능마다 정해 주면 새 기능을 실행 범위에 넣을 수 있습니다. 명세 자체도 요즘은 OpenAPI로 자동화하는 경우가 많아서, 지침과 허용할 API 가드레일만 맞춰 두면 업데이트가 한결 쉬워집니다.</p>

<p>실행은 사람이 승인한 뒤에만 하도록 했습니다. 지금 확인 가능한 정보만 보고 해볼 만한 일을 제안하고, 초안을 만들거나 설정을 바꾸는 일을 도우며, 실행 계획은 무엇을 바꿀지 먼저 보여 주고 승인을 받은 뒤에만 브라우저가 요청을 보냅니다.</p>

<p>처음에는 되돌릴 수 없는 동작을 아예 막았는데, 승인 절차가 이미 있는데도 막는 것은 구현의 한계를 유저에게 떠넘기는 일이라고 보고 바꿨습니다. 지금은 API마다 되돌릴 수 있는지를 선언해 승인 화면에 보여 주고, 되돌릴 수 있는 쓰기는 직전 상태를 남겨 둡니다. 다만 바깥에 바로 보이는 공개 전환은 승인을 받더라도 에이전트에게 맡기지 않고, 사람이 화면에서 직접 누르게 두었습니다. 실행이 끝나면 무엇이 만들어졌는지와, 이후에 무엇을 확인하면 좋을지를 안내합니다.</p>

<p>다만 실제 권한이 있는 API만 호출할 수 있어야 하고, 여러 쓰기를 한꺼번에 보내면 데이터베이스 잠금이 생길 수 있습니다. 그래서 실행을 묶는 코드, 이른바 하네스에서 허용 목록에 있는 호출만 받고, 계획에 든 호출은 한 건씩 차례로 보내기로 했습니다. 하나라도 어긋나면 거기서 멈추고, 계획을 다시 짜는 단계로 넘깁니다.</p>

<div class="language-ts highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">type</span> <span class="nx">Call</span> <span class="o">=</span> <span class="p">{</span> <span class="na">catalogId</span><span class="p">:</span> <span class="kr">string</span><span class="p">;</span> <span class="nl">payload</span><span class="p">:</span> <span class="nb">Record</span><span class="o">&lt;</span><span class="kr">string</span><span class="p">,</span> <span class="nx">unknown</span><span class="o">&gt;</span> <span class="p">};</span>
<span class="kd">type</span> <span class="nx">CatalogEntry</span> <span class="o">=</span> <span class="p">{</span>
  <span class="na">method</span><span class="p">:</span> <span class="dl">"</span><span class="s2">GET</span><span class="dl">"</span> <span class="o">|</span> <span class="dl">"</span><span class="s2">POST</span><span class="dl">"</span> <span class="o">|</span> <span class="dl">"</span><span class="s2">PUT</span><span class="dl">"</span> <span class="o">|</span> <span class="dl">"</span><span class="s2">DELETE</span><span class="dl">"</span><span class="p">;</span>
  <span class="nl">path</span><span class="p">:</span> <span class="kr">string</span><span class="p">;</span>
  <span class="nl">validate</span><span class="p">:</span> <span class="p">(</span><span class="na">payload</span><span class="p">:</span> <span class="nx">unknown</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="nx">boolean</span><span class="p">;</span>
<span class="p">};</span>

<span class="k">async</span> <span class="kd">function</span> <span class="nx">executeApprovedPlan</span><span class="p">(</span>
  <span class="nx">calls</span><span class="p">:</span> <span class="nx">Call</span><span class="p">[],</span>
  <span class="nx">catalog</span><span class="p">:</span> <span class="nb">Map</span><span class="o">&lt;</span><span class="kr">string</span><span class="p">,</span> <span class="nx">CatalogEntry</span><span class="o">&gt;</span><span class="p">,</span>
  <span class="nx">request</span><span class="p">:</span> <span class="p">(</span><span class="nx">entry</span><span class="p">:</span> <span class="nx">CatalogEntry</span><span class="p">,</span> <span class="nx">payload</span><span class="p">:</span> <span class="nb">Record</span><span class="o">&lt;</span><span class="kr">string</span><span class="p">,</span> <span class="nx">unknown</span><span class="o">&gt;</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="nb">Promise</span><span class="o">&lt;</span><span class="nx">unknown</span><span class="o">&gt;</span><span class="p">,</span>
<span class="p">)</span> <span class="p">{</span>
  <span class="k">for</span> <span class="p">(</span><span class="kd">const</span> <span class="p">[</span><span class="nx">index</span><span class="p">,</span> <span class="nx">call</span><span class="p">]</span> <span class="k">of</span> <span class="nx">calls</span><span class="p">.</span><span class="nx">entries</span><span class="p">())</span> <span class="p">{</span>
    <span class="c1">// 경로와 메서드는 모델 출력이 아니라 허용 목록에서 꺼냅니다.</span>
    <span class="kd">const</span> <span class="nx">entry</span> <span class="o">=</span> <span class="nx">catalog</span><span class="p">.</span><span class="kd">get</span><span class="p">(</span><span class="nx">call</span><span class="p">.</span><span class="nx">catalogId</span><span class="p">);</span>
    <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nx">entry</span><span class="p">)</span> <span class="p">{</span>
      <span class="k">return</span> <span class="p">{</span> <span class="na">ok</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span> <span class="na">failedAt</span><span class="p">:</span> <span class="nx">index</span><span class="p">,</span> <span class="na">reason</span><span class="p">:</span> <span class="dl">"</span><span class="s2">not in catalog</span><span class="dl">"</span> <span class="p">}</span> <span class="k">as</span> <span class="kd">const</span><span class="p">;</span>
    <span class="p">}</span>
    <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nx">entry</span><span class="p">.</span><span class="nx">validate</span><span class="p">(</span><span class="nx">call</span><span class="p">.</span><span class="nx">payload</span><span class="p">))</span> <span class="p">{</span>
      <span class="k">return</span> <span class="p">{</span> <span class="na">ok</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span> <span class="na">failedAt</span><span class="p">:</span> <span class="nx">index</span><span class="p">,</span> <span class="na">reason</span><span class="p">:</span> <span class="dl">"</span><span class="s2">invalid payload</span><span class="dl">"</span> <span class="p">}</span> <span class="k">as</span> <span class="kd">const</span><span class="p">;</span>
    <span class="p">}</span>
    <span class="c1">// 여러 쓰기를 한꺼번에 보내면 잠금이 생길 수 있어 한 건씩 보냅니다.</span>
    <span class="k">await</span> <span class="nx">request</span><span class="p">(</span><span class="nx">entry</span><span class="p">,</span> <span class="nx">call</span><span class="p">.</span><span class="nx">payload</span><span class="p">);</span>
  <span class="p">}</span>
  <span class="k">return</span> <span class="p">{</span> <span class="na">ok</span><span class="p">:</span> <span class="kc">true</span> <span class="p">}</span> <span class="k">as</span> <span class="kd">const</span><span class="p">;</span>
<span class="p">}</span>
</code></pre></div></div>

<p>화면에서 막히던 제약이 이 경로에서는 더 이상 안전장치가 되지 않는다는 점도 분명해졌습니다. 실제로 붙여 보니 화면에만 있고 서버에는 없는 제약이 있었습니다. 서버의 검증이 안전장치의 중심이 되어야 한다고 보고, 그런 자리는 보내기 직전 검사로 메웠습니다.</p>

<p>그리고 이 서비스의 웹 프론트엔드는 Vue 2에서 Vue 3로 마이그레이션하는 중이었습니다. 한 모노레포 안에서 Nuxt 4(Vue 3) 앱, Nuxt 2 앱, Vite로 빌드하는 Vue 2.7 앱이 함께 돌고, 경로마다 어느 앱이 그 화면을 맡을지는 라우팅 단계에서 나눕니다. 실제 구조는 아래 그림과 같습니다. 이 구조에서 에이전트를 한 앱에 붙여 두면 화면이 다른 앱으로 옮겨질 때마다 그 화면에서 에이전트가 사라졌습니다.</p>

<pre><code class="language-mermaid">flowchart TB
  req[브라우저 요청] --&gt; router[경로별로 담당 앱을 고르는 라우팅]
  router --&gt; appNew[Nuxt 4 앱 · Vue 3]
  router --&gt; appOld[Nuxt 2 앱 · Vue 2.7]
  router --&gt; appVite[Vite 앱 · Vue 2.7]
  subgraph shared[공유 패키지]
    agent[에이전트 패키지: vue-demi로 Vue 2.7·3 공용]
  end
  appNew --&gt;|요청·업로드·이동 구현과 기능 등록| agent
  appOld --&gt;|요청·업로드·이동 구현과 기능 등록| agent
  appVite --&gt;|요청·업로드·이동 구현과 기능 등록| agent
  agent --&gt;|모델 호출| proxy[웹 서버의 모델 프록시]
</code></pre>

<p>그래서 에이전트는 Vue 2.7과 Vue 3를 함께 지원하는 UI 라이브러리처럼 공유 패키지로 만들었습니다. 컴포넌트와 컴포저블은 vue-demi로 두 버전의 차이를 감추고, 앱이 바뀌어도 상태와 흐름이 같게 돌도록 짰습니다. 요청, 업로드, 화면 이동 같은 기능은 에이전트가 직접 들고 있지 않고, 에이전트를 붙인 각 앱이 자기 방식대로 구현해 넘겨 주게 했습니다. 어떤 기능을 열지도 그 앱이 등록하게 해서, 그 기능이 없는 앱에서는 제안이 나오지 않게 했습니다.</p>

<p>다만 같은 화면이 두 앱에 걸쳐 있는 구간에서는, 프롬프트만으로 그 기능을 열 수는 없었습니다. 같은 API를 새 화면과 예전 화면이 다르게 선언해 둔 곳에서는, 모델이 맞는 값을 써도 실제로 요청을 받는 쪽이 그 값을 모를 수 있었습니다. 모델에게 일을 맡긴다고 해서, 클라이언트가 아직 이어 주지 못한 경로까지 실행되는 것은 아니었습니다.</p>

<h2 id="api를-읽으며-놓친-기능을-발견한-과정">API를 읽으며 놓친 기능을 발견한 과정</h2>

<p>에이전트를 고도화하다 보면, 처음 계획에는 없던 데이터가 더 필요해질 때가 있습니다. 자세히 보면 그건 유저에게 필요한 기능인데, 우리가 놓치고 있던 경우이기도 했습니다.</p>

<p>API를 그대로 읽는 구조 덕분에, 그 빈칸이 비교적 빨리 보였습니다. 에이전트가 할 일을 설계하며 확인하려던 값이 API에 없던 자리가, 유저 화면에서도 그 값이 빠져 있던 자리와 겹치는 일이 있었습니다. 예를 들어 에이전트가 만든 결과물 하나가 이후 실제로 팔렸는지 확인하려 했는데, 응답에 그 결과물을 이어 줄 식별자가 없었고, 사람이 쓰는 관리 화면도 같은 질문에 답하지 못했습니다. 사람에게 필요한 것이 에이전트에게도 필요해지는 경험은, 뒤에서 다시 이어집니다.</p>

<p><img src="/dev-articles/assets/2026-11-18-api-spec-in-the-browser-01.png" alt="에이전트를 고도화하다 필요한 데이터가 더 생기면, API 명세에 그 값이 없는 때가 유저에게 빠져 있던 기능과 겹치는 과정입니다." /></p>

<p>에이전트를 고도화하다 필요한 데이터가 더 생기면, API 명세에 그 값이 없는 때가 유저에게 빠져 있던 기능과 겹치는 과정입니다.</p>

<h2 id="기능-단위로-명세를-나누고-판별만-맡기는-구조">기능 단위로 명세를 나누고 판별만 맡기는 구조</h2>

<p>에이전트가 모든 API 응답을 알아야 한다면 토큰 낭비도 크고, 없는 내용을 지어 낼 여지도 커집니다. 그래서 명세를 기능 단위로 쪼개고, 유저의 말을 어느 단위로 보낼지 판별하는 에이전트를 따로 두었습니다. 이 에이전트는 기능 단위를 고르고, 요청이 모호할 때 되묻는 한 문장 말고는 유저에게 보여줄 답을 만들지 않으며, 비교적 저렴한 모델을 씁니다. 고를 수 있는 값은 응답 스키마로 미리 묶어 두고, 받은 뒤에 코드가 한 번 더 검증합니다. 나눠진 단위마다 그 기능의 API와, 그 기능에 고유한 도메인 지식을 담은 지침을 두었습니다.</p>

<div class="language-ts highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">type</span> <span class="nx">Route</span> <span class="o">=</span>
  <span class="o">|</span> <span class="p">{</span> <span class="na">kind</span><span class="p">:</span> <span class="dl">"</span><span class="s2">unit</span><span class="dl">"</span><span class="p">;</span> <span class="nl">unit</span><span class="p">:</span> <span class="kr">string</span> <span class="p">}</span>
  <span class="o">|</span> <span class="p">{</span> <span class="na">kind</span><span class="p">:</span> <span class="dl">"</span><span class="s2">clarify</span><span class="dl">"</span><span class="p">;</span> <span class="nl">question</span><span class="p">:</span> <span class="kr">string</span> <span class="p">}</span>
  <span class="o">|</span> <span class="p">{</span> <span class="na">kind</span><span class="p">:</span> <span class="dl">"</span><span class="s2">unsupported</span><span class="dl">"</span> <span class="p">};</span>

<span class="k">async</span> <span class="kd">function</span> <span class="nx">classifyUnit</span><span class="p">(</span>
  <span class="nx">message</span><span class="p">:</span> <span class="kr">string</span><span class="p">,</span>
  <span class="nx">units</span><span class="p">:</span> <span class="k">readonly</span> <span class="kr">string</span><span class="p">[],</span>
  <span class="nx">model</span><span class="p">:</span> <span class="p">{</span>
    <span class="nl">generateJson</span><span class="p">:</span> <span class="p">(</span><span class="nx">input</span><span class="p">:</span> <span class="p">{</span> <span class="nl">system</span><span class="p">:</span> <span class="kr">string</span><span class="p">;</span> <span class="nl">user</span><span class="p">:</span> <span class="kr">string</span><span class="p">;</span> <span class="nl">schema</span><span class="p">:</span> <span class="nx">object</span> <span class="p">})</span> <span class="o">=&gt;</span> <span class="nb">Promise</span><span class="o">&lt;</span><span class="nx">unknown</span><span class="o">&gt;</span><span class="p">;</span>
  <span class="p">},</span>
<span class="p">):</span> <span class="nb">Promise</span><span class="o">&lt;</span><span class="nx">Route</span><span class="o">&gt;</span> <span class="p">{</span>
  <span class="kd">const</span> <span class="nx">schema</span> <span class="o">=</span> <span class="p">{</span>
    <span class="na">type</span><span class="p">:</span> <span class="dl">"</span><span class="s2">object</span><span class="dl">"</span><span class="p">,</span>
    <span class="na">properties</span><span class="p">:</span> <span class="p">{</span>
      <span class="na">unit</span><span class="p">:</span> <span class="p">{</span> <span class="na">type</span><span class="p">:</span> <span class="dl">"</span><span class="s2">string</span><span class="dl">"</span><span class="p">,</span> <span class="na">enum</span><span class="p">:</span> <span class="p">[...</span><span class="nx">units</span><span class="p">,</span> <span class="dl">"</span><span class="s2">unsupported</span><span class="dl">"</span><span class="p">]</span> <span class="p">},</span>
      <span class="na">question</span><span class="p">:</span> <span class="p">{</span> <span class="na">type</span><span class="p">:</span> <span class="dl">"</span><span class="s2">string</span><span class="dl">"</span> <span class="p">},</span>
    <span class="p">},</span>
    <span class="na">required</span><span class="p">:</span> <span class="p">[</span><span class="dl">"</span><span class="s2">unit</span><span class="dl">"</span><span class="p">],</span>
  <span class="p">};</span>
  <span class="kd">const</span> <span class="nx">raw</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">model</span><span class="p">.</span><span class="nx">generateJson</span><span class="p">({</span>
    <span class="na">system</span><span class="p">:</span> <span class="dl">"</span><span class="s2">Pick one unit. Ask one short question only when the request is ambiguous.</span><span class="dl">"</span><span class="p">,</span>
    <span class="na">user</span><span class="p">:</span> <span class="nx">message</span><span class="p">,</span>
    <span class="nx">schema</span><span class="p">,</span>
  <span class="p">});</span>
  <span class="c1">// 스키마로 묶어도 받은 값은 코드가 다시 확인합니다.</span>
  <span class="k">if</span> <span class="p">(</span><span class="k">typeof</span> <span class="nx">raw</span> <span class="o">!==</span> <span class="dl">"</span><span class="s2">object</span><span class="dl">"</span> <span class="o">||</span> <span class="nx">raw</span> <span class="o">===</span> <span class="kc">null</span><span class="p">)</span> <span class="k">return</span> <span class="p">{</span> <span class="na">kind</span><span class="p">:</span> <span class="dl">"</span><span class="s2">unsupported</span><span class="dl">"</span> <span class="p">};</span>
  <span class="kd">const</span> <span class="p">{</span> <span class="nx">unit</span><span class="p">,</span> <span class="nx">question</span> <span class="p">}</span> <span class="o">=</span> <span class="nx">raw</span> <span class="k">as</span> <span class="p">{</span> <span class="nx">unit</span><span class="p">?:</span> <span class="nx">unknown</span><span class="p">;</span> <span class="nl">question</span><span class="p">?:</span> <span class="nx">unknown</span> <span class="p">};</span>
  <span class="k">if</span> <span class="p">(</span><span class="k">typeof</span> <span class="nx">question</span> <span class="o">===</span> <span class="dl">"</span><span class="s2">string</span><span class="dl">"</span> <span class="o">&amp;&amp;</span> <span class="nx">question</span><span class="p">.</span><span class="nx">length</span> <span class="o">&gt;</span> <span class="mi">0</span><span class="p">)</span> <span class="k">return</span> <span class="p">{</span> <span class="na">kind</span><span class="p">:</span> <span class="dl">"</span><span class="s2">clarify</span><span class="dl">"</span><span class="p">,</span> <span class="nx">question</span> <span class="p">};</span>
  <span class="k">if</span> <span class="p">(</span><span class="k">typeof</span> <span class="nx">unit</span> <span class="o">!==</span> <span class="dl">"</span><span class="s2">string</span><span class="dl">"</span> <span class="o">||</span> <span class="o">!</span><span class="nx">units</span><span class="p">.</span><span class="nx">includes</span><span class="p">(</span><span class="nx">unit</span><span class="p">))</span> <span class="k">return</span> <span class="p">{</span> <span class="na">kind</span><span class="p">:</span> <span class="dl">"</span><span class="s2">unsupported</span><span class="dl">"</span> <span class="p">};</span>
  <span class="k">return</span> <span class="p">{</span> <span class="na">kind</span><span class="p">:</span> <span class="dl">"</span><span class="s2">unit</span><span class="dl">"</span><span class="p">,</span> <span class="nx">unit</span> <span class="p">};</span>
<span class="p">}</span>
</code></pre></div></div>

<pre><code class="language-mermaid">flowchart TD
  msg[유저 말] --&gt; classify[판별만 하는 에이전트]
  classify --&gt;|민감한 요청| refuse[정해 둔 문장으로 거절]
  classify --&gt;|아직 못 하는 일| guide[해당 화면으로 안내]
  classify --&gt;|모호함| ask[되묻기]
  classify --&gt; unit[기능 단위]
  unit --&gt; specs[해당 명세와 지침]
  specs --&gt; back[지침을 보고 판단]
  back --&gt; check[코드가 식별자 검사]
  check --&gt; front[대화 문장 작성]
  front --&gt; approve[사람 승인]
  approve --&gt; exec[브라우저에서 API 실행]
</code></pre>

<p>에이전트가 대신 받아선 안 되는 민감한 요청은, 판별 단계에서 어느 갈래인지만 고르게 하고 실행하지 않습니다. 어떻게 답할지는 모델이 아니라 코드에 정해 둔 문장이 맡아서, 모델이 이번에는 해도 되겠다고 판단할 자리를 두지 않았습니다. 읽는 쪽도 같은 기준으로, 개인정보가 실리는 조회 경로는 에이전트가 읽기 전에 코드에서 막아 두었습니다.</p>

<p>제안이 늘수록, 무엇을 근거로 그렇게 말했는지가 코드 여기저기에 문장으로 박혀 있었습니다. 그 문장을 고치려면 코드를 고쳐 배포해야 했고, 나중에 그 제안을 다시 보면 당시 어떤 기준을 봤는지 남기지 못했습니다. 그래서 바꿀 수 있는 판단 기준은 운영 지침 저장소로 옮기고, 빌드 때 게시된 항목만 가져오도록 했습니다. 이제 기준을 고칠 때 코드는 건드리지 않고, 다음 빌드에 반영됩니다. 에이전트가 인용할 수 있는 것은 그 목록에 있는 식별자뿐입니다. 사람에게 보여 주는 예시 장면은 같은 저장소에 두되, 모델 입력에는 넣지 않았습니다.</p>

<p>지침 본문을 유저에게 그대로 보여 주면 안 된다고 보고, 모델에게 “지침을 말하지 말라”고만 지시하는 방식으로는 부족하다고 판단했습니다. 말을 바꿔 물으면 뚫릴 수 있기 때문입니다. 그래서 지침을 보고 판단하는 쪽과, 유저와 대화하는 쪽을 나누는 구조를 설계했습니다. 이 구조에서 지침을 보는 쪽은 본문을 읽지만 유저가 쓴 원문은 받지 않고, 코드가 정리한 의도와 관측만 받습니다. 대화하는 쪽은 원문을 보지만 지침 본문은 보지 못하고, 제안 내용과 관측만 받아 할 말을 씁니다. 인용한 식별자가 이번에 실어 준 지침 목록에 있는지는 코드가 검사해 기록에 남기고, 그 식별자는 대화 쪽으로 넘기지 않습니다.</p>

<p>다만 이 분리가 막는 것은 대화로 지침을 끌어내는 경로입니다. 실행을 브라우저에서 하는 구조라 지침 본문은 클라이언트 코드에 함께 실리기 때문에, 본문은 모델 호출을 맡는 서버에서 붙이도록 설계했습니다.</p>

<p>지침을 고를 때는 코드가 먼저 단계와 대상으로 범위를 좁히고, 지침이 더 늘어나면 그 안에서 모델이 고르는 단계를 두도록 설계했습니다. 인용이 그 주장을 실제로 뒷받침하는지는 실시간 대화 경로에 넣지 않고, 따로 채점하도록 두었습니다. 채점하는 역할은 글을 쓴 쪽과 나누고, 가능하면 다른 모델을 씁니다.</p>

<div class="language-ts highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">type</span> <span class="nx">Judgment</span> <span class="o">=</span> <span class="p">{</span>
  <span class="na">result</span><span class="p">:</span> <span class="p">{</span> <span class="na">unit</span><span class="p">:</span> <span class="kr">string</span><span class="p">;</span> <span class="nl">feasible</span><span class="p">:</span> <span class="dl">"</span><span class="s2">yes</span><span class="dl">"</span> <span class="o">|</span> <span class="dl">"</span><span class="s2">partial</span><span class="dl">"</span> <span class="o">|</span> <span class="dl">"</span><span class="s2">no</span><span class="dl">"</span> <span class="p">};</span>
  <span class="nl">grounds</span><span class="p">?:</span> <span class="p">{</span> <span class="na">guidelineIds</span><span class="p">:</span> <span class="kr">string</span><span class="p">[];</span> <span class="nl">catalogVersion</span><span class="p">:</span> <span class="kr">string</span> <span class="p">};</span>
<span class="p">};</span>

<span class="c1">// 대화 쪽에는 근거 식별자를 떼고 넘깁니다.</span>
<span class="kd">function</span> <span class="nx">forConversation</span><span class="p">(</span><span class="nx">judgment</span><span class="p">:</span> <span class="nx">Judgment</span><span class="p">)</span> <span class="p">{</span>
  <span class="kd">const</span> <span class="p">{</span> <span class="na">grounds</span><span class="p">:</span> <span class="nx">_grounds</span><span class="p">,</span> <span class="p">...</span><span class="nx">visible</span> <span class="p">}</span> <span class="o">=</span> <span class="nx">judgment</span><span class="p">;</span>
  <span class="k">return</span> <span class="nx">visible</span><span class="p">;</span>
<span class="p">}</span>

<span class="c1">// 이번 호출에 실어 준 지침과 대조해, 목록에 없는 식별자는 버리지 않고 따로 셉니다.</span>
<span class="kd">function</span> <span class="nx">checkCitations</span><span class="p">(</span><span class="nx">judgment</span><span class="p">:</span> <span class="nx">Judgment</span><span class="p">,</span> <span class="nx">offered</span><span class="p">:</span> <span class="nb">Set</span><span class="o">&lt;</span><span class="kr">string</span><span class="o">&gt;</span><span class="p">)</span> <span class="p">{</span>
  <span class="kd">const</span> <span class="nx">ids</span> <span class="o">=</span> <span class="nx">judgment</span><span class="p">.</span><span class="nx">grounds</span><span class="p">?.</span><span class="nx">guidelineIds</span> <span class="o">??</span> <span class="p">[];</span>
  <span class="k">return</span> <span class="p">{</span>
    <span class="na">valid</span><span class="p">:</span> <span class="nx">ids</span><span class="p">.</span><span class="nx">filter</span><span class="p">((</span><span class="nx">id</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="nx">offered</span><span class="p">.</span><span class="nx">has</span><span class="p">(</span><span class="nx">id</span><span class="p">)),</span>
    <span class="na">invalid</span><span class="p">:</span> <span class="nx">ids</span><span class="p">.</span><span class="nx">filter</span><span class="p">((</span><span class="nx">id</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="o">!</span><span class="nx">offered</span><span class="p">.</span><span class="nx">has</span><span class="p">(</span><span class="nx">id</span><span class="p">)),</span>
  <span class="p">};</span>
<span class="p">}</span>
</code></pre></div></div>

<p>지금은 제안이 어떤 지침을 참고했는지 식별자를 기록하고, 그 지침을 올바르게 반영했는지, 지침 자체는 타당한지, 에이전트가 읽는 데이터는 부족한지를 나눠 보고 있습니다. 지침마다 어느 단계에서 읽을지를 표시해 두었는데, 한 지침이 작성 단계에만 걸려 있어서 기획 단계의 판단에는 반영되지 않은 일이 있었습니다. 그 지침이 읽힐 단계를 고치고, 지침의 조건을 판별하는 데 필요한 값도 기획 단계에 넘기도록 맞추었습니다.</p>

<p>호출이 늘면 “느리다”는 느낌만으로는 어디를 고쳐야 하는지 알기 어렵습니다. 그래서 턴 기록에 어느 에이전트가 어떤 모델을 불렀는지, 토큰은 얼마나 썼는지, 호출이 언제 시작하고 끝났는지를 남기기로 했습니다. 이 층이 시스템과 비용입니다. 백엔드 관측 도구를 새로 두지 않고, 호출 기록만으로도 어느 단계가 긴지 보려는 선택이었습니다. 실제로 이 기록에서 상위 모델 호출이 4분 46초까지 걸리고, 5분을 넘긴 호출은 Node 내장 fetch(undici)의 응답 헤더 대기 기본값인 300초에 걸려 끊기는 것을 봤습니다. 같은 요청을 한 단계 가벼운 모델은 30초 안쪽에 냈기 때문에, 역할마다 기본 모델을 가벼운 쪽으로 낮췄습니다. 지금은 스트리밍이 아니라서, 첫 토큰이 나오기까지의 시간은 재지 않습니다.</p>

<p>품질은 따로 봅니다. 처음에는 인용 하나하나가 주장을 뒷받침하는지를 쟀는데, 지금은 결과물 하나에 실린 지침을 따랐는지, 놓쳤는지, 어겼는지, 필요 없이 인용했는지를 봅니다. 실제 모델을 부르는 채점은 일반 테스트와 섞지 않습니다. 테스트 러너가 모으는 파일 이름을 쓰지 않고 테스트 명령에도 걸지 않았으며, 실행 플래그가 없으면 모델을 부르지 않게 두었습니다.</p>

<div class="language-ts highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nx">process</span><span class="p">.</span><span class="nx">argv</span><span class="p">.</span><span class="nx">includes</span><span class="p">(</span><span class="dl">"</span><span class="s2">--live</span><span class="dl">"</span><span class="p">))</span> <span class="p">{</span>
  <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="dl">"</span><span class="s2">model call skipped</span><span class="dl">"</span><span class="p">);</span>
  <span class="nx">process</span><span class="p">.</span><span class="nx">exit</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
<span class="p">}</span>
</code></pre></div></div>

<pre><code class="language-mermaid">flowchart TD
  turn[턴 기록] --&gt; sys[시스템: 에이전트와 모델]
  turn --&gt; cost[비용: 토큰과 호출 시각]
  turn --&gt; quality[품질: 지침 준수 채점]
  quality --&gt; offline[오프라인 채점]
  cost --&gt; decide[호출을 줄일지 판단]
</code></pre>

<p>지침 준수 채점처럼 모델을 여러 번 부르는 확인이 늘면 비용도 함께 늘어납니다. 어디까지 감당할지 정하려면, 신규 유저가 하루 안에 서비스를 시작할 수 있는 수준까지 가는 데 토큰이 얼마나 드는지부터 재야 한다고 봤습니다. 그래서 그 기준이 되는 흐름을 먼저 만들고, 그 위에서 토큰 비용을 재기로 했습니다.</p>

<h3 id="판단-전용-모델-검토">판단 전용 모델 검토</h3>

<p>판별 에이전트를 만들던 무렵, 글을 생성하지 않고 정해 둔 선택지 가운데 답과 그 확률을 돌려주는 판단 전용 모델로 TypeSafe AI의 <a href="https://typesafe.ai/blog/introducing-system-one-models-and-jev">Jev</a>가 소개되었고, 이를 공개 API로 제공하는 서비스도 있었습니다. 판별처럼 고르기만 하는 호출은 지금 구조에서 가장 가벼운 모델을 쓰는데, 검토 당시 공개 요금표로 따져 보면 입력 1,000토큰과 출력 100토큰짜리 호출을 100만 번 해도 140달러에서 550달러 사이였습니다. 호출 한 번에 1원이 안 되는 돈이라, 판단 모델로 바꿔 아낄 수 있는 몫이 크지 않았습니다. 나중에 실험에서 잰 비슷한 분류 호출도 한 번에 입력 약 1,200토큰, 출력 약 90토큰이라 이 가정에서 크게 벗어나지 않았습니다.</p>

<p>반면 바꾸는 쪽에는 따로 드는 것이 있었습니다. 추천 이유 같은 문장은 판단 모델이 쓰지 않으니 그 자리에 다른 모델 호출이 하나 더 필요했고, 공개 API는 키마다 호출 한도가 있어 429나 503 응답을 받았을 때 돌아갈 경로도 따로 만들어야 했습니다. 호스팅 API로 바꾸면 데이터가 바깥으로 나가고, 직접 운영할 수 있는 공개 가중치는 CC BY-NC 4.0이라 상업 서비스에는 쓸 수 없었습니다. 후보를 제한하고 코드로 검증하는 장치는 이미 있었기 때문에, 기존 구조를 유지하기로 했습니다.</p>

<h3 id="에이전트-프레임워크-검토">에이전트 프레임워크 검토</h3>

<p>실행을 묶는 코드를 직접 쓰기 전에 LangChain과 LangGraph도 비교했습니다. LangChain이 줄여 주는 것은 모델 호출, 응답 파싱, 토큰 집계 정도였고, 허용 목록과 도메인 지침, 되돌리기 같은 나머지는 그대로 남았습니다.</p>

<p>LangGraph는 사정이 달랐습니다. 체크포인터에 상태를 저장해 두고 같은 스레드에서 멈춘 실행을 이어 가는 구조라서 상태를 저장할 곳이 있어야 하는데, <a href="https://docs.langchain.com/oss/python/langgraph/checkpointers#checkpointer-libraries">LangGraph 체크포인터 공식 문서</a>도 인메모리 체크포인터(<code class="language-plaintext highlighter-rouge">InMemorySaver</code>)는 실험용으로 두고, 운영에서는 Postgres 같은 데이터베이스 기반 체크포인터를 쓰도록 안내합니다. 지금 구조는 서버가 실행 상태를 들고 있지 않고, 화면이 에이전트의 진행 상태를 직접 구독하며, 요청과 화면 이동 같은 도구는 유저의 세션과 앱 화면에 묶여 있습니다. 그래서 LangGraph를 쓴다는 것은 라이브러리를 바꾸는 일이 아니라 실행 위치를 서버로 옮기는 일이라고 봤습니다. 옮기면 화면은 서버가 흘려보내는 상태 변화를 받아 다시 조립해야 하고, 브라우저에 묶인 도구는 서버가 브라우저에 되묻는 호출이 됩니다.</p>

<p>한 턴이 분 단위로 길어지거나 웹 밖의 클라이언트가 같은 에이전트를 불러야 하는 때가 오면, 그때는 프레임워크보다 실행 위치를 서버로 옮길지부터 고민해야 할 것 같습니다.</p>

<h2 id="사람에게-필요한-것과-에이전트에게-필요한-것">사람에게 필요한 것과 에이전트에게 필요한 것</h2>

<p>LLM만으로 유저의 수익이 늘어나지는 않습니다. 다만 이것만 에이전트의 한계는 아닙니다. 사람 역시 수익이 늘 늘어난다고 말할 수는 없었고, 비즈니스팀에게도 그런 방법은 없었습니다.</p>

<p>그 대신 비즈니스팀에는 몇 년 동안 일을 하며 쌓인 직관과, 이렇게 하면 잘 될 것이라는 규칙이 있었습니다. 새로 합류하는 사람을 위해 그 내용은 운영 전략 문서와 플레이북으로 정리되어 있었고, 그 문서는 에이전트가 쓸 지침으로도 어느 정도 쓸 수 있었습니다. 에이전트에게도 실제로 필요한 정보였기 때문입니다. 그대로 맞지 않는 부분은 골라 옮겼습니다. API를 그대로 읽으며 유저에게 필요했는데 놓치고 있던 기능을 발견한 일과, 결이 비슷했습니다.</p>

<p>성과를 예측하지 말라는 식의 금지선은 운영 지침이 아니라 코드에 남겨, 지침 문구를 고친다고 풀리지 않게 했습니다. 그리고 코드로 확인할 수 있는 부분, 예를 들어 근거로 든 값이 실제로 관측한 값인지는 코드가 검사해서 어긋난 답을 받지 않습니다. 에이전트에게도 “잘 되고 있다”고 단정하기보다, 확인 가능한 범위 안에서만 말하게 하고, 모르는 부분은 모른다고 적을 자리를 출력 형식에 따로 두었습니다.</p>

<p>제 생각엔 사람에게 필요한 것은 에이전트에게도 필요하고, 에이전트가 필요로 한 것은 사람에게도 필요합니다. 사람을 늘리지 않고 운영을 도우려면, 에이전트가 글을 잘 만드는 것만으로는 부족하고, 판단의 근거를 남기며 그 근거가 맞는지 확인할 수 있어야 합니다.</p>]]></content><author><name>zeno0505</name></author><category term="인사이트" /><summary type="html"><![CDATA[서버 인력 없이 프론트엔드만으로, 유저 운영을 돕는 에이전트에 API 명세만 넘기고 실행은 브라우저에서 하게 두며, 사람에게 필요한 판단 근거를 지침으로 쓰기로 했습니다.]]></summary></entry><entry><title type="html">사람은 프록시가 아니라 오케스트레이터가 되어야 한다</title><link href="https://zeno0505.github.io/dev-articles/2026/11/18/be-an-orchestrator-not-a-proxy/" rel="alternate" type="text/html" title="사람은 프록시가 아니라 오케스트레이터가 되어야 한다" /><published>2026-11-18T00:00:00+09:00</published><updated>2026-11-18T00:00:00+09:00</updated><id>https://zeno0505.github.io/dev-articles/2026/11/18/be-an-orchestrator-not-a-proxy</id><content type="html" xml:base="https://zeno0505.github.io/dev-articles/2026/11/18/be-an-orchestrator-not-a-proxy/"><![CDATA[<p>연초에 저는 태스크를 받아 에이전트에게 개발을 맡기고, 변경 요청까지 이어 주는 하네스를 만들어 공개해 두었습니다. <a href="https://github.com/zeno0505/dailyagent">dailyagent</a>가 그 저장소입니다. 파이프라인은 실제로 끝까지 돌아갔습니다. 다만 병목은 코드를 만드는 속도가 아니라, 그 결과를 사람이 이해하고 검수하는 일이었습니다. 그래서 태스크마다 판단을 반복하는 대신 초기 설계를 먼저 두고, 실행과 검증을 나누며, 사람은 전달자가 아니라 목표와 과정을 보는 쪽으로 남기로 했습니다.</p>

<p>여기서 에이전트는 사람 대신 작업을 이어서 해 주는 AI 프로그램을, 하네스는 그 에이전트가 일하는 규칙과 도구를 묶어 둔 구조를 말합니다.</p>

<h2 id="태스크를-바로-변경-요청으로-이은-한계">태스크를 바로 변경 요청으로 이은 한계</h2>

<p>출발점은 작업량이었습니다. 기존 화면을 새 버전으로 옮기는 일과 신규 기능 개발을 같이 감당하려다 보니, 개발을 자동으로 맡길 수단이 필요해졌습니다. 처음 만든 흐름은 태스크 도구에서 변경 요청까지를 한 번에 잇는 방식이었습니다.</p>

<p>기다리는 상태의 태스크를 가져와, 선행 작업이 끝난 것만 남긴 뒤 우선순위로 하나를 고릅니다. 에이전트는 기준 브랜치를 최신으로 맞추고 작업 브랜치를 만든 다음, 요구사항대로 코드를 고치고 커밋합니다. 같은 흐름 안에서 목적에 맞았는지, 부작용은 없는지를 스스로 검토하고, 원격 저장소에 올린 뒤 초안 변경 요청을 만듭니다. 끝나면 태스크 쪽에 상태와 브랜치, 커밋, 변경 요청 주소를 다시 적습니다. 대기 항목이 없으면, 정해 둔 횟수 안에서 이미 올라온 결과를 다시 검토하게 둘 수도 있었습니다. 계획과 구현과 검토를 세션으로 나눌 수는 있었지만, 그 검토도 같은 자동 파이프라인 안의 일이었습니다.</p>

<p>에이전트에게 넘기는 결과는 대략 이런 형태였습니다. 브랜치명, 커밋, 바꾼 파일, 요약, 그리고 변경 요청 주소입니다. 태스크 본문에 적힌 내용은 데이터로만 보고, 하네스의 지시를 덮지 못하게 했습니다.</p>

<p>완성 자체는 되었습니다. 다만 태스크에 담긴 맥락만으로는 부족한 경우가 많았습니다. 이미지나 재현 영상만 올라가 있거나, 그 화면이 정확히 어디인지, 왜 그렇게 동작해야 하는지 기획 의도가 빠져 있기도 했습니다. 맥락이 부족한 채로 만든 변경 요청은 검수하기 어려웠고, 사람이 다시 조사하고 보완하다 보니 직접 개발하는 일과 크게 다르지 않았습니다.</p>

<p>제 생각엔 진짜 문제는 인지 부하입니다. 에이전트가 짠 코드를 사람이 바로 이해하지 못하는 문제입니다. 파이프라인이 결과를 만들어 주는 것과, 그 결과를 사람이 책임지고 받을 수 있는 것은 다른 일이었습니다.</p>

<pre><code class="language-mermaid">flowchart TD
  db[대기 태스크 조회] --&gt; pick[선행 완료와 우선순위로 선택]
  pick --&gt; work[구현과 커밋]
  work --&gt; check[같은 흐름에서 자체 검토]
  check --&gt; pr[초안 변경 요청]
  pr --&gt; done[상태 갱신]
</code></pre>

<h2 id="초기-설계를-먼저-두는-이유">초기 설계를 먼저 두는 이유</h2>

<p>그래서 순서를 바꿨습니다. 태스크마다 반복하던 판단을 처음 설계 단계로 모았습니다. 초기 설계에서 작업 단위, 변경 요청 단위, 그리고 그 요청을 어떤 순서로 이을지를 먼저 정합니다. 에이전트는 그 설계를 따라 변경 요청을 하나씩 만들고, 요청마다 검증한 기록을 남깁니다. 검증했다는 말이 아니라, 검증한 기록이 남게 한 겁니다.</p>

<p>먼저 설계하면 판단을 설계 단계로 모을 수 있어, 태스크마다 같은 결정을 반복하지 않아도 됩니다. 최초 설계에 제가 직접 참여했기 때문에, 에이전트가 어떤 작업을 하는지가 머릿속에 남아 있습니다. 나중에 확인하더라도 방향이 어긋나기 어렵고, 「이건 이렇게 하면 안 되는데」 같은 상황을 예전보다 덜 만나게 되었습니다.</p>

<pre><code class="language-mermaid">flowchart TD
  design[초기 설계] --&gt; pr1[변경 요청 1]
  pr1 --&gt; rec1[검증 기록 1]
  rec1 --&gt; pr2[변경 요청 2]
  pr2 --&gt; rec2[검증 기록 2]
  rec2 --&gt; pr3[변경 요청 3]
  pr3 --&gt; rec3[검증 기록 3]
</code></pre>

<p>설계를 먼저 두는 일과, 제안의 성과를 누가 책임질지는 다른 문제였습니다. 에이전트의 제안대로 사람이 따라도, 그 성과를 아무도 장담할 수 없다는 질문을 만난 적이 있습니다. 근거 없이 그럴듯한 안을 내놓도록 두면, 실행 결과는 아무도 책임질 수 없습니다. 그래서 제안 뒤에 실제로 일어난 일을 기록하고, 숫자로 가릴 수 있는 구조를 갖추려 했습니다. 이 판단은 이후 다른 에이전트 작업 규칙에도, 측정할 수 있는 지표를 먼저 두라는 쪽으로 이어졌습니다.</p>

<h2 id="하네스에서-팀과-역할을-나누는-방식">하네스에서 팀과 역할을 나누는 방식</h2>

<p>그 뒤에는, 에이전트 팀이 쓸 하네스를 어떻게 구성하고 팀과 에이전트를 어떻게 나눌지를 규칙으로 정리했습니다. 사람이 정해야 하는 사실만 묻고, 코드나 이미 적혀 있는 등록부에서 알 수 있는 것은 다시 묻지 않기로 했습니다. 모르는 값은 지어내지 않습니다.</p>

<p>하네스는 두 층을 나눕니다. 한쪽은 팀이 일하는 방식의 정의입니다. 역할, 지침, 권한, 사람이 확인해야 하는 관문처럼, 쉽게 바뀌면 안 되는 규칙을 둡니다. 다른 한쪽은 실행 기록입니다. 결정과 합의, 다음 에이전트가 읽을 산출물은 여기에 남깁니다. 알림만 오가고 기록이 없으면, 그 합의는 없는 것으로 봅니다.</p>

<p>팀을 만들 때는 먼저 일을 업무 단위로 나눕니다. 각 업무가 무엇을 읽고, 무엇을 쓰며, 시작에 어떤 맥락이 필요한지를 밝힙니다. 그다음 업무마다, 기계가 검증할 일인지, 사람이 관찰하거나 결정해야 하는 일인지를 가립니다. 에이전트로 묶을 때는 한 업무의 출력을 다른 업무가 읽는 강한 연결을 출발점으로 삼습니다. 전문성이 다를 뿐이면 새 에이전트를 만들기보다, 기존 에이전트에 그 능력을 붙입니다. 따로 두는 이유는 독립 실행, 병렬, 맥락 격리, 권한 경계가 필요할 때입니다. 만드는 일과 판정하는 일을 한 주체에 섞지 않습니다.</p>

<p>역할은 실행, 검증, 운영으로 나눕니다. 실행과 검증은 같은 에이전트에 묶지 않습니다. 평가의 맨 위는 사람이고, 자기 자신을 평가하는 관계는 두지 않습니다. 권한은 에이전트가 스스로 부여하지 않고, 요청서를 남겨 사람이 줍니다. 에이전트를 새로 둘지도 사람이 정합니다. 별도 실행 주체가 필요 없으면 만들지 않고, 목표를 숫자로 볼 수 있을 때만 지표를 고르되, 고른 직후부터 확정된 기준으로 쓰지는 않습니다.</p>

<p>처음 하네스가 태스크에서 변경 요청까지를 한 줄로 이었다면, 지금은 그 줄을 놓기 전에 업무와 역할과 관문부터 정하는 쪽에 가깝습니다. 그래야 사람이 모든 코드를 다시 읽지 않고도, 구조로 일을 지휘할 수 있다고 봤습니다.</p>

<pre><code class="language-mermaid">flowchart TD
  duties[업무로 나누기] --&gt; group[연결에 따라 에이전트로 묶기]
  group --&gt; roles[실행과 검증과 운영]
  roles --&gt; human[맨 위는 사람]
</code></pre>

<h2 id="완료를-실행으로-증명하는-방식">완료를 실행으로 증명하는 방식</h2>

<p>지금 방식을 지탱하는 중심은 완료 증명입니다. 정확도를 높이려면, 에이전트가 스스로 일이 끝났다는 걸 증명하게 해야 한다고 봅니다. 검증 수단이 없으면 에이전트는 「생각한 대로 구현했습니다」라고밖에 말하지 못합니다. 처음 하네스의 자체 검토만으로는, 만드는 쪽과 판정하는 쪽이 아직 충분히 나뉘지 않았습니다.</p>

<p>그래서 직접 실행해서 증명하게 합니다. 테스트 케이스를 돌리기 전에 테스트 계정의 권한과 상태를 확인하고, 그다음 작업을 실제로 실행한 뒤 테스트를 돌립니다. 마지막으로는 결과와 오류를 근거로 내놓게 합니다. 이렇게 해 두면 실패했을 때, 기능이 정말 고장 난 건지 테스트 준비가 덜 된 건지 구분할 수 있습니다. 에이전트가 실행한 내역은, 그 에이전트를 믿을지 판단하는 근거가 됩니다. 그 근거를 읽는 쪽은, 가능하면 구현한 에이전트와 다른 검증 역할이어야 한다고 봅니다.</p>

<pre><code class="language-mermaid">flowchart TD
  claim[완료 주장] --&gt; prep[계정 권한과 상태 확인]
  prep --&gt; run[실제 실행과 테스트]
  run --&gt; evidence[결과와 오류를 근거로 제시]
  evidence --&gt; fork{실패인가}
  fork --&gt;|기능 고장| bug[기능 문제]
  fork --&gt;|준비 부족| setup[테스트 준비 문제]
</code></pre>

<h2 id="사람에게-남기는-일과-권한">사람에게 남기는 일과 권한</h2>

<p>구조를 바꿔도 에이전트 사용량과 컴퓨팅 자원은 유한합니다. 여러 에이전트를 동시에 돌리면 로컬 머신이 멈추기도 했습니다. 인지 부하는 그 가운데서도, 보여 주는 방식을 바꾸면 줄일 여지가 있다고 봅니다. 긴 리포트 하나만 남기기보다 이미지, 문서, 영상처럼 한눈에 들어오는 자료로 보강하는 쪽이 읽기 쉽습니다.</p>

<p>다만 사람이 모든 단계를 볼 필요는 없습니다. 지금은 초기 설계, 큰 결정, 사람이 꼭 확인할 것만 제가 보고, 나머지는 자동화하려고 합니다. 명백한 오류는 에이전트가 고치고 확인까지 한 뒤 기록에 남기고, 기획 맥락이 필요하거나 확인에 품이 많이 드는 일, 개발자가 봐야 하는 일은 사람에게 올립니다. 되돌리기 어려운 실행이나 민감한 경로처럼, 사람이 열어 줘야 하는 관문은 사실에서 찾아 제안하되, 등록은 사람이 합니다.</p>

<p>앞으로 에이전트를 다루는 사람에게는 판단이 세 가지 필요하다고 봅니다. 첫째, 끝났다면 무엇으로 확인했는지 근거를 요구하고 의심하는 일입니다. 둘째, 작업이 목표에 비해 과하거나 흐려지지 않았는지 보는 일입니다. 맥락이 길어질수록 처음 목표가 흐려지기 쉬워서, 사람이 목표를 붙잡고 있어야 한다고 봅니다. 셋째, 이 일을 맡겨도 되는지 판단하고 권한을 나누는 일입니다. 안전하게 다룰 수 있는 범위와 그렇지 않은 범위를 나누지 않으면, 속도만 빠르고 근거 없는 위임이 됩니다.</p>

<p>한 사람이 모든 깊이를 가질 수는 없다고 봅니다. 다만 직군마다, 에이전트에게 맡길 수 있는 일, 올바르게 하려면 검증 수단이 필요한 일, 사람이 해야만 하는 일을 나눌 수는 있다고 생각합니다.</p>

<h2 id="프록시와-오케스트레이터">프록시와 오케스트레이터</h2>

<p>최근 <a href="https://www.youtube.com/@pragmatic-dev">실용주의 개발</a>의 「<a href="https://www.youtube.com/watch?v=wnvu0E4X7iY">요즘 개발자들이 AI 때문에 진짜 빡치는 순간</a>」을 보다가, 미트 프록시라는 말을 처음 들었습니다. 영상은 <a href="https://rudyfaile.com/2026/09/24/the-age-of-the-soft-skill/">The Age of the Soft Skill</a>을 따라가며, 누군가의 질문을 그대로 AI에 붙여 넣고 나온 답을 다시 그대로 돌려주는 사람을 그렇게 부릅니다. AI가 답변한 것을 그대로 중계하는 역할을 하니 이렇게 표현한 것입니다. 묻는 사람은 그 사람의 판단이나 맥락이 궁금해서 물었는데, 돌아오는 것은 본인도 직접 받을 수 있는 AI 답입니다. 그 글은, 틀린 답을 기계에게서 바로 받는 편이, 같은 답을 한참 뒤에 그 사람 이름표만 붙여 받는 것보다 낫다고까지 합니다. AI를 쓰지 말라는 이야기가 아닙니다. 내 시간을 아끼려고 읽는 부담을 상대에게 넘기지 말라는 이야기에 가깝습니다.</p>

<p><img src="/dev-articles/assets/2026-11-18-be-an-orchestrator-not-a-proxy-01.png" alt="A가 B에게 물은 내용을 B가 에이전트에 그대로 붙여 넣고, 받은 답을 다시 A에게 그대로 보내는 예시" /></p>

<p>A가 B에게 물은 내용을 B가 에이전트에 그대로 붙여 넣고, 받은 답을 다시 A에게 그대로 보내는 예시입니다.</p>

<p>이 영상을 보고 팀에서도 이야기를 나눴습니다. 제가 공감한 부분은, 요즘은 제가 AI와 AI를 잇는 사람 프록시가 된 것 같다는 느낌이었습니다. 팀에서 나온 말 가운데 저는 이 구분이 중요하다고 봤습니다. 에이전트의 말을 보고 검토해서 남길 것은 남기고 보완할 것은 보완하는 일과, 그 말을 그대로 붙여 다음 에이전트나 사람에게 넘기는 일은 다릅니다. 여러 에이전트가 계획과 구현과 검토를 이어 가더라도, 결정과 역할과 검토 규칙을 사람이 정해 두면 그건 오케스트레이션에 가깝습니다. 반대로 검토하지 않은 AI 출력을 그대로 전달받으면, 읽기 어려운 해석을 상대에게 맡기게 되고 말하는 사람의 판단은 빠집니다.</p>

<p>남이 만든 업무 흐름에 나를 맞추기는 생각보다 어렵습니다. 그래서 오늘 정리한 방식을 그대로 따라 하실 필요는 없다고 봅니다.</p>

<p>다만 역할만은 분명히 하고 싶습니다. 미트 프록시는 에이전트의 말을 그대로 믿고, 다른 에이전트나 다음 작업으로 잇는 전달자입니다. 오케스트레이터는 에이전트가 목표를 올바르게 세웠는지, 그 과정이 타당한지 보고, 꼭 필요한 일을 나누는 쪽입니다. 제 생각엔 사람은 프록시가 아니라 오케스트레이터가 되어야 합니다.</p>

<p>그래서 저는 이렇게 정리하고 싶습니다. AI가 믿을 수 있는 근거를 내놓으며 업무 흐름을 대리할 수 있는 구조를, 사람이 설계하는 일입니다.</p>]]></content><author><name>zeno0505</name></author><category term="인사이트" /><summary type="html"><![CDATA[연초에 태스크를 받아 변경 요청까지 잇는 하네스를 만들어 공개했습니다. 병목은 생성이 아니라 검수였고, 그래서 초기 설계를 먼저 두며, 실행과 검증을 나누고, 사람은 전달자가 아니라 목표와 과정을 보는 쪽으로 남기로 했습니다.]]></summary></entry><entry><title type="html">자동화 트래픽은 분석 수집 단계에서 끈다</title><link href="https://zeno0505.github.io/dev-articles/2026/11/18/turn-off-analytics-at-collection/" rel="alternate" type="text/html" title="자동화 트래픽은 분석 수집 단계에서 끈다" /><published>2026-11-18T00:00:00+09:00</published><updated>2026-11-18T00:00:00+09:00</updated><id>https://zeno0505.github.io/dev-articles/2026/11/18/turn-off-analytics-at-collection</id><content type="html" xml:base="https://zeno0505.github.io/dev-articles/2026/11/18/turn-off-analytics-at-collection/"><![CDATA[<p>최근 트래픽이 비정상적으로 늘어난 현상을 조사하다가, 그 요청이 서버 부하뿐 아니라 분석 이벤트까지 들어가 있는 걸 확인했습니다. 액세스 로그의 User-Agent는 HeadlessChrome인데, Mixpanel의 브라우저 값은 Chrome으로 적혀 있었습니다. 그래서 사후에 브라우저 값으로 거르지 않고, SDK를 초기화하기 전에 수집을 끄되, 봇 User-Agent 패턴의 최신화는 isbot 패키지에 맡기기로 했습니다.</p>

<h2 id="분석-값과-액세스-로그의-어긋남">분석 값과 액세스 로그의 어긋남</h2>

<p>처음에는 늘어난 요청이 어디서 오는지부터 봤습니다. 액세스 로그의 User-Agent를 같은 계정·같은 구간으로 맞춰 보니, 요청이 HeadlessChrome으로 들어오고 있었습니다. Mixpanel에 쌓인 이벤트 수도 그 계정들과 맞아서, 그 트래픽이 분석 데이터에 실제로 들어온 것도 확인했습니다.</p>

<p>다만 Mixpanel에서 브라우저 값만 보면 Chrome이었습니다. 이미 들어온 이벤트는 계정 단위로 분석에서 빼 달라고 요청했고, 앞으로는 자동화 브라우저에서 수집 자체가 되지 않게 막기로 했습니다.</p>

<h2 id="브라우저-이름이-chrome이-되는-이유">브라우저 이름이 Chrome이 되는 이유</h2>

<p>Mixpanel 자바스크립트 SDK는 기본 속성 <code class="language-plaintext highlighter-rouge">$browser</code>를 <code class="language-plaintext highlighter-rouge">navigator.userAgent</code>에서 만듭니다. 소스의 <code class="language-plaintext highlighter-rouge">_.info.browser</code>는 문자열에 <code class="language-plaintext highlighter-rouge">Chrome</code>이 포함되면 브라우저 이름을 Chrome으로 적습니다. HeadlessChrome이라는 토큰 안에 이미 <code class="language-plaintext highlighter-rouge">Chrome</code>이 들어 있으므로, 원문이 HeadlessChrome이어도 리포트의 브라우저 값은 Chrome이 됩니다. 브라우저 값만으로 헤드리스 트래픽을 가르려고 하면, 일반 Chrome 조회와 구분이 되지 않습니다.</p>

<p>SDK가 기본적으로 거르는 User-Agent 목록은 Googlebot, bingbot처럼 알려진 크롤러 중심입니다. 공식 문서도 그 목록에 없는 봇은 데이터에 영향을 준다고 적혀 있습니다. HeadlessChrome은 그 목록에 없습니다. 그래서 수집을 끌 기준을 Mixpanel 기본 목록에만 두지 않기로 했습니다.</p>

<p>자동화 여부는 User-Agent만의 문제가 아닙니다. <code class="language-plaintext highlighter-rouge">navigator.webdriver</code>는 사용자 에이전트가 자동화로 조종되는지를 알리는 표준 속성입니다. MDN 기준으로 Chrome에서는 <code class="language-plaintext highlighter-rouge">--headless</code> 또는 <code class="language-plaintext highlighter-rouge">--enable-automation</code>을 쓰면 이 값이 true입니다. isbot은 User-Agent 문자열만 보므로, 수집 가드에는 이 플래그를 같이 두기로 했습니다.</p>

<pre><code class="language-mermaid">flowchart TD
  open[페이지 열림] --&gt; signal[자동화 신호인가]
  signal --&gt;|있다| skip[초기화 생략]
  skip --&gt; drain[대기 이벤트 비움]
  signal --&gt;|없다| init[SDK 초기화]
  init --&gt; collect[이벤트 수집]
</code></pre>

<p>자동화 신호는 <code class="language-plaintext highlighter-rouge">navigator.webdriver</code>가 true이거나, isbot의 <code class="language-plaintext highlighter-rouge">isBot(userAgent)</code>이 true인 경우입니다.</p>

<h2 id="초기화-전에-두는-수집-가드">초기화 전에 두는 수집 가드</h2>

<p>자동화로 보이면 Mixpanel SDK의 <code class="language-plaintext highlighter-rouge">init</code> 자체를 건너뛰기로 했습니다. 꺼진 뒤에도 초기화 전에 쌓아 둔 이벤트가 나중에 나가면 안 되므로, 그때 대기열을 비우고, 이후 식별·추적 호출도 보내지 않습니다. 공식 문서의 <code class="language-plaintext highlighter-rouge">opt_out_tracking()</code>은 초기화 이후에 쓰는 방법이라, 이 가드에는 쓰지 않았습니다.</p>

<p>봇 User-Agent를 제 정규식으로 직접 들고 있으면, 새 봇이 나올 때마다 목록을 따라가야 합니다. 그래서 User-Agent 판정만 isbot 5.2.2에 맡기고, <code class="language-plaintext highlighter-rouge">navigator.webdriver</code>는 따로 같이 보기로 했습니다. 패턴 최신화는 패키지 버전을 올려 받습니다. isbot 5.2의 export는 <code class="language-plaintext highlighter-rouge">isBot(ua)</code>입니다. 아래는 같은 구조로 새로 쓴 예시입니다. 프로젝트 토큰이나 서비스 코드가 아닙니다.</p>

<div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">import</span> <span class="p">{</span> <span class="nx">isBot</span> <span class="p">}</span> <span class="k">from</span> <span class="dl">'</span><span class="s1">isbot</span><span class="dl">'</span><span class="p">;</span>

<span class="kd">let</span> <span class="nx">trackingDisabled</span> <span class="o">=</span> <span class="kc">false</span><span class="p">;</span>
<span class="kd">let</span> <span class="nx">ready</span> <span class="o">=</span> <span class="kc">false</span><span class="p">;</span>
<span class="kd">const</span> <span class="nx">pendingEvents</span> <span class="o">=</span> <span class="p">[];</span>

<span class="kd">function</span> <span class="nx">isAutomatedBrowser</span><span class="p">(</span><span class="nx">nav</span> <span class="o">=</span> <span class="nx">globalThis</span><span class="p">.</span><span class="nb">navigator</span> <span class="o">??</span> <span class="kc">null</span><span class="p">)</span> <span class="p">{</span>
  <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nx">nav</span><span class="p">)</span> <span class="k">return</span> <span class="kc">false</span><span class="p">;</span>
  <span class="k">return</span> <span class="nx">nav</span><span class="p">.</span><span class="nx">webdriver</span> <span class="o">===</span> <span class="kc">true</span> <span class="o">||</span> <span class="nx">isBot</span><span class="p">(</span><span class="nx">nav</span><span class="p">.</span><span class="nx">userAgent</span><span class="p">);</span>
<span class="p">}</span>

<span class="kd">function</span> <span class="nx">initAnalytics</span><span class="p">()</span> <span class="p">{</span>
  <span class="k">if</span> <span class="p">(</span><span class="nx">isAutomatedBrowser</span><span class="p">())</span> <span class="p">{</span>
    <span class="nx">trackingDisabled</span> <span class="o">=</span> <span class="kc">true</span><span class="p">;</span>
    <span class="nx">pendingEvents</span><span class="p">.</span><span class="nx">length</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
    <span class="k">return</span><span class="p">;</span>
  <span class="p">}</span>
  <span class="nx">mixpanel</span><span class="p">.</span><span class="nx">init</span><span class="p">(</span><span class="dl">'</span><span class="s1">YOUR_PROJECT_TOKEN</span><span class="dl">'</span><span class="p">);</span>
  <span class="nx">ready</span> <span class="o">=</span> <span class="kc">true</span><span class="p">;</span>
<span class="p">}</span>

<span class="kd">function</span> <span class="nx">track</span><span class="p">(</span><span class="nx">event</span><span class="p">,</span> <span class="nx">payload</span><span class="p">)</span> <span class="p">{</span>
  <span class="k">if</span> <span class="p">(</span><span class="nx">trackingDisabled</span><span class="p">)</span> <span class="k">return</span><span class="p">;</span>
  <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nx">ready</span><span class="p">)</span> <span class="p">{</span>
    <span class="nx">pendingEvents</span><span class="p">.</span><span class="nx">push</span><span class="p">([</span><span class="nx">event</span><span class="p">,</span> <span class="nx">payload</span><span class="p">]);</span>
    <span class="k">return</span><span class="p">;</span>
  <span class="p">}</span>
  <span class="nx">mixpanel</span><span class="p">.</span><span class="nx">track</span><span class="p">(</span><span class="nx">event</span><span class="p">,</span> <span class="nx">payload</span><span class="p">);</span>
<span class="p">}</span>
</code></pre></div></div>

<p>isbot 5.2.2 기준으로 HeadlessChrome이나 Applebot이 들어 있는 User-Agent는 <code class="language-plaintext highlighter-rouge">isBot</code>이 true를 돌려 줍니다. 일반 Chrome이나 Safari, 흔한 인앱 브라우저 문자열은 false입니다. 같은 Chrome User-Agent라도 <code class="language-plaintext highlighter-rouge">navigator.webdriver</code>가 true면 자동화로 봅니다. <code class="language-plaintext highlighter-rouge">navigator</code>가 없는 환경에서는 자동화로 보지 않습니다. 헤드리스 브라우저에서 페이지를 열어 보니 Mixpanel 요청은 나가지 않았고, 같은 페이지를 일반 브라우저에서 열면 이벤트는 그대로 나갔습니다. User-Agent를 일반 브라우저처럼 바꾸면 isbot은 봇으로 보지 않고, <code class="language-plaintext highlighter-rouge">navigator.webdriver</code>를 숨기면 이 가드는 지나갈 수 있습니다. isbot 문서도, 사람처럼 위장한 프로그램까지 찾는 도구는 아니라고 적혀 있습니다.</p>

<h2 id="요청을-막는-방법과-비교">요청을 막는 방법과 비교</h2>

<p>요청 자체를 앞에서 막는 방법도 검토했습니다. 그러면 분석 이벤트뿐 아니라 서버 부하까지 줄어듭니다. 다만 사람이 자신의 에이전트를 붙여 화면을 자동으로 보게 하는 쓰임까지 막을 수 있습니다. 그 범위를 서비스 정책으로 정하기 전에는, 요청을 막는 방법은 쓰지 않기로 했습니다.</p>

<p>이미 들어온 이벤트를 분석에서 빼는 일도 필요합니다. Mixpanel은 한 번 들어온 이벤트를 삭제하지 못하고, 속성으로 걸러 보는 방식을 안내합니다. 다만 사후 필터는 이미 쌓인 오염을 리포트에서 가릴 뿐이고, 새로 들어오는 이벤트와 사용량까지 막지는 못합니다. 그래서 앞으로의 수집은 초기화 전에 끄고, 이미 들어온 분량은 분석 쪽에서 제외하는 쪽으로 나눴습니다.</p>

<p>봇 목록을 HeadlessChrome, Applebot처럼 직접 정규식으로 고정하는 방법도 있었습니다. 당장의 로그에는 그걸로도 걸립니다. 다만 목록을 제가 쥐고 있으면 최신화를 놓치기 쉽습니다. Mixpanel SDK 기본 목록도 알려진 크롤러 중심이라, 헤드리스 브라우저를 놓친 것과 같은 빈틈이 남을 수 있습니다. 제 생각엔 패턴 갱신은 그 목록을 꾸준히 고치는 패키지에 맡기는 편이 낫습니다.</p>

<h2 id="왜-수집-단계에서-끄기로-했는지">왜 수집 단계에서 끄기로 했는지</h2>

<p>분석 도구와 오류 추적 도구는, 자동화된 요청이 들어오면 사용량이 늘고 지표가 흔들릴 수 있습니다. 요청을 막는 정책이 정해지기 전이어도, 자동화 브라우저에서는 추적을 먼저 끄고 보는 편이 낫다고 봤습니다. 봇 User-Agent 판단은 isbot에 맡기고, 패키지가 따라가지 않는 자동화 신호는 <code class="language-plaintext highlighter-rouge">navigator.webdriver</code>로 보완하기로 했습니다.</p>

<p>다만 User-Agent는 바꾸기 쉽습니다. 1차로 자동화 신호에서 수집을 끈 뒤에도 이상 로그가 다시 보이면, 그 로그의 특징을 재확인해서 2차로 가리기로 했습니다. 다음에 같은 일을 보면, 분석 SDK는 자동화 신호일 때 초기화하지 않는 쪽을 먼저 두려고 합니다.</p>

<h2 id="정리">정리</h2>

<p>분석 리포트의 브라우저 값이 Chrome이어도, 원문 User-Agent와 자동화 플래그는 다를 수 있습니다. 헤드리스 트래픽은 브라우저 값으로 사후에 가르기보다, 수집이 시작되기 전에 끄는 편이 맞다고 봅니다.</p>

<h2 id="참고">참고</h2>

<ul>
  <li><a href="https://docs.mixpanel.com/docs/data-structure/property-reference/default-properties">Mixpanel Default Properties</a> — <code class="language-plaintext highlighter-rouge">$browser</code>, <code class="language-plaintext highlighter-rouge">$mp_raw_user_agent</code></li>
  <li><a href="https://docs.mixpanel.com/docs/tracking-methods/sdks/javascript">Mixpanel JavaScript SDK</a> — 기본은 추적 켜진 채 <code class="language-plaintext highlighter-rouge">init</code></li>
  <li><a href="https://docs.mixpanel.com/docs/tracking-best-practices/bot-traffic">Mixpanel Block Unwanted Traffic</a> — SDK 기본 봇 필터와 <code class="language-plaintext highlighter-rouge">$ignore</code></li>
  <li><a href="https://github.com/mixpanel/mixpanel-js/blob/master/src/utils.js">mixpanel-js <code class="language-plaintext highlighter-rouge">src/utils.js</code></a> — <code class="language-plaintext highlighter-rouge">_.info.browser</code>, <code class="language-plaintext highlighter-rouge">BLOCKED_UA_STRS</code> / <code class="language-plaintext highlighter-rouge">_.isBlockedUA</code></li>
  <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/Navigator/webdriver">MDN: <code class="language-plaintext highlighter-rouge">Navigator.webdriver</code></a></li>
  <li><a href="https://www.npmjs.com/package/isbot/v/5.2.2">isbot (npm 5.2.2)</a> — <code class="language-plaintext highlighter-rouge">import { isBot } from "isbot"</code>, <code class="language-plaintext highlighter-rouge">isBot(userAgent)</code>, 패턴은 패키지 갱신으로 받음</li>
</ul>]]></content><author><name>zeno0505</name></author><category term="일일 회고" /><summary type="html"><![CDATA[최근 트래픽이 비정상적으로 늘어난 현상을 조사하다가, 분석 이벤트가 오염된 걸 확인했습니다. 브라우저 값으로 거르지 않고 SDK 초기화 전에 수집을 끄되, 봇 User-Agent 최신화는 isbot에 맡기기로 했습니다.]]></summary></entry><entry><title type="html">SSR에서 부르는 API는 세션과 첫 화면으로 나눈다</title><link href="https://zeno0505.github.io/dev-articles/2026/11/17/ssr-apis-by-session-and-screen/" rel="alternate" type="text/html" title="SSR에서 부르는 API는 세션과 첫 화면으로 나눈다" /><published>2026-11-17T00:00:00+09:00</published><updated>2026-11-17T00:00:00+09:00</updated><id>https://zeno0505.github.io/dev-articles/2026/11/17/ssr-apis-by-session-and-screen</id><content type="html" xml:base="https://zeno0505.github.io/dev-articles/2026/11/17/ssr-apis-by-session-and-screen/"><![CDATA[<p>서버가 페이지를 그리는 시점에 부르는 API를, 봇 요청과 사람 요청에 똑같이 붙여 두었습니다. 페이지 하나를 열면 로그인 확인과 채널·설정 API가 같이 나갔고, 크롤러가 그 페이지를 열 때마다 그 호출이 그대로 붙었습니다. 그래서 요청에 세션 쿠키가 있는지, 그 값이 첫 화면에 꼭 필요한지로 호출을 나누기로 했습니다.</p>

<p>이 글은 서버에서 페이지를 그릴 때, 봇이나 비로그인 요청에도 로그인 확인이나 설정 API가 같이 나가는 분께 도움이 됩니다.</p>

<h2 id="한눈에-보는-결론">한눈에 보는 결론</h2>

<ul>
  <li>제약: 첫 화면에 필요한 내용은 서버에서 그려야 하고, 사람이 보는 화면은 그대로여야 합니다. 다만 세션이 없거나 첫 화면에 없는 값은, 페이지를 여는 모든 요청에 붙여 둘 필요가 없습니다.</li>
  <li>결정: 쿠키가 없으면 로그인 확인을 생략하고, 설정은 쓰는 화면에서만 클라이언트에서 부르며, 부가 UI API는 그 UI를 열 때 호출합니다.</li>
</ul>

<h2 id="과제와-제약">과제와 제약</h2>

<p>목표는 서버가 그리는 첫 화면은 유지하면서, 페이지를 열 때마다 같이 나가던 호출을 나누는 것이었습니다. 기존 서버 렌더링은 들어온 요청을 사람 페이지처럼 다루어, 봇이 페이지 하나를 열어도 로그인 확인과 페이지 API가 나갔고, 채널 페이지면 채널·설정 API까지 같이 나갔습니다. 자바스크립트를 실행하는 봇은 본문 아래 부가 UI용 호출까지 만들 수 있었습니다. 첫 화면을 비우면 사람이 보는 내용이 빠지므로, 호출을 통째로 빼는 방법은 쓸 수 없었습니다.</p>

<h2 id="제약에-맞춰-고른-방법">제약에 맞춰 고른 방법</h2>

<p>선택지는 세 가지였습니다. User-Agent로 봇을 막아 호출 자체를 줄이는 방법, 서버에서 설정 응답을 캐시하는 방법, 그리고 호출을 세션 유무와 첫 화면 필요 여부로 나누는 방법입니다. User-Agent 차단은 우회가 쉬워, 그것만으로는 부족하고 보조 수단에 가깝습니다. 서버 캐시는 같은 설정을 반복해서 읽는 비용을 줄이지만, 쿠키가 없는데도 로그인 확인을 부르는 구조 자체는 남습니다. 그래서 호출을 나누는 쪽을 택하고, 서버 캐시는 같이 쓰기로 했습니다.</p>

<p>로그인 확인은 세션 쿠키가 있을 때만 서버에서 부릅니다. 설정은 그 값을 쓰는 화면의 클라이언트에서만 부르고, 부가 UI는 패널을 여는 시점에 호출합니다. 자바스크립트를 실행하지 않는 봇에는 클라이언트 호출이 나가지 않고, 설정 장치를 두지 않은 화면에도 설정 API가 나가지 않습니다.</p>

<h2 id="기본-구조">기본 구조</h2>

<p>아래는 그 구분을 Nuxt 3의 useCookie와 useFetch로 옮긴 일반 예시입니다. useCookie는 서버와 클라이언트에서 쿠키를 읽을 수 있고, useFetch는 기본이 서버에서도 호출이며, <code class="language-plaintext highlighter-rouge">server: false</code>와 <code class="language-plaintext highlighter-rouge">immediate: false</code>로 그 시점을 옮길 수 있습니다.</p>

<pre><code class="language-mermaid">flowchart TD
  req[페이지 요청] --&gt; page[페이지 API]
  req --&gt; cookie{세션 쿠키가 있나}
  cookie --&gt;|있다| session[로그인 확인 API]
  cookie --&gt;|없다| skip[로그인 확인 생략]
  page --&gt; first[첫 화면 렌더]
  session --&gt; first
  skip --&gt; first
  first --&gt; settings[설정: 쓰는 화면에서만 클라이언트 호출]
  first --&gt; extra[부가 UI: 열 때 호출]
</code></pre>

<div class="language-vue highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;</span><span class="k">script</span> <span class="na">setup</span> <span class="na">lang=</span><span class="s">"ts"</span><span class="nt">&gt;</span>
<span class="kd">const</span> <span class="nx">sessionCookie</span> <span class="o">=</span> <span class="nx">useCookie</span><span class="p">(</span><span class="dl">'</span><span class="s1">session</span><span class="dl">'</span><span class="p">)</span>

<span class="kd">const</span> <span class="p">{</span> <span class="na">data</span><span class="p">:</span> <span class="nx">page</span> <span class="p">}</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">useFetch</span><span class="p">(</span><span class="dl">'</span><span class="s1">/api/page</span><span class="dl">'</span><span class="p">)</span>

<span class="kd">const</span> <span class="p">{</span> <span class="na">data</span><span class="p">:</span> <span class="nx">session</span> <span class="p">}</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">useFetch</span><span class="p">(</span><span class="dl">'</span><span class="s1">/api/session</span><span class="dl">'</span><span class="p">,</span> <span class="p">{</span>
  <span class="na">immediate</span><span class="p">:</span> <span class="nb">Boolean</span><span class="p">(</span><span class="nx">sessionCookie</span><span class="p">.</span><span class="nx">value</span><span class="p">),</span>
<span class="p">})</span>

<span class="kd">const</span> <span class="p">{</span> <span class="na">data</span><span class="p">:</span> <span class="nx">settings</span> <span class="p">}</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">useFetch</span><span class="p">(</span><span class="dl">'</span><span class="s1">/api/settings</span><span class="dl">'</span><span class="p">,</span> <span class="p">{</span>
  <span class="na">server</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
<span class="p">})</span>

<span class="kd">const</span> <span class="p">{</span> <span class="na">execute</span><span class="p">:</span> <span class="nx">loadExtras</span> <span class="p">}</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">useFetch</span><span class="p">(</span><span class="dl">'</span><span class="s1">/api/extras</span><span class="dl">'</span><span class="p">,</span> <span class="p">{</span>
  <span class="na">server</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
  <span class="na">immediate</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
<span class="p">})</span>

<span class="kd">function</span> <span class="nx">openExtraPanel</span><span class="p">()</span> <span class="p">{</span>
  <span class="nx">loadExtras</span><span class="p">()</span>
<span class="p">}</span>
<span class="nt">&lt;/</span><span class="k">script</span><span class="nt">&gt;</span>
</code></pre></div></div>

<p>페이지 API는 첫 화면에 필요하므로 서버에서 그대로 부릅니다. 로그인 확인은 쿠키가 있을 때만 <code class="language-plaintext highlighter-rouge">immediate</code>를 켜서, 세션이 없는 요청에서는 호출이 나가지 않게 했습니다. 설정은 그 값을 쓰는 화면에만 이 호출을 두고, 서버에서는 부르지 않습니다. 부가 UI는 <code class="language-plaintext highlighter-rouge">immediate: false</code>로 두었다가, 패널을 여는 함수에서 <code class="language-plaintext highlighter-rouge">execute</code>를 호출합니다.</p>

<h2 id="정리">정리</h2>

<ul>
  <li>서버 렌더 시점의 호출은 세션 유무와 첫 화면 필요로 나눕니다.</li>
  <li>쿠키가 없으면 로그인 확인을 생략합니다.</li>
  <li>설정은 쓰는 화면의 클라이언트에서만, 부가 UI는 열 때 부릅니다.</li>
  <li>User-Agent 차단만으로는 부족하고, 서버 캐시는 호출을 나누는 일과 같이 씁니다.</li>
</ul>

<p>서버가 페이지를 그리는 시점의 API는, 세션 유무와 첫 화면 필요로 나누려고 합니다.</p>

<h2 id="참고">참고</h2>

<ul>
  <li><a href="https://nuxt.com/docs/3.x/api/composables/use-cookie">Nuxt useCookie</a></li>
  <li><a href="https://nuxt.com/docs/3.x/api/composables/use-fetch">Nuxt useFetch</a></li>
</ul>]]></content><author><name>zeno0505</name></author><category term="일일 회고" /><summary type="html"><![CDATA[서버가 페이지를 그리는 시점에 로그인 확인과 설정 API가 봇 요청에도 같이 나갔습니다. 세션 쿠키 유무와 첫 화면 필요 여부로 호출을 나누기로 했습니다.]]></summary></entry><entry><title type="html">지시문 예시는 내부 칸에 두고 읽을 때 거른다</title><link href="https://zeno0505.github.io/dev-articles/2026/11/16/pin-examples-and-filter/" rel="alternate" type="text/html" title="지시문 예시는 내부 칸에 두고 읽을 때 거른다" /><published>2026-11-16T00:00:00+09:00</published><updated>2026-11-16T00:00:00+09:00</updated><id>https://zeno0505.github.io/dev-articles/2026/11/16/pin-examples-and-filter</id><content type="html" xml:base="https://zeno0505.github.io/dev-articles/2026/11/16/pin-examples-and-filter/"><![CDATA[<p>지시문의 가정 칸에만 두려고 한 문장이, 사용자가 정한 것처럼 보이는 소개 끝에 붙었습니다. 처음에는 한 번 잘못 나온 문장으로 보였는데, 이미 만든 소개가 다음 호출의 문맥에 실려 초안이 그 문장을 따라 쓰며 퍼졌습니다. 그래서 예시의 자리를 내부 칸으로 못박고, 새 소개를 읽는 코드에서 그 문장 패턴을 한 번 더 거르기로 했습니다.</p>

<p>이 글은 생성 모델에 계획 지시문을 주고, 그 출력을 다음 호출의 문맥으로 다시 넣는 분께 도움이 됩니다.</p>

<h2 id="한눈에-보는-결론">한눈에 보는 결론</h2>

<ul>
  <li>제약: 사용자에게 보이는 소개에는 내부 가정 예시가 들어가면 안 되고, 이전 소개가 다음 문맥에 들어가도 그 문장이 다시 살아나면 안 됩니다.</li>
  <li>결정: 지시문에서 예시는 assumptions 같은 내부 칸 전용이라고 못박고, 소개를 펼치는 지시문에도 가정 문장을 넣지 말라고 적었습니다. 그와 별도로, 새로 만든 소개를 읽을 때 그 문장 패턴을 제거합니다. 이미 저장한 글을 고치는 경로에는 이 거르기를 두지 않았습니다.</li>
  <li>확인: 일반 예시로 소개 문자열에 가정 예시 문장을 넣은 뒤 거르기 함수를 돌리면 그 문장은 빠지고 본문은 남았습니다. 고친 뒤에는 새 대화에서 소개를 만들어 저장해 보니, 보이는 소개에 그 가정 문장이 없었습니다.</li>
</ul>

<h2 id="과제와-제약">과제와 제약</h2>

<p>목표는 공개 소개 초안을 만들되, 계획 단계에서만 쓰는 가정이 사용자 화면에 나가지 않게 하는 것이었습니다. 가정 예시는 「가정:」처럼 표시된 짧은 메모가 아니라, 소개 본문처럼 읽히는 완성된 문장이었습니다. 생성 결과를 다음 호출의 문맥으로 다시 넣는 구조라, 한 번 섞인 문장은 다음 초안의 재료가 됩니다. 지시문에서 예시를 없애 버리면 모델이 내부 칸을 어떻게 채울지 보기 어려워, 예시는 남기되 자리가 분명해야 했습니다.</p>

<h2 id="어떤-방법을-골랐는지">어떤 방법을 골랐는지</h2>

<p>지시문만 고쳐서 「예시는 복사하지 말라」고 적는 방법은, 이미 섞여 나온 문장이 다음 문맥에 남아 있으면 다시 따라 쓰일 수 있습니다. 반대로 읽는 쪽에서만 거르면, 같은 뜻의 문장이 조금 다른 표기로 나올 때 빠지지 않을 수 있고, 모델은 여전히 소개 칸에 그 문장을 쓰려 합니다. 그래서 계획 지시문에서 예시의 자리를 내부 칸으로 못박고, 소개를 펼치는 지시문에도 가정이나 설명을 넣지 말라고 적었습니다. 그와 별도로, 새로 만든 소개를 읽는 코드에서 그 패턴을 거르는 두 겹을 두었습니다.</p>

<h2 id="기본-구조">기본 구조</h2>

<p>생성 한 번의 출력은 끝이 아닙니다. 그 출력이 다음 호출의 문맥으로 들어가면, 잘못된 문장도 다음 초안의 입력이 됩니다.</p>

<p><img src="/dev-articles/assets/2026-11-16-pin-examples-and-filter-01.png" alt="계획 지시문의 가정 예시가 소개에 섞인 뒤, 다음 문맥으로 다시 들어가 퍼지는 흐름과, 내부 칸 고정과 읽기 거르기로 끊는 구조" /></p>

<p>실제 고친 모양은, 지시문에서 예시가 들어갈 칸을 명시하고, 새로 만든 소개를 읽을 때 그 예시 문장을 빼는 쪽입니다. 아래는 그 구조를 일반 예시로 옮긴 코드입니다. 제품 지시문 원문이나 제품 거르기 코드가 아닙니다.</p>

<div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">const</span> <span class="nx">PLAN_PROMPT</span> <span class="o">=</span> <span class="s2">`당신은 공개 소개 초안을 만듭니다.
assumptions 칸에는 내부 가정만 적습니다. 이 칸의 문장은 사용자에게 보여 주지 않습니다.
description 칸에는 사용자에게 보일 문장만 적습니다.

assumptions 예시(내부 전용, description에 복사하지 말 것):
- 따로 고르지 않아 매달 이어지는 요금제로 두었습니다.

출력 형식:
{"assumptions":["..."],"description":"..."}`</span>

<span class="kd">const</span> <span class="nx">DRAFT_PROMPT</span> <span class="o">=</span> <span class="s2">`소개는 사용자에게 보이는 글입니다. 가정이나 설명 문장은 넣지 않습니다.`</span>

<span class="kd">function</span> <span class="nx">looksLikeAssumptionExample</span><span class="p">(</span><span class="nx">sentence</span><span class="p">)</span> <span class="p">{</span>
  <span class="kd">const</span> <span class="nx">unsaid</span> <span class="o">=</span> <span class="sr">/따로 고르지 않아|별도로 정하지 않아/</span>
  <span class="kd">const</span> <span class="nx">decided</span> <span class="o">=</span> <span class="sr">/두었습니다|정했습니다/</span>
  <span class="k">return</span> <span class="nx">unsaid</span><span class="p">.</span><span class="nx">test</span><span class="p">(</span><span class="nx">sentence</span><span class="p">)</span> <span class="o">&amp;&amp;</span> <span class="nx">decided</span><span class="p">.</span><span class="nx">test</span><span class="p">(</span><span class="nx">sentence</span><span class="p">)</span>
<span class="p">}</span>

<span class="k">export</span> <span class="kd">function</span> <span class="nx">stripAssumptionExamples</span><span class="p">(</span><span class="nx">text</span><span class="p">)</span> <span class="p">{</span>
  <span class="k">return</span> <span class="nx">text</span>
    <span class="p">.</span><span class="nx">split</span><span class="p">(</span><span class="sr">/</span><span class="se">(?&lt;</span><span class="sr">=다</span><span class="se">\.)\s</span><span class="sr">*/</span><span class="p">)</span>
    <span class="p">.</span><span class="nx">filter</span><span class="p">((</span><span class="nx">sentence</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="nx">sentence</span> <span class="o">&amp;&amp;</span> <span class="o">!</span><span class="nx">looksLikeAssumptionExample</span><span class="p">(</span><span class="nx">sentence</span><span class="p">))</span>
    <span class="p">.</span><span class="nx">join</span><span class="p">(</span><span class="dl">'</span><span class="s1"> </span><span class="dl">'</span><span class="p">)</span>
    <span class="p">.</span><span class="nx">trim</span><span class="p">()</span>
<span class="p">}</span>

<span class="k">export</span> <span class="kd">function</span> <span class="nx">parseNewDraft</span><span class="p">(</span><span class="nx">raw</span><span class="p">)</span> <span class="p">{</span>
  <span class="kd">const</span> <span class="nx">data</span> <span class="o">=</span> <span class="nx">JSON</span><span class="p">.</span><span class="nx">parse</span><span class="p">(</span><span class="nx">raw</span><span class="p">)</span>
  <span class="k">return</span> <span class="p">{</span>
    <span class="na">assumptions</span><span class="p">:</span> <span class="nx">data</span><span class="p">.</span><span class="nx">assumptions</span> <span class="o">??</span> <span class="p">[],</span>
    <span class="na">description</span><span class="p">:</span> <span class="nx">stripAssumptionExamples</span><span class="p">(</span><span class="nb">String</span><span class="p">(</span><span class="nx">data</span><span class="p">.</span><span class="nx">description</span> <span class="o">??</span> <span class="dl">''</span><span class="p">)),</span>
  <span class="p">}</span>
<span class="p">}</span>
</code></pre></div></div>

<p><code class="language-plaintext highlighter-rouge">parseNewDraft</code>는 새로 만든 소개를 읽을 때 씁니다. 이미 저장한 글을 고치는 경로에는 이 거르기를 두지 않았습니다.</p>

<h2 id="섞인-뒤-막기까지">섞인 뒤 막기까지</h2>

<h3 id="처음-판단-한-번-어긋난-출력">처음 판단: 한 번 어긋난 출력</h3>

<p>공개 소개를 만드는 계획 호출을 돌리다가, 지시문에 적어 둔 가정 예시가 소개 끝에 붙은 것을 봤습니다. 그 문장은 소개 본문처럼 읽혀, 처음에는 그 한 번의 출력이 어긋난 것으로 봤습니다.</p>

<h3 id="다음-문맥을-타고-번진-예시-문장">다음 문맥을 타고 번진 예시 문장</h3>

<p>그 문장은 소개를 펼치는 단계에서 먼저 나왔고, 처음 출처는 계획 지시문의 가정 예시였습니다. 이미 만든 소개가 다음 호출의 문맥에 같이 실렸고, 다음 초안이 그 문장을 따라 쓰며 여러 결과에 퍼졌습니다. 출력만 한 번 고치면 끝날 문제가 아니었습니다. 문맥으로 다시 들어가는 입력을 같이 손봐야 했습니다.</p>

<h3 id="내부-칸-고정과-읽기-단계-거르기">내부 칸 고정과 읽기 단계 거르기</h3>

<p>계획 지시문에서 가정 예시는 내부 칸 전용이라고 못박아, 소개 칸에 복사하지 말라고 적었습니다. 소개를 펼치는 지시문에도, 소개는 사용자에게 보이는 글이니 가정이나 설명을 넣지 말라고 적었습니다. 그와 별도로, 새로 만든 소개를 읽는 코드에서 「사용자가 고르지 않았다」는 말과 「그래서 이렇게 두었다」는 말이 한 문장에 같이 있는 패턴을 제거했습니다. 지시문이 어긋나도 화면에 나가기 전에 한 번 더 걸리게 하려는 선택이었습니다.</p>

<h2 id="예시가-출력으로-번지는-이유">예시가 출력으로 번지는 이유</h2>

<p>모델은 지시문의 규칙만 따르는 것이 아니라, 옆에 적어 둔 예시의 모양을 패턴으로 집어 다음 출력에 적용합니다. OpenAI 공식 문서의 few-shot 절은, 입력과 출력 예시를 프롬프트에 몇 개 넣으면 모델을 새 작업 쪽으로 이끌 수 있고, 모델이 그 예시에서 패턴을 스스로 집어 프롬프트에 적용한다고 적습니다. Brown 등의 논문도, 가중치를 바꾸지 않은 채 문맥에 과제 예시를 몇 개 보여 주면 모델이 그 다음 입력을 같은 방식으로 이어서 쓴다고 설명합니다.</p>

<p>그래서 가정 칸을 채우는 법이 궁금하다고 소개처럼 읽히는 예시를 지시문에 두면, 그 문장 자체가 소개 칸의 재료가 될 수 있습니다. 이미 나온 소개를 다음 문맥에 다시 넣으면, 한 번 섞인 문장은 다음 초안이 따라 쓸 예시가 됩니다. 지시문에 「복사하지 말라」고만 적어서는, 이 두 번째 입력을 막기 어렵습니다.</p>

<h2 id="스키마로-칸을-나누는-방법과-비교">스키마로 칸을 나누는 방법과 비교</h2>

<p>칸을 더 단단히 나누는 방법으로는, 모델이 JSON 스키마를 지키게 하는 structured output이 있습니다. OpenAI 문서는 structured output이 거절하지 않고 끝까지 만든 출력을, 넘겨 준 JSON 스키마에 맞추어 제한한다고 적습니다. JSON 모드만 켜면 유효한 JSON이 나온다는 점은 같지만, 스키마를 지킨다는 보장은 structured output에만 있습니다. 같은 문서는, 스키마가 담지 못한 업무 규칙은 응용 쪽에서 따로 검사해야 한다고도 적습니다.</p>

<p>이 일을 structured output만으로 맡기면, assumptions와 description이 다른 칸으로 나뉘는 쪽은 좋아질 수 있습니다. 다만 description이 문자열인 이상, 스키마는 그 칸에 어떤 문장이 들어가도 형식이 맞으면 통과시킵니다. 가정 예시가 소개 문장으로 들어가는 일은 스키마가 담지 못한 규칙이라, 칸을 나눈 뒤에도 소개를 읽는 쪽에서 그 패턴을 검사해야 합니다. 그래서 지금은 지시문에서 자리를 못박고, 새로 만든 소개를 읽을 때 거르는 두 겹을 두었습니다. structured output은 칸을 나누는 장치를 더할 때 다시 보면 됩니다.</p>

<h2 id="한계">한계</h2>

<p>거르기는 「고르지 않았다」와 「두었다」가 한 문장에 같이 있는 패턴만 빼므로, 표현이 조금만 바뀌면 남을 수 있습니다. 지시문에서 자리를 못박는 일은 모델이 칸을 지키게 돕는 장치이지, 출력을 보증하지는 않습니다. 이미 저장한 글을 고치는 경로에는 이 거르기를 두지 않았으므로, 예전에 섞여 들어간 문장은 그 경로만으로는 빠지지 않습니다. 위 코드의 예시 문장과 거르기 결과는 일반 예시입니다.</p>

<h2 id="확인-방법">확인 방법</h2>

<p>지시문에 적어 둔 예시 문장이 소개 문자열에 들어간 입력을 만들고, <code class="language-plaintext highlighter-rouge">parseNewDraft</code>를 돌린 뒤 description에 그 문장이 없는지 봅니다. 같은 함수에 본문만 있는 입력을 넣으면 본문은 그대로 남아야 합니다. 실제 생성 흐름에서는 고친 뒤 새 대화에서 소개를 만들어 저장하고, 보이는 소개에 그 가정 문장이 다시 나타나는지를 봅니다.</p>

<p>일반 예시로 확인한 결과는 아래와 같습니다.</p>

<div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">const</span> <span class="nx">leaked</span> <span class="o">=</span> <span class="nx">JSON</span><span class="p">.</span><span class="nx">stringify</span><span class="p">({</span>
  <span class="na">assumptions</span><span class="p">:</span> <span class="p">[</span><span class="dl">'</span><span class="s1">공개 전에 요금제를 확인한다</span><span class="dl">'</span><span class="p">],</span>
  <span class="na">description</span><span class="p">:</span>
    <span class="dl">'</span><span class="s1">이번 달 혜택을 소개합니다. 따로 고르지 않아 매달 이어지는 요금제로 두었습니다.</span><span class="dl">'</span><span class="p">,</span>
<span class="p">})</span>

<span class="kd">const</span> <span class="nx">parsed</span> <span class="o">=</span> <span class="nx">parseNewDraft</span><span class="p">(</span><span class="nx">leaked</span><span class="p">)</span>
<span class="c1">// parsed.description === '이번 달 혜택을 소개합니다.'</span>
</code></pre></div></div>

<p>저는 예시 문장이 한 번 새어 나온 것만 고치면 된다고 먼저 봤습니다. 다시 보니 문제는 그 출력이 다음 호출의 문맥으로 들어가 초안이 따라 쓰는 쪽이었습니다. 지시문에서 자리를 못박고 새 소개를 읽는 쪽에서 같은 문장 패턴을 거른 뒤에는, 일반 예시와 새 대화에서 만든 소개 모두에서 그 예시가 빠졌습니다.</p>

<h2 id="정리">정리</h2>

<ul>
  <li>지시문 예시는 출력으로 번질 수 있고, 다음 문맥에 들어가면 따라 퍼집니다.</li>
  <li>예시의 자리는 내부 칸으로 못박고, 소개를 펼치는 지시문에도 가정을 넣지 말라고 적습니다.</li>
  <li>새로 만든 소개를 읽을 때 그 문장 패턴을 한 번 더 거릅니다.</li>
</ul>

<p>지시문 예시는 내부 칸에 두고, 공개 글을 읽을 때 한 번 더 거르려고 합니다.</p>

<h2 id="참고">참고</h2>

<ul>
  <li><a href="https://developers.openai.com/api/docs/guides/prompt-engineering">OpenAI, Prompt engineering — Few-shot learning</a></li>
  <li><a href="https://arxiv.org/abs/2005.14165">Brown et al., Language Models are Few-Shot Learners</a></li>
  <li><a href="https://developers.openai.com/api/docs/guides/structured-outputs">OpenAI, Structured model outputs</a></li>
  <li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse">MDN, JSON.parse</a></li>
</ul>]]></content><author><name>zeno0505</name></author><category term="일일 회고" /><summary type="html"><![CDATA[계획 지시문의 가정 예시가 사용자에게 보이는 소개에 섞여 다음 초안에 따라 퍼졌습니다. 예시 자리를 내부 칸으로 못박고, 새 소개를 읽는 코드에서 그 문장 패턴을 거르기로 했습니다.]]></summary></entry><entry><title type="html">정확성 때문에 버린 최적화는 다시 잰다</title><link href="https://zeno0505.github.io/dev-articles/2026/11/13/remeasure-discarded-optimization/" rel="alternate" type="text/html" title="정확성 때문에 버린 최적화는 다시 잰다" /><published>2026-11-13T00:00:00+09:00</published><updated>2026-11-13T00:00:00+09:00</updated><id>https://zeno0505.github.io/dev-articles/2026/11/13/remeasure-discarded-optimization</id><content type="html" xml:base="https://zeno0505.github.io/dev-articles/2026/11/13/remeasure-discarded-optimization/"><![CDATA[<p>예전에 정확성 때문에 쓰지 않았던 직렬화 방식을, 입력 한 자가 무거워져 다시 써 봤습니다. 편집 문서 안에서 저장용 HTML을 만들면 쌓여 있는 Range를 브라우저가 같이 다루느라 입력이 밀릴 수 있어, document.implementation.createHTMLDocument로 분리된 문서를 만들고 그쪽에서 읽기로 했습니다. 처음 에디터를 만들 때 이 방법을 사용하지 않았던 이유는, 저장되는 문자열이 달라질 수 있다고 봤기 때문입니다. 다시 넣어 보니 입력 한 자의 멈춤은 줄었고, 그래서 문자열이 실제로 갈리는지부터 나눠 재기로 했습니다.</p>

<p>이 글은 에디터에서 저장용 HTML을 만드는 비용이 입력을 밀 때, 분리된 문서에서 직렬화해도 되는지를 가려야 하는 분께 도움이 됩니다.</p>

<h2 id="한눈에-보는-결론">한눈에 보는 결론</h2>

<ul>
  <li>제약: 저장 문자열과 미리보기·발행 결과가 조용히 바뀌면 안 됩니다.</li>
  <li>결정: 분리된 문서에서 innerHTML처럼 속성 그대로 읽는 경로인지를 확인한 뒤에 다시 씁니다.</li>
  <li>확인: innerHTML은 두 문서에서 같았고, href·src 프로퍼티와 XMLSerializer만 갈렸습니다. 실험용 페이지에서 단락 350개와 Range 8만 개 기준 중앙값은 3ms와 0.2ms였고, 입력 한 자의 멈춤이 줄어드는 것도 확인했습니다.</li>
</ul>

<h2 id="과제와-제약">과제와 제약</h2>

<p>목표는 글 쓰는 화면에서 입력 한 자가 멈추는 시간을 줄이되, 저장한 HTML을 다시 열었을 때 화면과 문자열이 이전과 같게 두는 것입니다. 직렬화 비용을 피하는 일과, 저장 결과가 같은지는 다른 축이라, 속도만 보고 넣을 수는 없었습니다.</p>

<h2 id="제약에-맞춰-고른-방법">제약에 맞춰 고른 방법</h2>

<p>선택지는 세 가지였습니다. 편집 문서에서 계속 직렬화하면 저장 결과는 그대로지만, Range가 쌓일수록 입력은 무거워질 수 있습니다. 분리된 문서에서 읽되 출력 비교를 생략하면 속도는 나지만, 저장된 HTML이 바뀌면 미리보기와 발행에 구멍이 납니다. 그래서 분리된 문서에서 만들되, 저장 결과가 같은 경로인지를 확인하고 쓰는 쪽을 택했습니다.</p>

<p>이 방법을 계속 쓰지 않는 편과, 체감만 보고 넣는 편은 쓰지 않기로 했습니다.</p>

<h2 id="기본-구조">기본 구조</h2>

<p>Tiptap의 getHTML은 편집 중인 문서를 HTML로 돌려 줍니다. 그 아래의 ProseMirror DOMSerializer.serializeFragment는 document 옵션을 받을 수 있고, 공식 문서는 브라우저가 아닐 때 노드를 만들 문서를 넘기라고 적습니다. createHTMLDocument가 만드는 문서는 지금 페이지와 분리되어 있고, 기준 주소는 about:blank입니다.</p>

<p><img src="/dev-articles/assets/2026-11-13-remeasure-discarded-optimization-01.png" alt="저장 HTML은 읽기 방법에 따라 갈릴 수 있다" /></p>

<p>실제 고친 모양은, 분리된 문서에서 노드를 옮긴 뒤 innerHTML로만 읽는 함수입니다. href나 src 프로퍼티를 속성에 다시 쓰지 않습니다.</p>

<div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">function</span> <span class="nx">serializeForSave</span><span class="p">(</span><span class="nx">source</span><span class="p">)</span> <span class="p">{</span>
  <span class="kd">const</span> <span class="nx">detached</span> <span class="o">=</span> <span class="nb">document</span><span class="p">.</span><span class="nx">implementation</span><span class="p">.</span><span class="nx">createHTMLDocument</span><span class="p">(</span><span class="dl">''</span><span class="p">)</span>
  <span class="kd">const</span> <span class="nx">wrap</span> <span class="o">=</span> <span class="nx">detached</span><span class="p">.</span><span class="nx">createElement</span><span class="p">(</span><span class="dl">'</span><span class="s1">div</span><span class="dl">'</span><span class="p">)</span>
  <span class="nx">wrap</span><span class="p">.</span><span class="nx">appendChild</span><span class="p">(</span><span class="nx">detached</span><span class="p">.</span><span class="nx">importNode</span><span class="p">(</span><span class="nx">source</span><span class="p">,</span> <span class="kc">true</span><span class="p">))</span>
  <span class="k">return</span> <span class="nx">wrap</span><span class="p">.</span><span class="nx">innerHTML</span>
<span class="p">}</span>
</code></pre></div></div>

<p>같은 마크업을 편집 문서와 분리된 문서에서 innerHTML로 읽으면 문자열이 같았습니다. href와 src 프로퍼티를 속성에 다시 쓰면 편집 문서에서는 <code class="language-plaintext highlighter-rouge">https://example.com/about</code>처럼 풀리고, 분리된 문서에서는 <code class="language-plaintext highlighter-rouge">/about</code>으로 남았습니다. XMLSerializer로 <code class="language-plaintext highlighter-rouge">br</code>을 읽으면 두 문서 모두 <code class="language-plaintext highlighter-rouge">&lt;br xmlns="http://www.w3.org/1999/xhtml" /&gt;</code>가 되고, outerHTML은 <code class="language-plaintext highlighter-rouge">&lt;br&gt;</code>입니다.</p>

<h2 id="다시-넣기까지">다시 넣기까지</h2>

<h3 id="예전에-이-방법을-사용하지-않았던-이유">예전에 이 방법을 사용하지 않았던 이유</h3>

<p>처음 에디터를 만들 때는, 분리된 문서에서 읽으면 저장 문자열이 달라질 수 있다고 보고 이 방식을 버렸습니다. 정확성을 지키려는 선택이었습니다.</p>

<h3 id="다시-넣은-뒤-가벼워진-입력">다시 넣은 뒤 가벼워진 입력</h3>

<p>입력 한 자가 무거워져, 예전에 버린 방식을 다시 넣었습니다. 속도가 나을 거라고 봤고, 실제로 입력 한 자의 멈춤은 줄었습니다.</p>

<h3 id="읽기-경로에-따라-갈린-저장-문자열">읽기 경로에 따라 갈린 저장 문자열</h3>

<p>그래서 버린 이유가 지금도 같은지 다시 쟀습니다. innerHTML처럼 속성 그대로 읽는 경로는 두 문서에서 같았고, 갈린 것은 확인된 읽기 방법뿐이었습니다. 같은 경로를 확인한 뒤에야 이 방식을 다시 쓸 수 있다고 봤습니다.</p>

<h2 id="한계">한계</h2>

<p>분리된 문서의 기준 주소는 about:blank라, 상대 주소를 프로퍼티로 풀어 저장하면 결과가 갈립니다. XMLSerializer는 HTML이 아니라 XML 표기를 돌려 주므로, outerHTML이나 innerHTML과 같은 문자열이라고 보면 안 됩니다.</p>

<h2 id="확인-방법">확인 방법</h2>

<p>굵게, 기울임, 링크, 이미지, 목록처럼 실제로 쓰는 서식을 한 번씩 넣고, 저장한 뒤 다시 열었을 때 화면과 문자열이 같은지 봅니다. href·src를 절대 주소로 풀어 쓰거나 XMLSerializer로 저장하는 경로가 있으면 그 차이까지 대조합니다. 그리고 한 자 입력으로 멈춤이 줄었는지를 같이 봅니다.</p>

<p>저는 입력 한 자의 멈춤이 줄어든 것만으로 다시 쓰기로 결정하지 않았습니다. 예전에 버린 이유가 저장 문자열이 달라질 수 있다는 점이었고, 다시 재어 보니 innerHTML은 같았으며, 갈린 것은 href·src 프로퍼티와 XMLSerializer뿐이었습니다. 저장 문자열이 같은지 먼저 확인했고, 직접 입력해 보는 테스트에서도 UX 문제는 없었습니다.</p>

<h2 id="정리">정리</h2>

<ul>
  <li>분리된 문서에서 innerHTML로 읽으면 편집 문서와 같았습니다.</li>
  <li>href·src 프로퍼티와 XMLSerializer는 갈리므로, 그 경로인지를 먼저 가릅니다.</li>
  <li>속도만 보고 다시 넣지는 않습니다.</li>
</ul>

<p>정확성 때문에 버린 최적화는, 버린 이유와 지금 출력부터 다시 재려고 합니다.</p>

<h2 id="참고">참고</h2>

<ul>
  <li><a href="https://tiptap.dev/docs/editor/api/editor">Tiptap Editor#getHTML</a></li>
  <li><a href="https://prosemirror.net/docs/ref/#model.DOMSerializer.serializeFragment">ProseMirror DOMSerializer.serializeFragment</a></li>
  <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/DOMImplementation/createHTMLDocument">MDN createHTMLDocument</a></li>
</ul>]]></content><author><name>zeno0505</name></author><category term="일일 회고" /><summary type="html"><![CDATA[정확성 때문에 버린 분리 문서 직렬화를 다시 넣었더니, innerHTML은 같고 href·src와 XMLSerializer만 갈렸습니다.]]></summary></entry><entry><title type="html">부모 창에 건 리스너는 pagehide에서 푼다</title><link href="https://zeno0505.github.io/dev-articles/2026/11/10/close-with-record/" rel="alternate" type="text/html" title="부모 창에 건 리스너는 pagehide에서 푼다" /><published>2026-11-10T00:00:00+09:00</published><updated>2026-11-10T00:00:00+09:00</updated><id>https://zeno0505.github.io/dev-articles/2026/11/10/close-with-record</id><content type="html" xml:base="https://zeno0505.github.io/dev-articles/2026/11/10/close-with-record/"><![CDATA[<p>프레임을 여닫을수록 부모 창의 메모리가 내려가지 않았습니다. 성능을 보려고 iframe 안의 앱이 부모 창에 긴 작업 관측기를 걸었고, 프레임을 걷으면 Vue의 onUnmounted가 그 구독을 풀어 줄 거라고 봤습니다. 부모 창에 건 관측기가 끊기지 않아 iframe 앱이 통째로 남는 쪽이었습니다. 그래서 정리 훅만 믿지 않고, 문서가 숨는 pagehide에서도 같은 정리를 걸어 다시 여닫았습니다. 그때는 메모리가 평평했습니다.</p>

<p>이 글은 iframe 안의 앱이 부모 창에 리스너나 관측기를 걸 때, 프레임을 여닫은 뒤 메모리가 내려가지 않는 분께 도움이 됩니다.</p>

<h2 id="과제와-제약">과제와 제약</h2>

<p>목표는 부모 창에 건 구독을, 프레임이 사라질 때도 남기지 않는 것입니다. 제약은 세 가지였습니다. 부모 쪽이 요소만 제거할 수 있고, 구독은 iframe 문서가 아니라 부모 창에 남으며, 탭만 옮긴 것처럼 잠시 숨는 일과 문서가 사라지는 일을 같은 훅으로 다루면 안 됩니다.</p>

<h2 id="한눈에-보는-결론">한눈에 보는 결론</h2>

<ul>
  <li>부모 쪽이 iframe 요소만 제거하면 onUnmounted는 호출되지 않았습니다.</li>
  <li>이 Chrome에서는 pagehide가 왔고 persisted는 false였으며, unload는 없었습니다.</li>
  <li>콜백이 실행되지 않아도 리스너는 부모 창에 남아 힙을 밀어 올렸습니다.</li>
  <li>cleanup은 한 번만 실행되게 가드를 두고, onUnmounted와 pagehide에 같이 걸었습니다.</li>
</ul>

<h2 id="제약에-맞춰-고른-방법">제약에 맞춰 고른 방법</h2>

<p>정리 훅만 두면, 부모 쪽이 요소만 제거할 때 호출되지 않습니다. pagehide만 두면, iframe은 남겨 둔 채 Vue만 언마운트할 때 이벤트가 오지 않아 리스너가 남고 probe에도 계속 응답했습니다. unload는 이 Chrome에서 iframe 제거 때 이벤트 자체가 없었고, 공식 문서도 쓰지 말라고 합니다. visibilitychange는 제거 순간에도 hidden으로 오지만, 탭만 옮겨도 같은 이벤트가 와 구독이 풀리고 다시 돌아와도 복구되지 않았습니다.</p>

<p>그래서 cleanup은 한 번만 실행되게 가드를 두고, onUnmounted와 pagehide에 같이 걸었습니다. 부모 문서가 제거 전에 unmount를 반드시 부르게 하는 방법은, 부모를 우리가 통제할 때는 확실합니다. 다만 부모 쪽이 요소만 빼는 경우가 있어, 정리의 주된 위치는 iframe 문서의 수명에 두기로 했습니다.</p>

<h2 id="기본-구조">기본 구조</h2>

<p><img src="/dev-articles/assets/2026-11-10-close-with-record-01.png" alt="부모 창 구독은 두 종료 경로에서 같이 푼다" /></p>

<p>Vue의 onUnmounted는 컴포넌트가 언마운트된 뒤에 수동으로 만든 타이머나 DOM 리스너를 지우라고 되어 있습니다. 그 훅은 Vue가 컴포넌트 트리를 내릴 때 호출됩니다. WHATWG HTML은 iframe 제거를 자식 탐색 가능 객체를 파괴하는 일로 적고, 내용 문서는 unload되지 않고 파괴되며 unload 이벤트도 발생하지 않는다고 밝힙니다. 같은 Chrome에서는 같은 출처 iframe을 제거하는 순간에 pagehide와 visibilitychange는 동기적으로 발생했습니다.</p>

<p>실제 고친 모양은, 부모 창 구독을 연결하는 함수와, 한 번만 도는 정리 함수를 훅과 pagehide에 같이 거는 쪽입니다.</p>

<div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">import</span> <span class="p">{</span> <span class="nx">onMounted</span><span class="p">,</span> <span class="nx">onUnmounted</span> <span class="p">}</span> <span class="k">from</span> <span class="dl">'</span><span class="s1">vue</span><span class="dl">'</span>

<span class="k">export</span> <span class="kd">function</span> <span class="nx">useParentSubscription</span><span class="p">(</span><span class="nx">connect</span><span class="p">)</span> <span class="p">{</span>
  <span class="kd">let</span> <span class="nx">disconnect</span> <span class="o">=</span> <span class="p">()</span> <span class="o">=&gt;</span> <span class="p">{}</span>
  <span class="kd">let</span> <span class="nx">cleaned</span> <span class="o">=</span> <span class="kc">false</span>
  <span class="kd">const</span> <span class="nx">cleanup</span> <span class="o">=</span> <span class="p">()</span> <span class="o">=&gt;</span> <span class="p">{</span>
    <span class="k">if</span> <span class="p">(</span><span class="nx">cleaned</span><span class="p">)</span> <span class="k">return</span>
    <span class="nx">cleaned</span> <span class="o">=</span> <span class="kc">true</span>
    <span class="nx">disconnect</span><span class="p">()</span>
    <span class="nb">window</span><span class="p">.</span><span class="nx">removeEventListener</span><span class="p">(</span><span class="dl">'</span><span class="s1">pagehide</span><span class="dl">'</span><span class="p">,</span> <span class="nx">cleanup</span><span class="p">)</span>
  <span class="p">}</span>

  <span class="nx">onMounted</span><span class="p">(()</span> <span class="o">=&gt;</span> <span class="p">{</span>
    <span class="nx">disconnect</span> <span class="o">=</span> <span class="nx">connect</span><span class="p">(</span><span class="nb">window</span><span class="p">.</span><span class="nx">parent</span><span class="p">)</span>
  <span class="p">})</span>
  <span class="nx">onUnmounted</span><span class="p">(</span><span class="nx">cleanup</span><span class="p">)</span>
  <span class="nb">window</span><span class="p">.</span><span class="nx">addEventListener</span><span class="p">(</span><span class="dl">'</span><span class="s1">pagehide</span><span class="dl">'</span><span class="p">,</span> <span class="nx">cleanup</span><span class="p">)</span>

  <span class="k">return</span> <span class="nx">cleanup</span>
<span class="p">}</span>
</code></pre></div></div>

<p><code class="language-plaintext highlighter-rouge">connect</code>는 부모 창에 addEventListener나 MutationObserver를 걸고, 푸는 함수를 돌려 주면 됩니다.</p>

<h2 id="여닫이에서-본-것">여닫이에서 본 것</h2>

<h3 id="처음-판단-정리-훅이-구독을-풀어-줄-것">처음 판단: 정리 훅이 구독을 풀어 줄 것</h3>

<p>성능을 보려고 부모 창에 관측기를 걸었고, 프레임을 걷으면 정리 훅이 구독을 풀어 줄 거라고 봤습니다. 여닫을수록 메모리는 내려가지 않았고, 부모 창에 건 관측기가 끊기지 않아 iframe 앱이 통째로 남았습니다.</p>

<h3 id="pagehide에도-둔-정리와-평평해진-메모리">pagehide에도 둔 정리와 평평해진 메모리</h3>

<p>그래서 문서가 숨는 pagehide에서도 같은 정리를 걸어 다시 여닫았습니다. 그때는 메모리가 평평했습니다.</p>

<h3 id="울리지-않는-콜백과-남아-있는-리스너">울리지 않는 콜백과 남아 있는 리스너</h3>

<p>같은 상황을 일반 예시로 다시 재어 보니, 문제는 콜백이 계속 울리는 쪽이 아니었습니다. Headless Chrome 157에서 정리 훅에만 cleanup을 두고 iframe을 제거하자, 기록은 onMounted, pagehide, visibilitychange까지였고 onBeforeUnmount와 onUnmounted, unload는 없었습니다. 부모 창에 probe를 다시 보내도 콜백은 이미 실행되지 않았지만, 개발자 도구로 세어 보면 probe 리스너는 그대로 남아 있었습니다. 같은 여닫기를 12번 반복하면 부모 창에 리스너가 12개 남고, 힙은 0.6MB에서 102.6MB까지 올랐습니다. 같은 정리 함수를 pagehide에서도 부르면, 제거 직후 리스너는 0개였고 12번을 반복한 뒤에도 힙은 약 1MB에서 평평했습니다.</p>

<h2 id="한계">한계</h2>

<p>pagehide도 항상 온다고 보기는 어렵습니다. 모바일에서 다른 앱으로 나갔다가 브라우저를 종료하면 이 이벤트가 오지 않을 수 있고, 명세는 iframe 제거를 언로드가 아니라 파괴로 적습니다. 지금 확인한 것은 이 Chrome에서 같은 출처 iframe을 제거할 때 pagehide가 호출된다는 점입니다. 그 한계를 전제로, 문서가 숨는 신호와 프레임워크 훅을 같이 두는 쪽을 택했습니다.</p>

<h2 id="확인-방법">확인 방법</h2>

<p>부모 창에서 같은 이벤트를 다시 보내 콜백이 실행되는지를 봅니다. 이미 파괴된 문서에서 온 리스너는 실행되지 않으면서도 부모 창에 남아 있을 수 있어, 개발자 도구의 getEventListeners로 남은 개수를 같이 셉니다. 프레임을 여러 번 여닫은 뒤 가비지 컬렉션을 유도하고 힙이 평평한지 봅니다. iframe을 남겨 둔 채 app.unmount()만 호출하는 경로도 같이 봅니다. 이때는 onUnmounted가 돌고 pagehide는 오지 않아야 하며, 그 경로에서도 리스너 개수가 0이 되어야 합니다.</p>

<p>저는 정리 훅이 부모 창 구독까지 풀어 줄 거라고 보고 관측기를 걸었습니다. 다시 재어 보니 훅은 돌지 않았고, 실행되지 않는 리스너가 부모 창에 남아 힙을 밀어 올렸습니다. pagehide에 같은 정리를 두자 리스너 개수와 힙이 같이 가라앉았습니다.</p>

<h2 id="정리">정리</h2>

<ul>
  <li>프레임 제거는 Vue 언마운트가 아닙니다.</li>
  <li>콜백이 안 울리는지만 보면 누수를 놓칩니다.</li>
  <li>정리 훅과 pagehide를 한 함수로 맞춥니다.</li>
</ul>

<p>부모 창에 건 구독은, 프레임워크 훅과 문서가 숨는 이벤트를 같이 두고 풀려고 합니다.</p>

<h2 id="참고">참고</h2>

<ul>
  <li><a href="https://vuejs.org/api/composition-api-lifecycle.html#onunmounted">Vue onUnmounted</a></li>
  <li><a href="https://html.spec.whatwg.org/multipage/iframe-embed-object.html#the-iframe-element">WHATWG HTML, iframe 제거 절차</a></li>
  <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/Window/pagehide_event">MDN pagehide</a></li>
  <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/Window/unload_event">MDN unload</a></li>
</ul>]]></content><author><name>zeno0505</name></author><category term="일일 회고" /><summary type="html"><![CDATA[iframe을 걷을 때 Vue 정리 훅은 안 돌고 부모 창 리스너는 남아, pagehide에서도 같은 정리를 걸었습니다.]]></summary></entry><entry><title type="html">숨은 iframe preload는 기기 조건을 보고 켠다</title><link href="https://zeno0505.github.io/dev-articles/2026/11/05/prework-when-to-connect/" rel="alternate" type="text/html" title="숨은 iframe preload는 기기 조건을 보고 켠다" /><published>2026-11-05T00:00:00+09:00</published><updated>2026-11-05T00:00:00+09:00</updated><id>https://zeno0505.github.io/dev-articles/2026/11/05/prework-when-to-connect</id><content type="html" xml:base="https://zeno0505.github.io/dev-articles/2026/11/05/prework-when-to-connect/"><![CDATA[<p>빠른 경로를 만들려고 켠 미리 불러오기가, 느린 기기에서는 첫 화면을 무겁게 만들 수 있습니다. 업로드 창이 늦게 열려 숨은 iframe을 처음부터 불러 두면 여는 순간을 줄일 수 있다고 봤고, 빠른 기기에서는 그 방법이 맞아 보였습니다. 다만 사양이 낮은 기기에서는 같은 방식이 페이지를 불러오는 동안 렉을 만들 수 있어, 그 기기에서는 미리 불러오지 않게 바꾸고 불필요한 스크립트도 빼 두었습니다.</p>

<p>이 글은 숨은 iframe으로 패널을 미리 불러오려 할 때, 저사양에서 첫 화면이 버벅일 수 있는지부터 가려야 하는 분께 도움이 됩니다.</p>

<h2 id="한눈에-보는-결론">한눈에 보는 결론</h2>

<ul>
  <li>display:none이어도 문서와 스크립트는 불러져 실행됩니다.</li>
  <li>실험실에서 첫 페인트는 거의 그대로였고, 비용은 긴 작업으로 나타났습니다. 같은 분량의 일을 CPU 8배속에서 재면 긴 작업 총합 중앙값은 280ms에서 2,424ms로 늘었습니다.</li>
  <li>saveData, 메모리, 논리 프로세서 수를 보고, 값이 없거나 낮으면 켜지 않습니다.</li>
  <li>저사양 기기에서는 미리 불러오지 않게 바꾸고, 불필요한 스크립트도 빼 두었습니다.</li>
</ul>

<h2 id="제약에-맞춰-고른-방법">제약에 맞춰 고른 방법</h2>

<p>목표는 업로드 창을 여는 기다림을 줄이되, 느린 기기에서 첫 화면을 무겁게 만들지 않는 것입니다. 항상 켜 두면 빠른 기기에서는 이득이지만, 같은 최적화가 느린 기기에서는 반대로 작동할 수 있어 버렸습니다.</p>

<p>기기 메모리 값만 보는 방법도 두지 않았습니다. navigator.deviceMemory는 대략적인 기비바이트를 2의 거듭제곱으로 거칠게 돌려주고, 보안 맥락에서만 쓸 수 있습니다. W3C는 2026년 10월 이 API를 Discontinued Draft로 두었고, 지원하지 않는 브라우저에서는 값이 없습니다. 없는 값을 고사양으로 보면 preload가 꺼지지 않습니다.</p>

<p>네트워크 상태만 보는 방법도 좁았습니다. navigator.connection.saveData는 사용자가 데이터 절약을 켠 신호라 존중할 만하지만, Network Information API 자체는 모든 브라우저의 기준 기능이 아니고, 느린 CPU를 직접 말해 주지는 않습니다. 그래서 여러 신호를 보되, 하나가 없거나 낮으면 켜지 않기로 했습니다.</p>

<h2 id="기본-구조">기본 구조</h2>

<p>iframe 문서는 중첩된 탐색 공간입니다. display:none이어도 문서를 불러오고 스크립트를 실행하는 일은 멈추지 않습니다. 같은 출처이면 그 일이 부모 문서와 스레드를 나눠 쓰는 경우가 많아, 프레임 안의 긴 작업이 부모 화면의 입력을 밀 수 있습니다.</p>

<p><img src="/dev-articles/assets/2026-11-05-prework-when-to-connect-01.png" alt="숨은 iframe preload는 조건을 통과할 때만 켠다" /></p>

<p>켤 조건을 정할 때는 표준화된 값부터 봤습니다. navigator.hardwareConcurrency는 HTML에 정의된 논리 프로세서 수이고, 브라우저가 더 작은 수를 돌려줄 수 있습니다. saveData가 true이면 preload를 끕니다. deviceMemory가 있고 그 값이 낮으면 끄고, 값이 없으면 고사양으로 보지 않습니다.</p>

<div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">function</span> <span class="nx">shouldPreload</span><span class="p">({</span> <span class="nx">connection</span><span class="p">,</span> <span class="nx">deviceMemory</span><span class="p">,</span> <span class="nx">hardwareConcurrency</span> <span class="p">}</span> <span class="o">=</span> <span class="nb">navigator</span><span class="p">)</span> <span class="p">{</span>
  <span class="k">if</span> <span class="p">(</span><span class="nx">connection</span> <span class="o">&amp;&amp;</span> <span class="nx">connection</span><span class="p">.</span><span class="nx">saveData</span><span class="p">)</span> <span class="k">return</span> <span class="kc">false</span>
  <span class="k">if</span> <span class="p">(</span><span class="k">typeof</span> <span class="nx">deviceMemory</span> <span class="o">===</span> <span class="dl">'</span><span class="s1">number</span><span class="dl">'</span> <span class="o">&amp;&amp;</span> <span class="nx">deviceMemory</span> <span class="o">&lt;</span> <span class="mi">4</span><span class="p">)</span> <span class="k">return</span> <span class="kc">false</span>
  <span class="k">if</span> <span class="p">(</span><span class="k">typeof</span> <span class="nx">hardwareConcurrency</span> <span class="o">===</span> <span class="dl">'</span><span class="s1">number</span><span class="dl">'</span> <span class="o">&amp;&amp;</span> <span class="nx">hardwareConcurrency</span> <span class="o">&lt;=</span> <span class="mi">4</span><span class="p">)</span> <span class="k">return</span> <span class="kc">false</span>
  <span class="k">if</span> <span class="p">(</span><span class="k">typeof</span> <span class="nx">deviceMemory</span> <span class="o">!==</span> <span class="dl">'</span><span class="s1">number</span><span class="dl">'</span><span class="p">)</span> <span class="k">return</span> <span class="kc">false</span>
  <span class="k">return</span> <span class="kc">true</span>
<span class="p">}</span>

<span class="k">export</span> <span class="kd">function</span> <span class="nx">mountPreloadedPanel</span><span class="p">(</span><span class="nx">doc</span><span class="p">,</span> <span class="nx">src</span><span class="p">)</span> <span class="p">{</span>
  <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nx">shouldPreload</span><span class="p">())</span> <span class="k">return</span> <span class="kc">null</span>
  <span class="kd">const</span> <span class="nx">frame</span> <span class="o">=</span> <span class="nx">doc</span><span class="p">.</span><span class="nx">createElement</span><span class="p">(</span><span class="dl">'</span><span class="s1">iframe</span><span class="dl">'</span><span class="p">)</span>
  <span class="nx">frame</span><span class="p">.</span><span class="nx">src</span> <span class="o">=</span> <span class="nx">src</span>
  <span class="nx">frame</span><span class="p">.</span><span class="nx">style</span><span class="p">.</span><span class="nx">display</span> <span class="o">=</span> <span class="dl">'</span><span class="s1">none</span><span class="dl">'</span>
  <span class="nx">frame</span><span class="p">.</span><span class="nx">title</span> <span class="o">=</span> <span class="dl">'</span><span class="s1">미리 불러온 패널</span><span class="dl">'</span>
  <span class="nx">doc</span><span class="p">.</span><span class="nx">body</span><span class="p">.</span><span class="nx">appendChild</span><span class="p">(</span><span class="nx">frame</span><span class="p">)</span>
  <span class="k">return</span> <span class="nx">frame</span>
<span class="p">}</span>
</code></pre></div></div>

<h2 id="미리-불러오기를-켠-뒤">미리 불러오기를 켠 뒤</h2>

<h3 id="처음-판단-미리-불러오면-창이-빨리-열림">처음 판단: 미리 불러오면 창이 빨리 열림</h3>

<p>업로드 창을 빨리 열려고 숨은 iframe을 처음부터 불러 두었습니다. 빠른 기기에서는 기다림이 줄어 이 방법이 맞아 보였습니다.</p>

<h3 id="저사양-기기에서-미리-불러오기-끄기">저사양 기기에서 미리 불러오기 끄기</h3>

<p>사양이 낮은 기기에서는 같은 방식이 페이지를 불러오는 동안 렉을 만들 수 있어, 그 기기에서는 미리 불러오지 않게 바꾸고 불필요한 스크립트도 빼 두었습니다. 그 렉이 어디서 생기는지는, 첫 페인트가 아니라 숨은 프레임이 만든 긴 작업 쪽이었습니다.</p>

<h2 id="한계">한계</h2>

<p>deviceMemory는 비표준이고, 지금은 Discontinued Draft입니다. hardwareConcurrency는 HTML 기준 기능이지만 실제 코어 수보다 작게 보고될 수 있습니다. saveData는 브라우저에 따라 없을 수 있습니다. 신호를 보수적으로 보면 고사양에서도 가끔 꺼질 수 있고, preload를 끄면 빠른 기기에서는 창을 여는 순간 한 번 더 기다리게 됩니다. 그 비용을 감수하고, 기본값은 켜지 않는 쪽에 두었습니다.</p>

<h2 id="확인-방법">확인 방법</h2>

<p>확인은 페인트 시각과 긴 작업을 같이 봅니다. PerformancePaintTiming의 first-contentful-paint와, 긴 작업 항목의 개수와 합을 적습니다. CPU를 느리게 둔 뒤에도 같은 분량의 일이 길어지는지, shouldPreload()가 값이 없을 때 false를 주는지를 봅니다.</p>

<p>Headless Chrome 157에서 부모 문서에 제목을 바로 그려 두고, display:none iframe이 고정된 양의 일을 하는 스크립트를 불러오게 했습니다. 이 환경의 deviceMemory는 16, hardwareConcurrency는 8, saveData는 false였고, localhost라 보안 맥락은 true였습니다. preload가 없을 때 first-contentful-paint 중앙값은 1배속에서 40ms, 8배속에서는 124ms였고 긴 작업은 거의 없었습니다. 숨은 iframe을 붙이면 페인트는 1배속에서 40ms, 8배속에서 164ms로 비슷했지만, 긴 작업 총합 중앙값은 280ms에서 2,424ms로 늘었습니다.</p>

<p>저는 업로드 창을 빨리 열려고 항상 켜 두었다가, 사양이 낮은 기기에서 첫 화면이 무거워질 수 있어 그 기기에서는 끄기로 했습니다. 다시 재어 보니 그 비용은 페인트 숫자보다 긴 작업으로 나타났고, 같은 일이 느린 CPU에서 훨씬 길었습니다.</p>

<h2 id="정리">정리</h2>

<ul>
  <li>숨은 프레임도 부모와 스레드를 나눕니다.</li>
  <li>첫 페인트만 보면 비용을 놓칩니다.</li>
  <li>신호가 없거나 낮으면 켜지 않습니다.</li>
</ul>

<p>숨은 preload는 항상 켜 두지 않고, 기기와 네트워크가 감당할 때만 켜려고 합니다.</p>

<h2 id="참고">참고</h2>

<ul>
  <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/Navigator/deviceMemory">MDN deviceMemory</a></li>
  <li><a href="https://www.w3.org/TR/device-memory/">W3C Device Memory API</a></li>
  <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/Navigator/hardwareConcurrency">MDN hardwareConcurrency</a></li>
  <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation">MDN Network Information</a></li>
  <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/PerformancePaintTiming">MDN PerformancePaintTiming</a></li>
</ul>]]></content><author><name>zeno0505</name></author><category term="일일 회고" /><summary type="html"><![CDATA[업로드 창을 빨리 열려고 켠 숨은 iframe preload는, 저사양에서 첫 화면을 무겁게 만들 수 있어 기기 조건을 보고 켜기로 했습니다.]]></summary></entry><entry><title type="html">같은 오류 코드로는 중단과 시간 초과를 같이 끄지 않는다</title><link href="https://zeno0505.github.io/dev-articles/2026/11/04/mute-by-cause/" rel="alternate" type="text/html" title="같은 오류 코드로는 중단과 시간 초과를 같이 끄지 않는다" /><published>2026-11-04T00:00:00+09:00</published><updated>2026-11-04T00:00:00+09:00</updated><id>https://zeno0505.github.io/dev-articles/2026/11/04/mute-by-cause</id><content type="html" xml:base="https://zeno0505.github.io/dev-articles/2026/11/04/mute-by-cause/"><![CDATA[<p>한 오류 코드 아래를 통째로 끄면, 남겨야 할 신호까지 같이 사라집니다. 오류 알림이 크게 늘었을 때, 다른 앱에서 연 웹 화면이 다시 앱으로 넘어가며 끊긴 요청이 한꺼번에 잡힌 것으로 보였고, 그 실패 코드를 끄면 조용해질 거라고 생각했습니다. 다만 쓰던 클라이언트 axios 0.21.4는 브라우저가 끊은 요청과 시간 초과를 같은 오류 코드 ECONNABORTED로 남겨, 그 코드를 끄면 실제 시간 초과까지 안 보이게 됩니다. 그래서 브라우저가 끊은 요청만 보고에서 빼고, 시간 초과는 남겨 두었습니다.</p>

<p>이 글은 실패 알림이 늘었을 때 오류 코드를 묶어 끄려 하거나, 중단과 시간 초과가 같은 칸에 있는 분께 도움이 됩니다.</p>

<h2 id="과제와-제약">과제와 제약</h2>

<p>목표는 예상된 중단이 알림을 채우지 않게 하되, 실제 시간 초과와 고쳐야 할 실패는 보고에 남기는 것입니다. 화면이 닫히거나 다른 앱으로 넘어가며 요청이 끊기는 일은 자주 있습니다. 그 중단만 끄고, 같은 코드 아래의 시간 초과는 끄지 않아야 했습니다. 예상된 업무 4xx를 상태 코드만으로 끄면, 같은 상태에 숨은 다른 원인도 놓칩니다.</p>

<h2 id="한눈에-보는-결론">한눈에 보는 결론</h2>

<ul>
  <li>axios 0.21.4는 중단과 시간 초과에 같은 ECONNABORTED를 씁니다. 그 코드를 통째로 끄면 둘 다 사라집니다.</li>
  <li>브라우저가 끊은 요청만 보고에서 빼고, 시간 초과는 남겼습니다.</li>
  <li>공식 fetch 경로에서는 중단이 AbortError, 시간 초과가 TimeoutError이고, 4xx는 fetch가 거부하지 않습니다.</li>
  <li>예상된 업무 4xx를 알림에서 거른 뒤, 남은 실제 오류는 고치기 전과 후를 다시 재현해 고쳤습니다.</li>
</ul>

<h2 id="기본-구조">기본 구조</h2>

<p><img src="/dev-articles/assets/2026-11-04-mute-by-cause-01.png" alt="같은 오류 코드 아래를 원인으로 나눈다" /></p>

<p>실제 고친 모양은, 공유 코드가 아니라 원인 이름으로 보고 여부를 가리는 함수입니다. 공식 경로의 AbortError는 끄고, TimeoutError는 남깁니다. axios의 ECONNABORTED는 메시지나 원인 필드로 시간 초과와 중단을 나눕니다.</p>

<div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kd">function</span> <span class="nx">shouldReport</span><span class="p">(</span><span class="nx">error</span><span class="p">,</span> <span class="nx">response</span><span class="p">)</span> <span class="p">{</span>
  <span class="k">if</span> <span class="p">(</span><span class="nx">error</span> <span class="o">&amp;&amp;</span> <span class="nx">error</span><span class="p">.</span><span class="nx">name</span> <span class="o">===</span> <span class="dl">'</span><span class="s1">AbortError</span><span class="dl">'</span><span class="p">)</span> <span class="k">return</span> <span class="kc">false</span>
  <span class="k">if</span> <span class="p">(</span><span class="nx">error</span> <span class="o">&amp;&amp;</span> <span class="nx">error</span><span class="p">.</span><span class="nx">name</span> <span class="o">===</span> <span class="dl">'</span><span class="s1">TimeoutError</span><span class="dl">'</span><span class="p">)</span> <span class="k">return</span> <span class="kc">true</span>
  <span class="k">if</span> <span class="p">(</span><span class="nx">error</span> <span class="o">&amp;&amp;</span> <span class="nx">error</span><span class="p">.</span><span class="nx">code</span> <span class="o">===</span> <span class="dl">'</span><span class="s1">ECONNABORTED</span><span class="dl">'</span><span class="p">)</span> <span class="p">{</span>
    <span class="kd">const</span> <span class="nx">message</span> <span class="o">=</span> <span class="nb">String</span><span class="p">(</span><span class="nx">error</span><span class="p">.</span><span class="nx">message</span> <span class="o">||</span> <span class="dl">''</span><span class="p">)</span>
    <span class="k">if</span> <span class="p">(</span><span class="sr">/timeout/i</span><span class="p">.</span><span class="nx">test</span><span class="p">(</span><span class="nx">message</span><span class="p">))</span> <span class="k">return</span> <span class="kc">true</span>
    <span class="k">return</span> <span class="kc">false</span>
  <span class="p">}</span>
  <span class="k">if</span> <span class="p">(</span><span class="nx">response</span> <span class="o">&amp;&amp;</span> <span class="nx">response</span><span class="p">.</span><span class="nx">status</span> <span class="o">&gt;=</span> <span class="mi">400</span> <span class="o">&amp;&amp;</span> <span class="nx">response</span><span class="p">.</span><span class="nx">status</span> <span class="o">&lt;</span> <span class="mi">500</span><span class="p">)</span> <span class="p">{</span>
    <span class="kd">const</span> <span class="nx">cause</span> <span class="o">=</span> <span class="nx">response</span><span class="p">.</span><span class="nx">body</span> <span class="o">&amp;&amp;</span> <span class="nx">response</span><span class="p">.</span><span class="nx">body</span><span class="p">.</span><span class="nx">cause</span>
    <span class="k">if</span> <span class="p">(</span><span class="nx">cause</span> <span class="o">&amp;&amp;</span> <span class="nx">cause</span><span class="p">.</span><span class="nx">expected</span><span class="p">)</span> <span class="k">return</span> <span class="kc">false</span>
  <span class="p">}</span>
  <span class="k">return</span> <span class="kc">true</span>
<span class="p">}</span>
</code></pre></div></div>

<p>같은 출처의 느린 응답을 두고, 한쪽은 AbortController.abort()로 끊고 다른 쪽은 AbortSignal.timeout(50)으로 끊으면, 예외 이름은 AbortError와 TimeoutError로 갈렸습니다. 둘 다 DOMException이었습니다. 400 응답은 fetch가 거부하지 않았고, 상태와 본문을 그대로 주었습니다. 이 둘을 REQUEST_FAILED라는 한 코드로 묶은 뒤 그 코드를 끄면, 중단과 시간 초과가 함께 사라집니다. 원인 이름 기준으로 중단과 예상된 400만 끄면, 보고에 남는 것은 TimeoutError뿐입니다. 공식 문서도 AbortSignal.timeout이 시간 초과 때 TimeoutError를 쓰고, 사용자의 중단은 AbortError로 나누어 보라고 적습니다.</p>

<h2 id="알림을-끄기까지">알림을 끄기까지</h2>

<h3 id="처음-판단-공유-코드를-통째로-끄면-조용해질-것">처음 판단: 공유 코드를 통째로 끄면 조용해질 것</h3>

<p>알림이 늘었을 때 가장 쉬운 대응은 그 실패 코드를 통째로 끄는 것이었습니다. 다만 같은 칸에 실제 시간 초과가 들어 있으면, 시끄러운 쪽만 끄려다 장애 신호까지 같이 꺼집니다.</p>

<h3 id="브라우저가-끊은-요청만-제외-시간-초과는-유지">브라우저가 끊은 요청만 제외, 시간 초과는 유지</h3>

<p>쓰던 클라이언트가 두 원인을 같은 코드로 남긴다는 점을 본 뒤, 브라우저가 끊은 요청만 보고에서 빼기로 했습니다. 시간 초과는 그대로 두었습니다.</p>

<h3 id="예상된-4xx-거르기와-남은-오류의-전후-재현">예상된 4xx 거르기와 남은 오류의 전후 재현</h3>

<p>예상된 업무 응답이 알림을 가득 채우는 경우도 결이 같습니다. 정상적인 4xx를 상태 코드만으로 끄지 않고, 본문 원인까지 본 뒤 예상된 것만 거르고, 남은 실제 오류는 고치기 전과 후를 다시 재현해 고쳤습니다.</p>

<h2 id="한계">한계</h2>

<p>원인 단위로 나누면 분류 규칙이 늘어납니다. fetch는 4xx만으로 약속을 거부하지 않으므로, 상태만 보고 끄면 같은 상태 아래의 다른 본문 원인까지 같이 사라질 수 있습니다. 메시지 문자열만 믿으면 클라이언트가 바뀌었을 때 구분이 흔들릴 수 있어, 공식 경로에서는 예외 이름을 먼저 봅니다.</p>

<h2 id="확인-방법">확인 방법</h2>

<p>실패한 요청을 세 갈래로 재현합니다. AbortController로 끊은 요청, AbortSignal.timeout으로 끊은 요청, 그리고 예상된 4xx입니다. 각각에서 error.name, error.message, HTTP 상태를 적고, 한 코드로 끈 뒤의 남은 알림과 원인 단위로 끈 뒤의 남은 알림을 비교합니다. 시간 초과는 후자에만 남아야 합니다.</p>

<p>저는 알림이 늘었을 때 공유 코드를 통째로 끄면 편할 것처럼 보였습니다. 다시 보니 그 코드 아래에는 실행이 멈춘 중단과, 기다리다 실패한 시간 초과가 함께 있었습니다. 브라우저가 끊은 요청만 빼자 시간 초과는 보고에 남았고, 예상된 4xx를 거른 뒤에는 남은 실패를 고치기 전과 후로 재현할 수 있었습니다.</p>

<h2 id="정리">정리</h2>

<ul>
  <li>같은 오류 코드 아래를 통째로 끄지 않습니다.</li>
  <li>공식 경로에서는 AbortError와 TimeoutError를 나눕니다.</li>
  <li>예상된 4xx도 상태만이 아니라 본문 원인을 같이 봅니다.</li>
</ul>

<p>실패 알림은 코드 하나가 아니라, 그 아래에 있는 원인부터 보고 끄려고 합니다.</p>

<h2 id="참고">참고</h2>

<ul>
  <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch#exceptions">MDN fetch 예외</a></li>
  <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/timeout_static">MDN AbortSignal.timeout</a></li>
</ul>]]></content><author><name>zeno0505</name></author><category term="일일 회고" /><summary type="html"><![CDATA[axios 0.21.4는 중단과 시간 초과를 ECONNABORTED로 같이 남겨, 브라우저가 끊은 요청만 보고에서 빼고 시간 초과는 남겼습니다.]]></summary></entry><entry><title type="html">대비를 맞추려고 고른 색의 명도를 낮추지 않는다</title><link href="https://zeno0505.github.io/dev-articles/2026/10/27/fixed-or-changeable/" rel="alternate" type="text/html" title="대비를 맞추려고 고른 색의 명도를 낮추지 않는다" /><published>2026-10-27T00:00:00+09:00</published><updated>2026-10-27T00:00:00+09:00</updated><id>https://zeno0505.github.io/dev-articles/2026/10/27/fixed-or-changeable</id><content type="html" xml:base="https://zeno0505.github.io/dev-articles/2026/10/27/fixed-or-changeable/"><![CDATA[<p>대비를 맞추는 일과, 그 사람이 고른 색을 지키는 일은 같은 칸이 아닙니다. 소개 화면에서 사용자가 고른 원색을 구역 바탕으로 쓰다 보니, 그 위에 올린 흰 글자가 대비 기준을 못 넘었습니다. 흰 글자를 유지하려고 바탕 명도를 계산으로 내리면 될 거라고 봤습니다. 시안에서 밝은 산호색이 훨씬 어둡고 탁한 붉은색으로 바뀌어, 그 방법과 밝은 색을 막는 방법은 쓰지 않기로 했습니다.</p>

<p>이 글은 사용자가 고른 색을 구역 바탕으로 쓸 때, 대비를 맞추려고 그 색을 바꿀지를 가려야 하는 분께 도움이 됩니다.</p>

<h2 id="한눈에-보는-결론">한눈에 보는 결론</h2>

<ul>
  <li>제약: 고른 색은 그 사람의 인상이라 그대로 두고, 일반 텍스트 4.5:1, 큰 텍스트 3:1을 통과해야 합니다.</li>
  <li>결정: 큰 제목은 색 위에 짙은 글자, 본문은 흰 카드, 강조는 밑칠로 맞춥니다. 바탕을 어둡게 하거나 밝은 색을 막는 방법은 쓰지 않기로 했습니다.</li>
  <li>확인: #f08080과 흰 글자는 2.59:1로 두 기준을 못 넘겼고, 바탕을 #b15e5e로 낮추면 4.53:1이 되지만 명도는 72.2에서 53.1로, 채도는 78.9에서 34.7로 바뀌었습니다. 같은 산호색 위 검은 글자는 8.10:1이었습니다. 휴대 전화 너비 미리보기에서 고른 색이 그대로이고 글자를 읽을 수 있는지를 확인했습니다.</li>
</ul>

<h2 id="제약에-맞춰-고른-방법">제약에 맞춰 고른 방법</h2>

<p>바탕 명도를 계산으로 내리는 방법은 가장 단순했습니다. 흰 글자를 유지할 수 있고, 숫자만 보면 기준을 통과합니다. 다만 사용자가 고른 밝은 산호색이 훨씬 어둡고 탁한 붉은색으로 바뀝니다. 고른 색이 그 사람의 인상이라면, 대비를 위해 그 색을 바꾸는 일은 다른 색을 보여주는 일과 같습니다. 그래서 이 방법은 쓰지 않기로 했습니다.</p>

<p>너무 밝은 색을 고르지 못하게 막는 방법도 보았습니다. 대비는 쉽게 맞출 수 있지만, 밝은 색 자체를 쓰지 못하게 됩니다. 고른 색을 다시 바꾸라고 묻는 방법도, 이미 정한 인상을 흔들어 택하지 않았습니다.</p>

<h2 id="기본-구조">기본 구조</h2>

<p>WCAG 2.1은 sRGB에서 상대 휘도를 L = 0.2126R + 0.7152G + 0.0722B로 정의합니다. 각 채널은 8비트 값을 255로 나눈 뒤, 0.04045 이하면 12.92로 나누고, 그보다 크면 ((값 + 0.055) / 1.055)^2.4를 씁니다. 대비는 더 밝은 휘도 L1과 더 어두운 휘도 L2로 (L1 + 0.05) / (L2 + 0.05)입니다.</p>

<p><img src="/dev-articles/assets/2026-10-27-fixed-or-changeable-01.png" alt="고른 색은 두고, 글자와 배치로 대비를 맞춘다" /></p>

<p>실제 고친 모양은, 고른 색의 16진 값은 바꾸지 않고, 그 위에 올릴 글자 색과 본문 배치만 고르는 함수입니다.</p>

<div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kd">function</span> <span class="nx">contrastRatio</span><span class="p">(</span><span class="nx">a</span><span class="p">,</span> <span class="nx">b</span><span class="p">)</span> <span class="p">{</span>
  <span class="kd">const</span> <span class="nx">first</span> <span class="o">=</span> <span class="nx">relativeLuminance</span><span class="p">(</span><span class="nx">a</span><span class="p">)</span>
  <span class="kd">const</span> <span class="nx">second</span> <span class="o">=</span> <span class="nx">relativeLuminance</span><span class="p">(</span><span class="nx">b</span><span class="p">)</span>
  <span class="kd">const</span> <span class="nx">lighter</span> <span class="o">=</span> <span class="nb">Math</span><span class="p">.</span><span class="nx">max</span><span class="p">(</span><span class="nx">first</span><span class="p">,</span> <span class="nx">second</span><span class="p">)</span>
  <span class="kd">const</span> <span class="nx">darker</span> <span class="o">=</span> <span class="nb">Math</span><span class="p">.</span><span class="nx">min</span><span class="p">(</span><span class="nx">first</span><span class="p">,</span> <span class="nx">second</span><span class="p">)</span>
  <span class="k">return</span> <span class="p">(</span><span class="nx">lighter</span> <span class="o">+</span> <span class="mf">0.05</span><span class="p">)</span> <span class="o">/</span> <span class="p">(</span><span class="nx">darker</span> <span class="o">+</span> <span class="mf">0.05</span><span class="p">)</span>
<span class="p">}</span>

<span class="k">export</span> <span class="kd">function</span> <span class="nx">planOnBrandColor</span><span class="p">(</span><span class="nx">brand</span><span class="p">,</span> <span class="p">{</span> <span class="nx">white</span><span class="p">,</span> <span class="nx">black</span> <span class="p">})</span> <span class="p">{</span>
  <span class="kd">const</span> <span class="nx">withWhite</span> <span class="o">=</span> <span class="nx">contrastRatio</span><span class="p">(</span><span class="nx">brand</span><span class="p">,</span> <span class="nx">white</span><span class="p">)</span>
  <span class="kd">const</span> <span class="nx">withBlack</span> <span class="o">=</span> <span class="nx">contrastRatio</span><span class="p">(</span><span class="nx">brand</span><span class="p">,</span> <span class="nx">black</span><span class="p">)</span>
  <span class="k">if</span> <span class="p">(</span><span class="nx">withWhite</span> <span class="o">&gt;=</span> <span class="mf">4.5</span><span class="p">)</span> <span class="p">{</span>
    <span class="k">return</span> <span class="p">{</span> <span class="nx">brand</span><span class="p">,</span> <span class="na">title</span><span class="p">:</span> <span class="nx">white</span><span class="p">,</span> <span class="na">bodyOnCard</span><span class="p">:</span> <span class="kc">true</span> <span class="p">}</span>
  <span class="p">}</span>
  <span class="k">return</span> <span class="p">{</span> <span class="nx">brand</span><span class="p">,</span> <span class="na">title</span><span class="p">:</span> <span class="nx">withBlack</span> <span class="o">&gt;=</span> <span class="mf">4.5</span> <span class="p">?</span> <span class="nx">black</span> <span class="p">:</span> <span class="nx">white</span><span class="p">,</span> <span class="na">bodyOnCard</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span> <span class="na">highlight</span><span class="p">:</span> <span class="dl">'</span><span class="s1">underline</span><span class="dl">'</span> <span class="p">}</span>
<span class="p">}</span>

<span class="kd">function</span> <span class="nx">relativeLuminance</span><span class="p">([</span><span class="nx">red</span><span class="p">,</span> <span class="nx">green</span><span class="p">,</span> <span class="nx">blue</span><span class="p">])</span> <span class="p">{</span>
  <span class="kd">const</span> <span class="nx">channel</span> <span class="o">=</span> <span class="p">(</span><span class="nx">value</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span>
    <span class="kd">const</span> <span class="nx">srgb</span> <span class="o">=</span> <span class="nx">value</span> <span class="o">/</span> <span class="mi">255</span>
    <span class="k">return</span> <span class="nx">srgb</span> <span class="o">&lt;=</span> <span class="mf">0.04045</span> <span class="p">?</span> <span class="nx">srgb</span> <span class="o">/</span> <span class="mf">12.92</span> <span class="p">:</span> <span class="p">((</span><span class="nx">srgb</span> <span class="o">+</span> <span class="mf">0.055</span><span class="p">)</span> <span class="o">/</span> <span class="mf">1.055</span><span class="p">)</span> <span class="o">**</span> <span class="mf">2.4</span>
  <span class="p">}</span>
  <span class="k">return</span> <span class="mf">0.2126</span> <span class="o">*</span> <span class="nx">channel</span><span class="p">(</span><span class="nx">red</span><span class="p">)</span> <span class="o">+</span> <span class="mf">0.7152</span> <span class="o">*</span> <span class="nx">channel</span><span class="p">(</span><span class="nx">green</span><span class="p">)</span> <span class="o">+</span> <span class="mf">0.0722</span> <span class="o">*</span> <span class="nx">channel</span><span class="p">(</span><span class="nx">blue</span><span class="p">)</span>
<span class="p">}</span>
</code></pre></div></div>

<p>#f08080의 상대 휘도는 0.3552였습니다. 흰 글자와의 대비는 2.59:1로 두 기준을 모두 못 통과했습니다. 흰 글자 기준으로 4.5:1을 만들려면 바탕의 상대 휘도가 0.1833 이하여야 해서, 같은 색을 검게 가깝게 줄여 #b15e5e를 얻었습니다. 시안에서 본 탁한 붉은색이, 이 계산이 가리키는 변화와 같았습니다. 같은 #f08080 위에 검은 글자를 올리면 대비는 8.10:1이었습니다.</p>

<h2 id="시안을-고르기까지">시안을 고르기까지</h2>

<h3 id="처음-판단-바탕-명도를-낮춰-흰-글자-유지">처음 판단: 바탕 명도를 낮춰 흰 글자 유지</h3>

<p>흰 글자를 지키려고 바탕 명도를 계산으로 내리면 될 거라고 봤습니다. 시안에서 밝은 산호색이 훨씬 어둡고 탁한 붉은색으로 바뀌었습니다.</p>

<h3 id="두-배치-비교-뒤-고른-카드-배치">두 배치 비교 뒤 고른 카드 배치</h3>

<p>큰 제목은 색 위에 짙은 글자로 두고 본문은 흰 카드에 두는 안과, 다른 배치 안을 나란히 본 뒤 카드 쪽을 골랐습니다. 강조는 색을 바꾸는 대신 밑칠처럼 따로 표시하는 쪽으로 나누었습니다.</p>

<h3 id="미리보기에서-확인한-색-유지">미리보기에서 확인한 색 유지</h3>

<p>휴대 전화 너비로 미리보기를 열어, 고른 색이 그대로이고 글자를 읽을 수 있는지를 확인했습니다.</p>

<h2 id="한계">한계</h2>

<p>고른 색을 지키면, 밝은 바탕 위에 흰 글자를 쓰는 조합은 포기하게 됩니다. 대비만 올라가고 색의 16진 값이나 명도, 채도가 바뀌었다면, 이 글의 기준으로는 통과가 아닙니다.</p>

<h2 id="확인-방법">확인 방법</h2>

<p>공식과 같은 계산으로 상대 휘도와 대비를 다시 풉니다. 일반 텍스트 4.5:1과 큰 텍스트 3:1을 각각 통과하는지를 적습니다. 그리고 고른 색의 16진 값, 명도, 채도가 그대로인지를 같이 봅니다. 글자 색만 바꾼 조합에서는 바탕 색이 기준 값과 같아야 합니다.</p>

<p>저는 흰 글자를 지키려고 바탕을 낮추면 숫자가 맞을 거라고 봤습니다. 계산을 풀어 보니 그 방법은 숫자를 맞추는 대신 색을 바꿨고, 글자를 짙게 하고 본문을 카드에 두는 방법은 고른 색을 유지한 채 기준을 넘었습니다.</p>

<h2 id="정리">정리</h2>

<ul>
  <li>대비를 맞추려고 고른 색의 명도를 낮추지 않습니다.</li>
  <li>제목은 짙은 글자, 본문은 흰 카드, 강조는 밑칠로 나눕니다.</li>
  <li>통과 여부는 대비와 색이 그대로인지를 같이 봅니다.</li>
</ul>

<p>대비는 고른 색을 바꾸지 않고, 글자와 배치처럼 바꿔도 되는 쪽에서 맞추려고 합니다.</p>

<h2 id="참고">참고</h2>

<ul>
  <li><a href="https://www.w3.org/TR/WCAG21/#dfn-relative-luminance">WCAG 2.1 상대 휘도</a></li>
  <li><a href="https://www.w3.org/TR/WCAG21/#contrast-minimum">WCAG 2.1 Contrast (Minimum)</a></li>
  <li><a href="https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio">WCAG 2.1 대비 비율</a></li>
</ul>]]></content><author><name>zeno0505</name></author><category term="일일 회고" /><summary type="html"><![CDATA[사용자가 고른 원색 위 흰 글자가 대비 기준을 못 넘겨, 바탕을 낮추지 않고 글자와 흰 카드로 맞추기로 했습니다.]]></summary></entry><entry><title type="html">호출 수와 인라인 CSS는 응답 크기에서 다른 축이다</title><link href="https://zeno0505.github.io/dev-articles/2026/10/20/reference-and-weight/" rel="alternate" type="text/html" title="호출 수와 인라인 CSS는 응답 크기에서 다른 축이다" /><published>2026-10-20T00:00:00+09:00</published><updated>2026-10-20T00:00:00+09:00</updated><id>https://zeno0505.github.io/dev-articles/2026/10/20/reference-and-weight</id><content type="html" xml:base="https://zeno0505.github.io/dev-articles/2026/10/20/reference-and-weight/"><![CDATA[<p>호출을 줄였는데 응답 크기가 거의 그대로였습니다. 상세 화면을 서버에서 그릴 때 내려 주는 문서를 가볍게 하려고, 그 시점에 나가는 API 호출을 줄이면 응답도 작아질 거라고 봤습니다. 호출을 줄인 페이지와 아직 줄이지 않은 페이지의 응답 크기를 나란히 재 보니 거의 같았습니다. 응답을 열어 보니 대부분이 인라인 스타일이었고, 그제야 어느 축을 건드려야 할지가 보였습니다.</p>

<p>이 글은 서버가 내려 주는 HTML을 가볍게 하려 할 때, 호출 횟수가 줄었으니 응답도 줄었다고 보기 쉬운 분께 도움이 됩니다.</p>

<h2 id="한눈에-보는-결론">한눈에 보는 결론</h2>

<ul>
  <li>호출을 줄인 페이지와 안 줄인 페이지의 응답 크기는 거의 같았습니다. 열어 보니 대부분이 인라인 스타일이었습니다.</li>
  <li>같은 구조를 일반 예시로 짜서 재면, 기준 102,163바이트 가운데 인라인 CSS가 90,000바이트로 88.1%였습니다. 데이터만 줄이면 전체는 8.8%만 줄고, 인라인 CSS를 20,000바이트로 줄이면 전체는 68.5%가 줄었습니다.</li>
  <li>호출 횟수는 별 지표로 두고, 칸별 바이트 비중을 같이 봅니다.</li>
</ul>

<h2 id="과제와-제약">과제와 제약</h2>

<p>목표는 서버가 만들어 보내는 HTML을 가볍게 하는 것입니다. 호출 수가 줄어든 것과 내려 가는 바이트가 줄어든 것은 같은 신호가 아니라, 응답을 열어 어떤 칸이 큰지부터 봐야 했습니다.</p>

<h2 id="다시-재-보기까지">다시 재 보기까지</h2>

<h3 id="처음-판단-호출을-줄이면-응답도-작아질-것이라는-예상">처음 판단: 호출을 줄이면 응답도 작아질 것이라는 예상</h3>

<p>서버 렌더 시점에 API를 덜 부르면 직렬화되는 데이터도 줄고, 응답도 작아질 거라고 봤습니다. 그래서 호출을 줄이는 일부터 했습니다.</p>

<h3 id="나란히-잰-결과-비슷한-크기와-인라인-스타일">나란히 잰 결과: 비슷한 크기와 인라인 스타일</h3>

<p>호출을 줄인 페이지와 아직 줄이지 않은 페이지의 응답 크기는 거의 같았습니다. 응답을 열어 보니 대부분이 인라인 스타일이었고, 그제야 어느 축을 건드려야 할지가 보였습니다.</p>

<h2 id="기본-구조">기본 구조</h2>

<p><img src="/dev-articles/assets/2026-10-20-reference-and-weight-01.png" alt="응답 크기에서 큰 칸은 호출 수가 아니다" /></p>

<p>서버 렌더 시점에 API를 덜 부르면 데이터가 줄어들 수는 있습니다. 다만 그 데이터가 응답 전체에서 차지하는 비율이 작으면, 호출 수가 줄어도 내려 가는 바이트는 거의 그대로입니다. 인라인 CSS는 같은 문서 안에서 한 번 더 실리고, 선택자를 반복할수록 그 칸이 커집니다.</p>

<p>실제 고친 모양은, 줄이기 전에 응답 전체와 칸별 바이트를 같이 적어 어느 축을 건드릴지 정하는 쪽입니다.</p>

<div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kd">function</span> <span class="nx">measure</span><span class="p">(</span><span class="nx">html</span><span class="p">)</span> <span class="p">{</span>
  <span class="kd">const</span> <span class="nx">buf</span> <span class="o">=</span> <span class="nx">Buffer</span><span class="p">.</span><span class="k">from</span><span class="p">(</span><span class="nx">html</span><span class="p">,</span> <span class="dl">'</span><span class="s1">utf8</span><span class="dl">'</span><span class="p">)</span>
  <span class="kd">const</span> <span class="nx">css</span> <span class="o">=</span> <span class="nx">html</span><span class="p">.</span><span class="nx">match</span><span class="p">(</span><span class="sr">/&lt;style&gt;</span><span class="se">([\s\S]</span><span class="sr">*</span><span class="se">)</span><span class="sr">&lt;</span><span class="se">\/</span><span class="sr">style&gt;/</span><span class="p">)?.[</span><span class="mi">1</span><span class="p">]</span> <span class="o">||</span> <span class="dl">''</span>
  <span class="kd">const</span> <span class="nx">api</span> <span class="o">=</span> <span class="nx">html</span><span class="p">.</span><span class="nx">match</span><span class="p">(</span><span class="sr">/id="data"&gt;</span><span class="se">([\s\S]</span><span class="sr">*</span><span class="se">?)</span><span class="sr">&lt;</span><span class="se">\/</span><span class="sr">script&gt;/</span><span class="p">)?.[</span><span class="mi">1</span><span class="p">]</span> <span class="o">||</span> <span class="dl">''</span>
  <span class="kd">const</span> <span class="nx">total</span> <span class="o">=</span> <span class="nx">buf</span><span class="p">.</span><span class="nx">length</span>
  <span class="kd">const</span> <span class="nx">inlineCss</span> <span class="o">=</span> <span class="nx">Buffer</span><span class="p">.</span><span class="nx">byteLength</span><span class="p">(</span><span class="nx">css</span><span class="p">)</span>
  <span class="kd">const</span> <span class="nx">apiJson</span> <span class="o">=</span> <span class="nx">Buffer</span><span class="p">.</span><span class="nx">byteLength</span><span class="p">(</span><span class="nx">api</span><span class="p">)</span>
  <span class="k">return</span> <span class="p">{</span>
    <span class="nx">total</span><span class="p">,</span>
    <span class="nx">inlineCss</span><span class="p">,</span>
    <span class="nx">apiJson</span><span class="p">,</span>
    <span class="na">cssShare</span><span class="p">:</span> <span class="nx">inlineCss</span> <span class="o">/</span> <span class="nx">total</span><span class="p">,</span>
    <span class="na">apiShare</span><span class="p">:</span> <span class="nx">apiJson</span> <span class="o">/</span> <span class="nx">total</span><span class="p">,</span>
  <span class="p">}</span>
<span class="p">}</span>

<span class="k">export</span> <span class="kd">function</span> <span class="nx">pickAxis</span><span class="p">(</span><span class="nx">baseline</span><span class="p">,</span> <span class="nx">changed</span><span class="p">)</span> <span class="p">{</span>
  <span class="kd">const</span> <span class="nx">dropped</span> <span class="o">=</span> <span class="p">(</span><span class="nx">baseline</span><span class="p">.</span><span class="nx">total</span> <span class="o">-</span> <span class="nx">changed</span><span class="p">.</span><span class="nx">total</span><span class="p">)</span> <span class="o">/</span> <span class="nx">baseline</span><span class="p">.</span><span class="nx">total</span>
  <span class="k">return</span> <span class="p">{</span> <span class="nx">dropped</span><span class="p">,</span> <span class="na">heavier</span><span class="p">:</span> <span class="nx">baseline</span><span class="p">.</span><span class="nx">cssShare</span> <span class="o">&gt;=</span> <span class="nx">baseline</span><span class="p">.</span><span class="nx">apiShare</span> <span class="p">?</span> <span class="dl">'</span><span class="s1">inlineCss</span><span class="dl">'</span> <span class="p">:</span> <span class="dl">'</span><span class="s1">apiJson</span><span class="dl">'</span> <span class="p">}</span>
<span class="p">}</span>
</code></pre></div></div>

<p>기준은 인라인 CSS 90,000바이트와 데이터 약 12,000바이트로, 전체 102,163바이트입니다. 데이터만 줄인 문서는 93,163바이트로 9,000바이트가 줄었습니다. 인라인 CSS만 20,000바이트로 줄인 문서는 32,163바이트로 70,000바이트가 줄었습니다. 둘 다 줄이면 23,163바이트입니다.</p>

<h2 id="제약에-맞춰-고른-방법">제약에 맞춰 고른 방법</h2>

<p>데이터만 줄이고 끝내거나, 호출 횟수만 보고 부하가 줄었다고 보는 방법은, 위에서 본 8.8%짜리 변화만으로는 근거가 부족했습니다. 외부 스타일 파일로 나누는 방법도 있습니다. 첫 HTML은 작아지고 스타일은 캐시될 수 있지만, 그때는 추가 요청과 캐시 전략까지 같이 정해야 하므로, 이번 측정만으로 그 방법을 택하지는 않았습니다. 먼저 응답을 열어 어떤 칸이 큰지 재고, 그다음에 어느 축을 건드릴지 정하기로 했습니다.</p>

<h2 id="확인-방법">확인 방법</h2>

<p>응답 전체 길이만 보지 않습니다. 인라인 CSS 바이트, 데이터 바이트, 그 둘이 전체에서 차지하는 비율을 같이 적습니다. 한 칸만 줄인 문서와 기준 문서를 나란히 두고, 전체가 얼마나 줄었는지를 봅니다. 호출 횟수는 별 지표로 남겨, 바이트 변화와 섞지 않습니다. 같은 방법으로 실제 응답을 열면, 어느 칸이 큰지는 같은 방식으로 갈립니다.</p>

<p>저는 호출이 곧 부하라고 보고 데이터부터 줄였습니다. 나란히 재 보니 응답 크기는 거의 같았고, 열어 보니 기준 문서의 대부분은 인라인 CSS였습니다. 그 칸을 줄여야 응답 크기가 의미 있게 변했습니다.</p>

<h2 id="정리">정리</h2>

<ul>
  <li>호출 횟수와 응답 바이트는 다른 축입니다.</li>
  <li>줄이기 전에 칸별 비중을 엽니다.</li>
  <li>작은 칸만 줄인 변화를 성공으로 보지 않습니다.</li>
</ul>

<p>응답을 줄일 때는 호출 횟수보다, 실제로 큰 칸이 무엇인지부터 보려고 합니다.</p>]]></content><author><name>zeno0505</name></author><category term="일일 회고" /><summary type="html"><![CDATA[서버 렌더 호출을 줄여도 응답 크기가 거의 같았고, 열어 보니 대부분은 인라인 스타일이었습니다.]]></summary></entry></feed>