<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0"><channel><title><![CDATA[/dev/write]]></title><description><![CDATA[남정현의 기술 블로그. C#과 .NET 개발, Azure 배포, AI 개발 도구와 로컬 모델 실험, 오픈소스 개발기를 코드와 실행 결과로 풀어냅니다.]]></description><link>https://devwrite.ai</link><image><url>https://cdn.hashnode.com/uploads/logos/60adcb82557cc70e51211e5c/915fd88f-2922-478e-9ac3-77ae90ffe52c.png</url><title>/dev/write</title><link>https://devwrite.ai</link></image><generator>RSS for Node</generator><lastBuildDate>Sun, 22 Nov 2026 08:01:52 GMT</lastBuildDate><atom:link href="https://devwrite.ai/rss.xml" rel="self" type="application/rss+xml"/><language><![CDATA[en]]></language><ttl>60</ttl><item><title><![CDATA[[.NET 11 미리보기] C# 파일 기반 앱의 진화]]></title><description><![CDATA[한 파일로 시작한 도구에서 코드를 나누고 공유하는 방법]]></description><link>https://devwrite.ai/net-11-file-based-app-evolution</link><guid isPermaLink="true">https://devwrite.ai/net-11-file-based-app-evolution</guid><category><![CDATA[.NET]]></category><category><![CDATA[net11]]></category><category><![CDATA[C#]]></category><category><![CDATA[fba]]></category><dc:creator><![CDATA[Jung-hyun, Nam]]></dc:creator><pubDate>Tue, 10 Nov 2026 04:40:58 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/covers/60adcb82557cc70e51211e5c/8ee81c38-e411-421d-a41f-d4099b44a508.jpg" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>C# 파일 하나로 도구를 만들어도 출력 형식이 늘거나 다른 도구와 기능을 공유할 때는 코드를 나눌 필요가 생깁니다. .NET 11의 <code>#:include</code>는 여러 파일의 소스를 한 앱에서 함께 컴파일하고, <code>#:ref</code>는 다른 파일 기반 앱을 별도 어셈블리로 참조합니다. Damian Edwards의 .NET Conf 2026 발표 초록은 이 변화와 함께 반복 실행 속도, NuGet 참조, CLI 명령의 개선을 예고했습니다. 2026년 11월 10일 기준 .NET 11 RC3에서 두 지시문과 반복 실행이 어떻게 동작하는지 살펴봅니다. <a href="https://dotnet.microsoft.com/en-us/conf/2026/agenda#:~:text=C%23%20File-based%20apps%20turned%20up%20to%2011!">공식 세션 초록</a></p>
<h2>C# 파일 실행과 SDK의 역할</h2>
<p>.NET 10부터는 <code>dotnet run --file App.cs</code>처럼 진입점 파일을 지정해 앱을 빌드하고 실행할 수 있습니다. SDK는 메모리에 가상 프로젝트를 만들고 파일 머리의 <code>#:</code> 지시문을 MSBuild 속성과 항목으로 해석합니다. NuGet 패키지 복원, 대상 프레임워크 지정, 빌드 결과 생성에는 이 프로젝트의 구성을 사용합니다. C# 컴파일러는 진입점 파일의 최상위 문을 컴파일합니다. <a href="https://learn.microsoft.com/en-us/dotnet/core/sdk/file-based-apps">Microsoft Learn 파일 기반 앱 안내</a></p>
<p>같은 폴더에 여러 <code>.cs</code> 파일을 두어도 기본 컴파일 대상은 진입점 파일 하나입니다. 도구별로 진입점을 두고, 앱마다 필요한 소스와 어셈블리를 명시할 수 있습니다. <a href="https://github.com/dotnet/dotnet/blob/v11.0.100-rc.3.26522.148/src/sdk/src/Cli/Microsoft.DotNet.FileBasedPrograms/VirtualProjectBuilder.cs#L615-L662">RC3 SDK 가상 프로젝트 생성기</a></p>
<h2>소스 포함과 앱 참조</h2>
<p><code>#:include Helpers.cs</code>를 쓰면 <code>Helpers.cs</code>가 현재 앱의 컴파일에 포함됩니다. 이 파일에 형식이나 메서드를 선언하고, 최상위 실행 문은 진입점에 둡니다. 같은 어셈블리에 들어가는 코드이므로 앱에서 <code>internal</code> 멤버에 접근할 수 있습니다. <code>#:include</code>는 .NET 11의 앞선 미리 보기와 .NET 10 SDK의 후속 업데이트에서도 제공됐습니다. <a href="https://learn.microsoft.com/en-us/dotnet/core/sdk/file-based-apps#include">Microsoft Learn의 파일 포함 규칙</a></p>
<p><code>#:ref ./Meter.cs</code>는 <code>Meter.cs</code>에서 만든 가상 프로젝트를 참조합니다. SDK가 두 앱을 따로 컴파일하므로 참조한 앱에서는 <code>Meter.cs</code>의 공개 형식에 접근할 수 있습니다. <code>Meter.cs</code>에 진입점이 있다면 그 파일을 직접 실행할 때만 진입점이 동작합니다. 진입점 없이 라이브러리로 쓸 파일에는 <code>#:property OutputType=Library</code>를 선언합니다. <code>.csproj</code>를 참조할 때는 <code>#:project</code>를 씁니다. <a href="https://github.com/dotnet/dotnet/blob/v11.0.100-rc.3.26522.148/src/sdk/documentation/general/dotnet-run-file.md#L247-L275">RC3 SDK 설계 문서의 참조 규칙</a></p>
<p><code>#:package</code>에서 패키지 ID와 버전 뒤에 <code>Aliases=CommandLine</code> 같은 메타데이터를 붙일 수 있습니다. 예를 들어 <code>#:package System.CommandLine@2.0.1 Aliases=CommandLine</code>으로 참조를 추가하면 코드에서 <code>extern alias CommandLine;</code>으로 별칭을 가져와 이 참조를 구분할 수 있습니다. <code>#:project</code>와 <code>#:ref</code>도 뒤에 메타데이터를 받을 수 있습니다. <code>#:property Company="Contoso Tools"</code>처럼 공백이 들어간 값은 따옴표로 묶습니다. SDK는 이렇게 지정한 값을 가상 프로젝트의 MSBuild 항목과 속성에 반영합니다. <a href="https://learn.microsoft.com/en-us/dotnet/core/whats-new/dotnet-11/sdk#quoted-values-and-item-metadata-in-file-based-directives">Microsoft Learn의 .NET 11 SDK 변경 사항</a></p>
<h2>RC3의 참조 처리와 실행 경로</h2>
<p>RC3의 <code>VirtualProjectBuilder</code>는 <code>#:ref</code>가 가리키는 파일의 가상 프로젝트를 만듭니다. 그 파일에 또 다른 참조가 있으면 같은 과정을 반복하고, 각각을 <code>ProjectReference</code> 항목으로 연결합니다. 패키지에 붙인 메타데이터는 <code>PackageReference</code>에 기록합니다. <code>dotnet reference add --file</code> 명령은 입력 경로가 C# 진입점이면 파일 기반 앱의 참조를 편집하는 코드에 처리를 맡깁니다. <a href="https://github.com/dotnet/dotnet/releases/tag/v11.0.100-rc.3.26522.148">RC3 소스 태그</a> <a href="https://github.com/dotnet/dotnet/blob/v11.0.100-rc.3.26522.148/src/sdk/src/Cli/Microsoft.DotNet.FileBasedPrograms/VirtualProjectBuilder.cs#L531-L570">가상 참조 프로젝트 생성</a> <a href="https://github.com/dotnet/dotnet/blob/v11.0.100-rc.3.26522.148/src/sdk/src/Cli/Microsoft.DotNet.FileBasedPrograms/VirtualProjectBuilder.cs#L855-L905">패키지 및 프로젝트 항목 생성</a> <a href="https://github.com/dotnet/dotnet/blob/v11.0.100-rc.3.26522.148/src/sdk/src/Cli/dotnet/Commands/Reference/Add/ReferenceAddCommand.cs#L113-L161">참조 명령 구현</a></p>
<p>SDK는 기존 빌드 결과를 실행하거나, 저장한 인수로 C# 컴파일러를 직접 호출하거나, MSBuild로 전체 빌드를 수행합니다. Native AOT CLI는 캐시에 남은 빌드 성공 기록이 유효하고 실행 정보가 일치할 때 기존 빌드 결과를 바로 실행합니다. 이를 판단할 때 SDK와 런타임 버전, 전역 속성, 진입점과 추가 입력 파일의 변경 여부를 확인합니다. 조건에 맞지 않으면 관리형 CLI가 실행을 이어받습니다. <a href="https://github.com/dotnet/dotnet/blob/v11.0.100-rc.3.26522.148/src/sdk/src/Cli/dotnet/Commands/Run/FileBasedAppRunPlan.cs#L70-L198">RC3 실행 계획과 캐시 판정</a> <a href="https://github.com/dotnet/dotnet/blob/v11.0.100-rc.3.26522.148/src/sdk/src/Cli/dotnet/Commands/Run/FileBasedAppRunPlan.cs#L408-L554">입력 변경 확인</a></p>
<p>RC3는 <code>#:project</code>나 <code>#:ref</code>가 있거나 <code>#:include</code>에 와일드카드를 쓴 앱을 빌드할 때 이 최적화에 필요한 캐시를 저장하지 않습니다. 아래에서는 앱 간 참조와 재실행 캐시를 서로 다른 예제로 확인합니다. <strong>발표 예상</strong>으로는 의존성이 단순한 앱을 골라 첫 실행과 재실행의 차이를 보여 줄 수 있습니다. 초록에는 실제 시연 구성이나 성능 수치가 공개되지 않았습니다. <a href="https://github.com/dotnet/dotnet/blob/v11.0.100-rc.3.26522.148/src/sdk/src/Cli/dotnet/Commands/Run/VirtualProjectBuildingCommand.cs#L470-L499">RC3 캐시 저장 조건</a> <a href="https://dotnet.microsoft.com/en-us/conf/2026/agenda#:~:text=C%23%20File-based%20apps%20turned%20up%20to%2011!">공식 세션 초록</a></p>
<h2>파일 포함과 앱 참조 예제</h2>
<p>빈 폴더에 다음 세 파일을 저장합니다. 예제에는 Native AOT 게시 도구 없이 실습할 수 있도록 <code>PublishAot=false</code>를 지정했습니다. <code>Dashboard.cs</code>를 빌드하면 <code>Labels.cs</code>는 앱과 함께 컴파일되고 <code>Meter.cs</code>는 별도 어셈블리로 참조됩니다. 앱은 이 어셈블리에서 <code>Meter</code>의 공개 메서드를 호출합니다.</p>
<p><code>Dashboard.cs</code></p>
<pre><code class="language-csharp">#!/usr/bin/env dotnet
#:property PublishAot=false
#:ref ./Meter.cs
#:include ./Labels.cs

Console.WriteLine($"{Labels.Today} {Meter.Format(12)}");
Console.WriteLine(typeof(Meter).Assembly.GetName().Name);
</code></pre>
<p><code>Labels.cs</code></p>
<pre><code class="language-csharp">internal static class Labels
{
    internal const string Today = "Today";
}
</code></pre>
<p><code>Meter.cs</code></p>
<pre><code class="language-csharp">#:property PublishAot=false

Console.WriteLine(Meter.Format(5));

public static class Meter
{
    public static string Format(int count) =&gt; $"{count} jobs";
}
</code></pre>
<p>파일을 저장한 폴더에서 <code>dotnet --version</code>을 실행해 .NET 11 RC3 SDK가 선택됐는지 확인합니다. SDK가 여러 개 설치돼 있다면 아래 릴리스 노트에서 RC3 SDK의 전체 버전을 확인해 <code>global.json</code>의 <code>sdk.version</code>에 적습니다. <code>rollForward</code>를 <code>disable</code>, <code>allowPrerelease</code>를 <code>true</code>로 지정하면 해당 SDK 버전을 고정할 수 있습니다. <a href="https://learn.microsoft.com/en-us/dotnet/core/tools/global-json">Microsoft Learn의 global.json 규칙</a></p>
<pre><code class="language-shell">dotnet run --file Dashboard.cs
dotnet run --file Meter.cs
dotnet reference list --file Dashboard.cs
</code></pre>
<p>첫 명령을 실행하면 <code>Today 12 jobs</code>와 참조한 어셈블리 이름 <code>Meter</code>가 나옵니다. <code>Meter.cs</code> 진입점의 <code>5 jobs</code>는 두 번째 명령에서만 출력됩니다. 마지막 명령은 참조 목록에 <code>./Meter.cs</code>를 표시합니다. 같은 명령의 <code>remove</code>와 <code>add</code>로 참조 지시문을 바꿀 수 있습니다. Windows에서 RC3 SDK로 세 명령의 출력을 확인했습니다. <a href="https://github.com/dotnet/dotnet/blob/v11.0.100-rc.3.26522.148/src/sdk/src/Cli/dotnet/Commands/Reference/Add/ReferenceAddCommand.cs#L113-L161">RC3 참조 명령 구현</a></p>
<p>패키지 별칭과 재실행 캐시를 보려면 아래 코드를 <code>AliasDemo.cs</code>에 저장합니다. <code>System.CommandLine</code>을 예제에 지정한 버전으로 복원할 수 있는 NuGet 패키지 소스나 로컬 캐시가 필요합니다.</p>
<pre><code class="language-csharp">#:property PublishAot=false
#:property Company="Queue Tools"
#:package System.CommandLine@2.0.1 Aliases=CommandLine

extern alias CommandLine;
using System.Reflection;

var commandType = typeof(CommandLine::System.CommandLine.RootCommand);
var app = Assembly.GetExecutingAssembly();

Console.WriteLine(commandType.Assembly.GetName().Name);
Console.WriteLine(app.GetCustomAttribute&lt;AssemblyCompanyAttribute&gt;()?.Company);
</code></pre>
<p><code>dotnet run --file AliasDemo.cs</code>를 실행하면 <code>System.CommandLine</code>과 <code>Queue Tools</code>가 나옵니다. Windows의 RC3 SDK에서 <code>DOTNET_CLI_CONTEXT_VERBOSE=true</code>를 설정하고 이 명령을 두 번 실행했습니다. 처음에는 관리형 CLI가 빌드했고, 파일을 그대로 둔 채 다시 실행하자 <code>AOT run tier: CachedLaunch (CacheValid)</code>가 기록됐습니다. <a href="https://github.com/dotnet/dotnet/blob/v11.0.100-rc.3.26522.148/src/sdk/src/Cli/dotnet/Commands/Run/FileBasedAppRunPlan.cs#L137-L198">RC3 실행 계획 구현</a></p>
<h2>명령 해석과 게시 설정의 제약</h2>
<p>현재 폴더에 프로젝트 파일이 있으면 <code>dotnet run App.cs</code>에서 <code>App.cs</code>가 기존 프로젝트의 실행 인수로 해석될 수 있습니다. 파일 자체를 실행할 때는 예제처럼 <code>--file</code>을 붙입니다. 여러 파일을 쓰는 앱이라면 진입점 첫 줄에 셔뱅(shebang)을 넣어 IDE가 진입점을 찾기 쉽게 할 수 있습니다. <code>dotnet build App.cs</code>와 <code>dotnet format App.cs</code>에도 파일 경로를 넘길 수 있습니다. 빌드 구성이 복잡해지면 <code>dotnet project convert App.cs</code>로 가상 프로젝트 구성을 <code>.csproj</code>로 옮길 수 있습니다. <a href="https://github.com/dotnet/dotnet/blob/v11.0.100-rc.3.26522.148/src/sdk/documentation/general/dotnet-run-file.md">RC3 SDK 설계 문서</a></p>
<p>파일 기반 앱의 기본 게시 설정은 <code>PublishAot=true</code>, 기본 패키징 설정은 <code>PackAsTool=true</code>입니다. CLI가 기존 빌드 결과를 캐시에서 찾아 실행하는 것과 앱 자체를 Native AOT로 게시하는 것은 별개의 기능입니다. 배포용 앱을 게시할 때는 대상 플랫폼에서 쓸 Native AOT 도구와 의존 패키지의 호환성을 확인합니다. <a href="https://learn.microsoft.com/en-us/dotnet/core/sdk/file-based-apps">Microsoft Learn 파일 기반 앱 안내</a> <a href="https://learn.microsoft.com/en-us/dotnet/core/deploying/native-aot/">Microsoft Learn Native AOT 배포</a></p>
<h2>결론</h2>
<p>한 도구 안에서 코드를 정리할 때는 <code>#:include</code>로 구현을 나눌 수 있습니다. 여러 도구에 공개 API를 제공할 때는 <code>#:ref</code>로 공유 코드를 별도 어셈블리에 둡니다. 파일 기반 앱을 유지하면서도 어떤 코드가 함께 컴파일되고, 어떤 코드가 참조를 통해 공유되는지 드러낼 수 있습니다.</p>
<h2>1차 출처</h2>
<ul>
<li><a href="https://dotnet.microsoft.com/en-us/conf/2026/agenda#:~:text=C%23%20File-based%20apps%20turned%20up%20to%2011!">공식 .NET Conf 2026 일정과 「C# File-based apps turned up to 11!」 초록</a></li>
<li><a href="https://github.com/dotnet/core/blob/main/release-notes/11.0/preview/rc3/11.0.0-rc.3.md">.NET 11 RC3 릴리스 노트 및 SDK 빌드 번호</a></li>
<li><a href="https://learn.microsoft.com/en-us/dotnet/core/sdk/file-based-apps">Microsoft Learn 파일 기반 앱 안내</a></li>
<li><a href="https://learn.microsoft.com/en-us/dotnet/core/whats-new/dotnet-11/sdk">Microsoft Learn .NET 11 SDK 및 도구 변경 사항</a></li>
<li><a href="https://github.com/dotnet/dotnet/blob/v11.0.100-rc.3.26522.148/src/sdk/documentation/general/dotnet-run-file.md">RC3 SDK 파일 기반 앱 설계 문서</a></li>
<li><a href="https://github.com/dotnet/dotnet/blob/v11.0.100-rc.3.26522.148/src/sdk/src/Cli/Microsoft.DotNet.FileBasedPrograms/VirtualProjectBuilder.cs">RC3 가상 프로젝트 구현</a> · <a href="https://github.com/dotnet/dotnet/blob/v11.0.100-rc.3.26522.148/src/sdk/src/Cli/dotnet/Commands/Run/FileBasedAppRunPlan.cs">RC3 실행 계획 구현</a></li>
</ul>
]]></content:encoded></item><item><title><![CDATA[Edge0 연재 5: M2 Air 16GB 실측 결과와 사내 PoC 확장 조건]]></title><description><![CDATA[M2 MacBook Air 16GB에서 Edge0 RAG 에이전트를 실행한 기록을 분석합니다. TTFT 53.47초의 의미, 이벤트 기반 출력 속도, 입력량 조절과 사내 PoC 확장 조건을 정리합니다.]]></description><link>https://devwrite.ai/edge0-real-benchmark-and-poc</link><guid isPermaLink="true">https://devwrite.ai/edge0-real-benchmark-and-poc</guid><category><![CDATA[llm]]></category><category><![CDATA[RAG ]]></category><category><![CDATA[apple silicon]]></category><category><![CDATA[microsoft-learn]]></category><dc:creator><![CDATA[Jung-hyun, Nam]]></dc:creator><pubDate>Thu, 17 Sep 2026 00:00:00 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/gql/60adcb82557cc70e51211e5c/e2e1dc2f-2bf7-4f46-8677-63a29048535c.webp" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>M2 MacBook Air 16GB에서 Microsoft Learn 검색, Edge0 스트리밍, 문장 단위 한국어 번역을 연결한 에이전트를 실행했습니다. 2026년 9월 13일 확인한 <a href="https://gist.github.com/rkttu/805dd58e333b7e51b10326168a484c2d">샘플 Gist</a>에는 전체 코드와 함께 TTFT 53.47초를 기록한 실행 결과를 공개했습니다.</p>
<p>마지막 글은 측정에 사용한 질문, 검색과 첫 응답까지의 시간, 생성 답변의 근거, 출력 속도의 해석, 후속 최적화와 사내 PoC 확장 조건을 다룹니다. <a href="https://rkttu.hashnode.dev/edge0-streaming-ttft-metrics">4편</a>에서 설명한 클라이언트 계측을 기준으로 결과를 읽습니다.</p>
<p>실행 로그와 측정값부터 살펴보겠습니다. 각 단계의 시간을 비교한 뒤 현재 결과로 판단할 수 있는 범위와 추가 실험이 필요한 범위를 나눠 설명합니다.</p>
<p>수치를 비교할 때의 기준은 다음과 같습니다.</p>
<blockquote>
<p>문서는 2026년 9월 13일에 확인했습니다. 아래 수치는 특정 질문과 검색 결과를 사용한 한 번의 실행에서 기록했습니다. 실행 당시의 모든 버전, 캐시 상태와 반복 측정 결과는 이 기록만으로 확인되지 않습니다. <code>tok/s</code>로 표시한 값은 콘텐츠가 있는 SSE 이벤트 수로 계산했습니다.</p>
</blockquote>
<h2>Native AOT 질문을 사용한 단일 실행</h2>
<p>실험에는 M2 MacBook Air 16GB와 <code>Edge0-35B-A3B-preview</code>를 사용했습니다. Python 호스트가 Microsoft Learn을 검색하고 Apple Translation으로 입력과 출력을 번역하는 구성은 <a href="https://gist.github.com/rkttu/805dd58e333b7e51b10326168a484c2d">Gist의 실행 안내</a>와 같습니다.</p>
<p>질문은 다음과 같이 입력했습니다.</p>
<pre><code class="language-text">NativeAOT에서 Reflection.Emit을 사용할 수 있는지도 설명해주세요.
</code></pre>
<p>모델의 일반 지식을 평가하기보다 검색한 공식 문서를 읽고 런타임 코드 생성의 지원 여부를 판정하는지 확인했습니다. 이 한 번의 결과를 장비의 평균 성능이나 다른 질문의 응답 품질로 일반화하지는 않습니다.</p>
<h2>검색 완료와 첫 응답 사이의 대기 시간</h2>
<p>요청 처리 단계별 기록을 정리하겠습니다. <a href="https://gist.github.com/rkttu/805dd58e333b7e51b10326168a484c2d">샘플 코드</a>의 상태 메시지는 입력 처리 시작을 기준으로 경과 시간을 표시하고, TTFT는 Edge0 요청을 시작하는 별도 시각을 기준으로 계산합니다.</p>
<h3>질문 변환과 검색에 걸린 약 2.6초</h3>
<p>실험 당시 한국어 안내문을 사용한 로그에서는 다음과 같은 순서로 검색을 마쳤습니다. 현재 Gist는 같은 안내를 영어로 표시합니다.</p>
<pre><code class="language-text">[   0.0s] 한국어 질문 정규화
[   1.3s] 영어 검색 질의 생성 완료
[   1.3s] Microsoft Learn 검색
[   2.6s] 관련 문서 3개 검색 완료

근거 자료
  [1] Native AOT deployment
  [2] Introduction to AOT warnings
  [3] ASP.NET Core support for Native AOT
</code></pre>
<p>약 2.6초에는 한국어 질문 정규화, 영어 질의 생성과 Microsoft Learn 검색이 포함됩니다. 이 실행에서 해당 구간은 뒤이어 발생한 첫 응답 대기보다 짧았습니다.</p>
<h3>Edge0 요청 이후 기록한 TTFT 53.47초</h3>
<p>검색 결과를 전달한 뒤에는 첫 콘텐츠를 받을 때까지 대기 상태를 출력했습니다.</p>
<pre><code class="language-text">[   2.6s] Edge0-35B에 요청 전달
[   7.6s] Edge0 처리 중, 첫 토큰 대기 5초
[  12.6s] Edge0 처리 중, 첫 토큰 대기 10초
[  17.7s] Edge0 처리 중, 첫 토큰 대기 15초
[  22.7s] Edge0 처리 중, 첫 토큰 대기 20초
[  27.7s] Edge0 처리 중, 첫 토큰 대기 25초
[  32.7s] Edge0 처리 중, 첫 토큰 대기 30초
[  37.7s] Edge0 처리 중, 첫 토큰 대기 35초
[  42.8s] Edge0 처리 중, 첫 토큰 대기 40초
[  47.8s] Edge0 처리 중, 첫 토큰 대기 45초
[  52.8s] Edge0 처리 중, 첫 토큰 대기 50초
[  56.1s] 첫 토큰 수신 (TTFT 53.5초)
</code></pre>
<p>입력 처리 시작부터 첫 콘텐츠 수신까지는 약 56.1초였고 Edge0 요청 기준 TTFT는 53.47초였습니다. 두 값은 시작 시점이 다릅니다.</p>
<p>TTFT에는 클라이언트 처리, 서버 대기열, 토큰화, 프리필과 첫 생성 단계가 함께 들어갈 수 있습니다. 서버 내부 계측이 없으므로 53.47초 전체를 프리필 시간으로 해석하지는 않습니다. 이 기록에서는 Edge0 요청 이후 첫 콘텐츠를 기다리는 구간이 가장 길었습니다.</p>
<h2>공식 문서와 대조한 생성 답변</h2>
<p>모델의 답변에서 핵심 판정을 짚어보겠습니다. 첫 영어 콘텐츠를 받은 뒤 호스트가 문장을 모아 번역하면서 한국어 답변을 출력했습니다. 실험 당시의 생성 결과를 다음과 같이 그대로 옮겼습니다.</p>
<pre><code class="language-text">전문가&gt; 아니요, 네이티브 AOT 애플리케이션에서는
`System.Reflection.Emit`를 사용할 수 없습니다.

네이티브 AOT는 `System.Reflection.Emit`를 포함하는
런타임 코드 생성을 명시적으로 금지합니다 [1].

컴파일러는 `RequiresDynamicCodeAttribute`를 사용하는
메서드에 대해 네이티브 코드를 생성할 수 없습니다.

이러한 경고는 해당 멤버가 AOT와 근본적으로 호환되지
않음을 나타냅니다.

가장 좋은 해결 방법은 네이티브 AOT로 빌드할 때 메서드를
호출하지 않고 AOT와 호환되는 다른 것을 사용하는 것입니다 [2].
</code></pre>
<p>핵심 판정인 <code>System.Reflection.Emit</code> 미지원은 <a href="https://learn.microsoft.com/dotnet/core/deploying/native-aot/#limitations-of-native-aot-deployment">Native AOT 제한 사항</a>과 일치합니다. 개별 AOT 경고의 의미와 대응은 <a href="https://learn.microsoft.com/dotnet/core/deploying/native-aot/fixing-warnings#react-to-aot-warnings">AOT 경고 문서</a>를 기준으로 해당 호출부를 살펴볼 수 있습니다. 생성 답변의 나머지 설명까지 이 한 가지 판정으로 검증한 것으로 보지는 않습니다.</p>
<p>호스트는 위 두 문서와 <a href="https://learn.microsoft.com/aspnet/core/fundamentals/native-aot">ASP.NET Core의 Native AOT 지원 문서</a>를 함께 출력했습니다. 독자는 답변의 출처 번호를 해당 문서와 대조할 수 있습니다.</p>
<h2>콘텐츠 이벤트로 계산한 출력 속도</h2>
<p>실행 로그에 기록한 값을 <a href="https://gist.github.com/rkttu/805dd58e333b7e51b10326168a484c2d">계측 코드</a>의 실제 계산 기준에 따라 해석하면 다음과 같습니다.</p>
<ul>
<li><p><strong>질문 처리와 검색, 약 2.6초</strong>: 입력 처리를 시작한 시점부터 자료 선택까지 걸린 시간을 기록했습니다.</p>
</li>
<li><p><strong>TTFT, 53.47초</strong>: Edge0 요청 기준 시각부터 첫 콘텐츠 수신까지 걸린 시간을 기록했습니다.</p>
</li>
<li><p><strong>총 생성 시간, 82.11초</strong>: Edge0 요청 기준 시각부터 스트림 수신 종료까지 걸린 시간을 기록했습니다.</p>
</li>
<li><p><strong>콘텐츠 이벤트 수, 119개</strong>: 샘플의 <code>completion_tokens</code> 필드가 콘텐츠를 포함한 이벤트를 세었습니다.</p>
</li>
<li><p><strong>첫 응답 이후 시간, 28.64초</strong>: 첫 콘텐츠 수신부터 스트림 수신 종료까지 걸린 시간을 기록했습니다.</p>
</li>
<li><p><strong>이벤트 기준 출력 속도, 약 4.15회/초</strong>: 콘텐츠 이벤트 수 119를 첫 응답 이후 시간 28.64초로 나누어 계산했습니다. 기존 로그에서는 이 값을 <code>tok/s</code>로 표시했습니다.</p>
</li>
</ul>
<p>첫 응답이 시작된 뒤에는 번역한 문장이 점진적으로 나타났습니다. 다만 TTFT는 첫 영어 콘텐츠를 받은 시점까지의 시간이며 첫 한국어 문장이 화면에 나타나는 데에는 문장 완성과 번역 시간이 더해집니다. 총 생성 시간도 한국어 번역과 출력이 모두 끝난 시점까지를 재는 지표는 아닙니다.</p>
<p>이 계측은 같은 구성의 변화를 비교하는 데 사용할 수 있습니다. 다른 모델이나 서버와 토큰 처리율을 비교하려면 실제 토큰 수와 측정 구간을 맞추면 됩니다. 현재 수치만으로 서버의 순수 디코드 성능을 단정하지는 않습니다.</p>
<h2>그라운딩 길이와 캐시 상태의 후속 비교</h2>
<p>입력량과 캐시 상태의 후속 비교 조건을 검토하겠습니다. 별도 실험에서 그라운딩을 약 6.7KB에서 약 1.7KB로 축소했을 때 전체 처리 시간이 약 94초에서 약 48초로 줄었고 핵심 답변을 유지했습니다. <a href="https://rkttu.hashnode.dev/edge0-16gb-mac-overview">1편의 비교 기록</a>과 <a href="https://gist.github.com/rkttu/805dd58e333b7e51b10326168a484c2d">Gist의 입력량 제한</a>을 함께 보면 후속 실험의 변수를 정할 수 있습니다.</p>
<p>긴 입력을 처리하는 비용이 대기 시간에 영향을 줄 수 있지만 앞선 비교는 캐시 상태와 반복 횟수를 통제한 결과가 아닙니다. 실제 원인을 더 좁히려면 다음과 같이 조건을 맞춰 비교할 수 있습니다.</p>
<ol>
<li>같은 질문과 검색 결과를 고정해 기준 실행을 기록합니다.</li>
<li>자료를 재정렬하고 그라운딩 크기를 줄인 뒤 답변의 핵심 근거를 비교합니다.</li>
<li>프리픽스 캐시의 지원 여부와 적용 조건을 확인하고 적용 전후를 측정합니다.</li>
<li>프로세스 시작 직후와 반복 요청에서 캐시 상태를 구분해 기록합니다.</li>
<li>동일한 입력과 생성 길이를 사용해 다른 Apple Silicon 장비에서 반복 측정합니다.</li>
<li>추가 백엔드가 공개되면 같은 요청과 계측 기준으로 비교합니다.</li>
</ol>
<p>이 순서는 앞으로 비교할 항목을 제시합니다. 현재 샘플에 재정렬 모델이나 프리픽스 캐시를 구현했다는 뜻은 아닙니다. 우선 입력 자료를 줄일 때 답변 근거를 유지하는지와 첫 응답 대기 시간이 어떻게 달라지는지를 함께 관찰할 수 있습니다.</p>
<h2>사내 PoC와 다른 백엔드의 확장 조건</h2>
<p>사내 서비스와 다른 백엔드로의 확장 조건을 다루겠습니다. M2 MacBook Air 실험에서는 한 사용자의 질문이 검색, 추론과 번역을 거쳐 끝까지 처리되는지 확인했습니다. <a href="https://github.com/Edge0-AI/Edge0/blob/main/docs/architecture.md">Edge0 아키텍처</a>는 추론 코어와 백엔드를 분리하지만 여러 사용자의 세션을 운영하는 서비스 계층은 별도로 구성할 수 있습니다.</p>
<h3>Mac mini와 Mac Studio의 요청 제어</h3>
<p>장비를 옮기는 후속 PoC에서는 클라이언트와 추론 서버 사이에 인증, 세션, 검색과 정책을 관리하는 호스트를 둘 수 있습니다. 아래 구조는 확장 구상이며 현재 CLI에 구현한 기능을 나타내지는 않습니다.</p>
<pre><code class="language-text">사내 클라이언트
    ↓
사용자 인터페이스와 API 어댑터
    ↓
에이전트 호스트
    ├─ 인증과 세션
    ├─ 문서 검색과 접근 권한
    ├─ 요청 수 제한과 대기열
    └─ 상태 및 응답 이벤트
    ↓
Edge0 서버
</code></pre>
<p><a href="https://github.com/Edge0-AI/Edge0/blob/main/docs/models/edge0-35b.md#http-api">현재 35B 서버 문서</a>는 생성 요청을 FIFO 대기열에서 하나씩 처리한다고 설명합니다. 이 동작을 여러 세션의 토큰 생성을 함께 처리하는 연속 배칭과 구분하면 동시 요청 수와 응답 대기 시간을 판단하기 쉽습니다.</p>
<p>사내 기술 문서 검색, 제품 매뉴얼 질의응답, 운영 절차 안내처럼 범위를 정한 업무를 후속 실험 대상으로 선택할 수 있습니다. 현재 CLI는 인증, 문서별 권한 필터링과 다중 사용자 세션을 구현하지 않았으므로 사내 서비스 구성에서는 해당 계층을 별도로 다룹니다. Responses API 형식이나 AG-UI를 제공하는 어댑터도 같은 후속 범위에 포함됩니다.</p>
<h3>CUDA 백엔드 공개 이후의 비교</h3>
<p><a href="https://github.com/Edge0-AI/Edge0#requirements">Edge0의 공개 지원 범위</a>는 MLX 기반 Apple Silicon을 대상으로 하며 CUDA 백엔드는 로드맵에 포함합니다. 따라서 NVIDIA GPU에서 같은 결과를 얻었다고 해석할 수는 없습니다.</p>
<p>추가 백엔드가 공개되고 호환 API를 제공하면 Python 호스트의 검색과 번역 흐름을 재사용하는 방향으로 검토할 수 있습니다. 동일한 질문, 그라운딩 자료, 생성 길이와 계측 기준을 유지하면 장비와 백엔드 차이에 따른 결과를 비교하기 쉽습니다.</p>
<h2>한정된 업무에서 확인한 로컬 에이전트의 범위</h2>
<p>여기까지 정리하면 16GB 노트북에서 35B급 모델과 공식 문서 검색, 온디바이스 번역을 연결한 에이전트가 한 요청을 끝까지 처리했습니다. 모델에는 문서 해석과 답변 생성을 맡기고 호스트에는 검색과 상태 관리를 맡기는 구성이 성립했습니다.</p>
<p>현재 장비에서 기록한 53.47초의 TTFT는 대화형 사용에 직접 영향을 줍니다. 입력 자료를 줄이고 캐시 상태를 나눠 측정하는 작업을 먼저 비교할 수 있으며 다중 사용자 운영과 다른 백엔드는 후속 검증 범위로 남습니다. 빠른 응답이 중요한 서비스와 대기 시간을 허용하는 기술 문서 실험은 서로 다른 기준으로 평가할 수 있습니다.</p>
<p>전체 실행 코드와 설치 절차는 <a href="https://gist.github.com/rkttu/805dd58e333b7e51b10326168a484c2d">연재 Gist</a>에 있습니다. 한정된 질문과 근거 자료로 재현을 시작하면 모델 크기뿐 아니라 답변의 출처, 첫 출력까지의 시간과 운영 범위를 함께 평가할 수 있습니다.</p>
<p>연재의 다른 글은 다음 순서로 읽을 수 있습니다.</p>
<ol>
<li><a href="https://rkttu.hashnode.dev/edge0-16gb-mac-overview">16GB Mac의 35B 로컬 LLM과 근거 기반 에이전트</a></li>
<li><a href="https://rkttu.hashnode.dev/edge0-setup-microsoft-learn-translation">Microsoft Learn과 Apple Translation 실행 환경</a></li>
<li><a href="https://rkttu.hashnode.dev/edge0-local-rag-agent">Microsoft Learn 검색을 연결한 로컬 RAG 에이전트</a></li>
<li><a href="https://rkttu.hashnode.dev/edge0-streaming-ttft-metrics">스트리밍 응답의 TTFT와 출력 속도 계측</a></li>
<li><strong>현재 글</strong></li>
</ol>
]]></content:encoded></item><item><title><![CDATA[Edge0 연재 4: 스트리밍 응답의 TTFT와 출력 속도 계측]]></title><description><![CDATA[Edge0의 SSE 응답을 받으며 첫 응답 대기 시간과 이후 출력 속도를 측정합니다. 대기 상태 표시, 문장 단위 한국어 번역, 이벤트 수 기반 토큰 추정의 한계를 설명합니다.]]></description><link>https://devwrite.ai/edge0-streaming-ttft-metrics</link><guid isPermaLink="true">https://devwrite.ai/edge0-streaming-ttft-metrics</guid><category><![CDATA[llm]]></category><category><![CDATA[RAG ]]></category><category><![CDATA[apple silicon]]></category><category><![CDATA[microsoft-learn]]></category><dc:creator><![CDATA[Jung-hyun, Nam]]></dc:creator><pubDate>Wed, 16 Sep 2026 00:00:00 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/gql/60adcb82557cc70e51211e5c/5c02f19d-5cd0-41f0-91a4-1f74f5f50a0a.webp" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>2026년 9월 13일 기준으로 <a href="https://gist.github.com/rkttu/805dd58e333b7e51b10326168a484c2d">연재의 Python 샘플</a>은 Edge0의 SSE 응답을 수신하면서 첫 응답 대기 시간과 출력 속도를 기록합니다. 이번 글에서는 <a href="https://rkttu.hashnode.dev/edge0-local-rag-agent">3편</a>에서 만든 그라운딩 프롬프트를 실제 생성 요청으로 연결합니다.</p>
<p>이번 글은 측정 시점, 대기 상태 표시, 작업 스레드의 스트림 수신, 문장 단위 한국어 번역, 측정값 해석을 다룹니다. M2 MacBook Air 16GB 실험에서 첫 응답까지 수십 초를 기다렸으므로 생성 전후의 시간을 나누어 기록했습니다.</p>
<p>측정값의 정의부터 살펴보겠습니다. 서버 응답을 받는 코드와 화면 출력을 분리한 뒤 생성 문장을 번역하고 마지막에 지표를 출력하는 순서로 설명합니다. 전체 프로그램은 Gist의 <code>microsoft_expert_agent.py</code>를 기준으로 사용합니다.</p>
<p>아래 계측은 다음 범위에서 해석합니다.</p>
<blockquote>
<p>공개 자료는 2026년 9월 13일에 확인했습니다. <code>Edge0-35B-A3B-preview</code>와 공개 스트리밍 인터페이스를 전제로 합니다. 샘플은 클라이언트가 관찰한 시간과 콘텐츠 이벤트 수를 기록하며 서버 내부의 프리필, 디코드, 대기 시간을 각각 계측하지는 않습니다.</p>
</blockquote>
<h2>첫 응답과 스트림 종료를 기준으로 한 측정값</h2>
<p>샘플에서 기록하는 시간의 범위를 정리하겠습니다. <a href="https://gist.github.com/rkttu/805dd58e333b7e51b10326168a484c2d">Gist의 <code>StreamStats</code></a>는 요청을 처리할 작업 스레드를 시작하기 직전에 기준 시각을 저장합니다. 이후 처음으로 비어 있지 않은 콘텐츠를 받은 시점과 스트림 수신을 끝낸 시점을 기록합니다.</p>
<ul>
<li><p><strong>TTFT</strong>: 요청 기준 시각부터 첫 콘텐츠를 수신하기까지 걸린 시간을 잽니다. 클라이언트에서 관찰한 첫 출력 대기 시간을 나타냅니다.</p>
</li>
<li><p><strong>총 생성 시간</strong>: 요청 기준 시각부터 스트림 수신이 끝날 때까지 걸린 시간을 잽니다. 검색 시간은 포함하지 않으며 한국어 번역이 모두 끝나는 시점까지 측정하지 않습니다.</p>
</li>
<li><p><strong>생성량</strong>: 콘텐츠가 있는 SSE 이벤트 수를 셉니다. 현재 전송 동작을 전제로 이 값을 토큰 수의 추정치로 사용합니다.</p>
</li>
<li><p><strong>첫 응답 이후 시간</strong>: 첫 콘텐츠를 받은 시점부터 스트림 수신이 끝날 때까지 걸린 시간을 잽니다. 네트워크 수신과 종료 처리에 걸리는 시간도 포함합니다.</p>
</li>
<li><p><strong>출력 속도</strong>: 생성량을 첫 응답 이후 시간으로 나눕니다. 콘텐츠 이벤트를 기준으로 처리율을 계산합니다.</p>
</li>
</ul>
<h3>시각과 생성량을 저장하는 객체</h3>
<p>기존 샘플의 필드명과 계산식을 유지한 측정 객체는 다음과 같습니다.</p>
<pre><code class="language-python">from dataclasses import dataclass


@dataclass
class StreamStats:
    request_started: float = 0.0
    first_token_at: float | None = None
    done_at: float | None = None
    completion_tokens: int = 0

    @property
    def ttft(self) -&gt; float | None:
        if self.first_token_at is None:
            return None

        return self.first_token_at - self.request_started

    @property
    def total_generation_time(self) -&gt; float | None:
        if self.done_at is None:
            return None

        return self.done_at - self.request_started

    @property
    def decode_time(self) -&gt; float | None:
        if self.first_token_at is None or self.done_at is None:
            return None

        return self.done_at - self.first_token_at

    @property
    def output_tokens_per_second(self) -&gt; float | None:
        duration = self.decode_time

        if not duration or duration &lt;= 0:
            return None

        return self.completion_tokens / duration
</code></pre>
<p>TTFT에는 스레드 시작, HTTP 처리, 서버 대기열, 토큰화, 프리필과 첫 생성 단계의 시간이 함께 들어갈 수 있습니다. <code>decode_time</code>이라는 필드명도 서버 내부의 순수 디코드 시간만을 의미하지는 않습니다.</p>
<h2>첫 응답을 기다리는 동안의 상태 표시</h2>
<p>대기 중 표시할 상태를 짚어보겠습니다. 첫 출력이 늦어지면 사용자는 요청이 진행 중인지 알기 어렵습니다. <a href="https://gist.github.com/rkttu/805dd58e333b7e51b10326168a484c2d">샘플의 <code>Activity</code></a>는 요청 처리 단계와 경과 시간을 터미널에 표시합니다. 모델의 내부 추론 내용 대신 프로그램이 관찰한 상태를 보여 줍니다.</p>
<h3>경과 시간을 붙이는 출력 함수</h3>
<p>상태 메시지를 출력할 때마다 경과 시간을 계산합니다. 전체 실행 파일은 <code>time</code> 모듈을 가져온 상태에서 이 클래스를 사용합니다.</p>
<pre><code class="language-python">class Activity:
    def __init__(self):
        self.started = time.perf_counter()

    def show(self, message: str):
        elapsed = time.perf_counter() - self.started

        print(
            f"[{elapsed:6.1f}s] {message}",
            flush=True,
        )
</code></pre>
<h3>실험 당시의 대기 메시지</h3>
<p>한국어 안내문을 사용한 실행 기록에서는 다음과 같이 대기 시간을 표시했습니다. 현재 Gist의 안내문은 영어이며 질문과 답변에는 한국어를 사용합니다.</p>
<pre><code class="language-text">[   2.6s] Edge0-35B에 요청 전달
[   7.6s] Edge0 처리 중, 첫 토큰 대기 5초
[  12.6s] Edge0 처리 중, 첫 토큰 대기 10초
[  17.7s] Edge0 처리 중, 첫 토큰 대기 15초
</code></pre>
<p>메인 스레드는 첫 콘텐츠를 받기 전까지 약 5초 간격으로 안내를 출력합니다. 이 표시만으로 서버가 내부적으로 어느 단계에 있는지 판단하지는 않습니다.</p>
<h2>작업 스레드에서 수신하는 SSE 응답</h2>
<p><a href="https://github.com/Edge0-AI/Edge0/blob/main/docs/models/edge0-35b.md#http-api">Edge0의 HTTP API</a>는 <code>/v1/chat/completions</code>와 <code>stream: true</code> 요청을 지원합니다. 샘플은 Flask 전송 계층을 사용하며 수신 작업을 별도 스레드에서 처리합니다.</p>
<p>다음 발췌 코드는 응답의 <code>data:</code> 행에서 콘텐츠를 꺼내 큐에 전달합니다. <code>requests</code>, <code>json</code>, <code>queue</code>, <code>time</code>과 서버 주소 등의 상수는 전체 실행 파일에서 정의합니다.</p>
<pre><code class="language-python">def edge0_worker(
    messages: list[dict],
    events: queue.Queue,
):
    try:
        response = requests.post(
            f"{EDGE0_BASE_URL}/v1/chat/completions",
            json={
                "model": EDGE0_MODEL,
                "messages": messages,
                "temperature": 0.0,
                "seed": 42,
                "max_tokens": MAX_TOKENS,
                "stream": True,
            },
            stream=True,
            timeout=600,
        )

        response.raise_for_status()

        for raw_line in response.iter_lines(
            decode_unicode=True,
        ):
            if not raw_line:
                continue

            if not raw_line.startswith("data:"):
                continue

            payload = raw_line[5:].strip()

            if payload == "[DONE]":
                break

            event = json.loads(payload)

            delta = (
                event["choices"][0]
                .get("delta", {})
                .get("content")
                or ""
            )

            if delta:
                events.put(
                    (
                        "token",
                        delta,
                        time.perf_counter(),
                    )
                )

        events.put(
            (
                "done",
                None,
                time.perf_counter(),
            )
        )

    except Exception as exc:
        events.put(
            (
                "error",
                exc,
                time.perf_counter(),
            )
        )
</code></pre>
<p>서버 문서는 토큰마다 SSE 이벤트를 보내고 마지막에 <code>[DONE]</code>을 전송하는 흐름을 설명합니다. 샘플은 내용이 있는 이벤트만 큐에 넣으므로 프로토콜의 모든 이벤트를 생성량으로 세지는 않습니다.</p>
<p>이 발췌는 정상적인 응답 형식을 전제로 합니다. 전체 Gist에는 JSON과 <code>choices</code>를 읽는 보조 오류 처리가 있지만, 스트림이 끝난 경우와 <code>[DONE]</code>을 받은 경우를 별도로 구분해 검증하는 처리는 포함하지 않습니다. 따라서 결과를 비교할 때에는 응답이 정상적으로 끝났는지도 함께 확인할 수 있습니다.</p>
<h2>메인 스레드의 TTFT 확정과 콘텐츠 전달</h2>
<p>메인 스레드의 수신 시각 처리를 확인하겠습니다. <a href="https://gist.github.com/rkttu/805dd58e333b7e51b10326168a484c2d">Gist의 <code>stream_edge0_with_progress()</code></a>는 1초 단위로 이벤트를 기다리고 첫 콘텐츠 이벤트가 오면 수신 시각을 저장합니다.</p>
<p>다음 함수는 상태 표시와 콘텐츠 전달, 종료 및 오류 처리를 연결합니다.</p>
<pre><code class="language-python">def stream_edge0_with_progress(
    messages: list[dict],
    activity: Activity,
    stats: StreamStats,
):
    events = queue.Queue()

    worker = threading.Thread(
        target=edge0_worker,
        args=(messages, events),
        daemon=True,
    )

    stats.request_started = time.perf_counter()
    worker.start()

    last_progress = 0

    while True:
        try:
            kind, value, event_time = events.get(
                timeout=1.0
            )

        except queue.Empty:
            if stats.first_token_at is None:
                waited = int(
                    time.perf_counter()
                    - stats.request_started
                )

                if (
                    waited &gt;= 5
                    and waited - last_progress &gt;= 5
                ):
                    activity.show(
                        "Edge0 처리 중, "
                        f"첫 토큰 대기 {waited}초"
                    )

                    last_progress = waited

            continue

        if kind == "token":
            stats.completion_tokens += 1

            if stats.first_token_at is None:
                stats.first_token_at = event_time

                activity.show(
                    "첫 토큰 수신 "
                    f"(TTFT {stats.ttft:.1f}초)"
                )

            yield value

        elif kind == "done":
            stats.done_at = event_time
            break

        elif kind == "error":
            stats.done_at = event_time
            raise value
</code></pre>
<p><code>completion_tokens</code>는 <code>token</code> 이벤트를 받을 때마다 1씩 증가합니다. 현재 서버의 토큰별 전송을 가정한 가벼운 추정이며 토크나이저로 다시 센 정확한 생성 토큰 수와 같다고 보장하지는 않습니다. 전송 계층이 여러 토큰을 묶거나 빈 콘텐츠를 포함하면 차이가 발생할 수 있습니다.</p>
<p>서버를 비교하는 벤치마크에서는 서버가 제공하는 사용량이나 같은 토크나이저로 센 토큰 수를 기준으로 사용할 수 있습니다. 이 샘플의 값은 우선 동일한 구성에서 입력량과 대기 시간의 변화를 비교하는 데 사용합니다.</p>
<h2>영어 문장을 모은 뒤 수행하는 한국어 번역</h2>
<p>영어 스트림의 작은 조각을 바로 번역기에 전달하면 문맥을 잃기 쉽습니다. <a href="https://gist.github.com/rkttu/805dd58e333b7e51b10326168a484c2d">전체 샘플</a>은 콘텐츠를 버퍼에 모으고 문장 경계로 판단한 부분을 Apple Translation에 전달합니다.</p>
<h3>구두점을 기준으로 나누는 문장 버퍼</h3>
<p>다음 함수는 문장으로 판단한 문자열 목록과 남은 버퍼를 반환합니다. 전체 파일은 앞에서 <code>re</code> 모듈을 가져옵니다.</p>
<pre><code class="language-python">SENTENCE_PATTERN = re.compile(
    r'(.+?[.!?](?:["\')\]]+)?)'
    r'(?:\s+|$)',
    re.DOTALL,
)


def pop_complete_sentences(
    buffer: str,
) -&gt; tuple[list[str], str]:
    sentences = []
    last_end = 0

    for match in SENTENCE_PATTERN.finditer(buffer):
        sentences.append(
            match.group(1).strip()
        )

        last_end = match.end()

    if not sentences:
        return [], buffer

    return (
        sentences,
        buffer[last_end:],
    )
</code></pre>
<p>이 정규식은 구두점 뒤의 공백이나 현재 버퍼의 끝을 경계로 취급합니다. 약어, 소수점, 코드 표기와 아직 도착하지 않은 후속 조각까지 고려하는 완전한 문장 분리기는 아닙니다. 응답이 끝난 뒤 남은 버퍼도 번역하도록 전체 루프에서 처리합니다.</p>
<h3>생성 시점과 한국어 표시 시점의 차이</h3>
<p>한국어 출력은 문장 단위로 갱신합니다. 첫 영어 콘텐츠를 받은 뒤에도 문장 버퍼를 채우고 번역하는 시간이 추가되므로 TTFT와 사용자가 처음 한국어 답변을 읽는 시점은 다릅니다.</p>
<p>작업 스레드는 수신 시각을 기록하고 메인 스레드는 번역과 출력을 처리합니다. 따라서 측정 객체의 <code>done_at</code>은 스트림 수신 종료를 가리키며 한국어 번역과 화면 출력 전체가 끝난 시각을 의미하지 않습니다.</p>
<h2>측정값 출력과 UI 확장 범위</h2>
<p>측정값 출력과 UI 연결 범위를 다루겠습니다. <a href="https://gist.github.com/rkttu/805dd58e333b7e51b10326168a484c2d">Gist의 <code>print_metrics()</code></a>는 마지막 지표 출력을 담당합니다. 메인 루프는 질문 번역, 검색, 그라운딩 구성, Edge0 수신, 문장 번역을 거친 뒤 이 함수를 호출합니다.</p>
<p>기존 샘플은 다음과 같은 이름과 단위로 결과를 출력합니다.</p>
<pre><code class="language-python">def print_metrics(
    stats: StreamStats,
):
    print()
    print("측정")

    if stats.ttft is not None:
        print(
            f"  TTFT              "
            f"{stats.ttft:.2f}초"
        )

    if stats.total_generation_time is not None:
        print(
            f"  총 생성 시간       "
            f"{stats.total_generation_time:.2f}초"
        )

    print(
        f"  생성 토큰 수       "
        f"{stats.completion_tokens}"
    )

    if stats.decode_time is not None:
        print(
            f"  첫 토큰 이후 시간  "
            f"{stats.decode_time:.2f}초"
        )

    if stats.output_tokens_per_second is not None:
        print(
            f"  출력 속도          "
            f"{stats.output_tokens_per_second:.2f} tok/s"
        )
</code></pre>
<p>출력 문구의 <code>생성 토큰 수</code>와 <code>tok/s</code>는 앞에서 설명한 콘텐츠 이벤트 기반 추정을 가리킵니다. 서로 다른 서버나 토크나이저와 수치를 비교할 때에는 이 차이를 반영할 수 있습니다.</p>
<p>이 상태 표시는 이후 웹 UI를 연결할 때에도 사용할 수 있습니다. 실행 시작과 종료, 검색 중 상태, 응답 콘텐츠를 이벤트로 변환하는 어댑터를 추가하면 됩니다. AG-UI 같은 프로토콜과의 연결은 후속 설계 범위로 남아 있으며 현재 CLI에서는 해당 프로토콜을 구현하지 않았습니다.</p>
<h2>첫 출력 대기와 이후 처리율의 분리</h2>
<p>여기까지 정리하면 샘플은 첫 콘텐츠 수신까지의 시간과 이후 스트림 수신 시간을 나누어 기록합니다. 작업 스레드가 응답을 받는 동안 메인 스레드는 대기 상태를 표시하고 영어 문장을 한국어로 번역합니다.</p>
<p>현재 구성에서는 그라운딩 길이와 첫 응답 대기 시간이 사용 경험에 직접 영향을 줍니다. 토크나이저 기반 생성량 측정과 UI 프로토콜 연결은 후속 과제로 남깁니다. <a href="https://rkttu.hashnode.dev/edge0-real-benchmark-and-poc">5편</a>에서는 TTFT 53.47초와 이벤트 기반 출력 속도 약 4.15회/초를 기록한 실행 결과를 해석합니다.</p>
<p>연재의 다른 글은 다음 순서로 읽을 수 있습니다.</p>
<ol>
<li><a href="https://rkttu.hashnode.dev/edge0-16gb-mac-overview">16GB Mac의 35B 로컬 LLM과 근거 기반 에이전트</a></li>
<li><a href="https://rkttu.hashnode.dev/edge0-setup-microsoft-learn-translation">Microsoft Learn과 Apple Translation 실행 환경</a></li>
<li><a href="https://rkttu.hashnode.dev/edge0-local-rag-agent">Microsoft Learn 검색을 연결한 로컬 RAG 에이전트</a></li>
<li><strong>현재 글</strong></li>
<li><a href="https://rkttu.hashnode.dev/edge0-real-benchmark-and-poc">M2 Air 16GB 실측 결과와 사내 PoC 확장 조건</a></li>
</ol>
]]></content:encoded></item><item><title><![CDATA[Edge0 연재 3: Microsoft Learn 검색을 연결한 로컬 RAG 에이전트]]></title><description><![CDATA[한국어 질문 정규화, Apple Translation 호출, Microsoft Learn 검색을 Python으로 연결합니다. 근거 자료의 수와 길이를 제한하고 최근 대화만 요청에 포함하는 RAG 구성을 설명합니다.]]></description><link>https://devwrite.ai/edge0-local-rag-agent</link><guid isPermaLink="true">https://devwrite.ai/edge0-local-rag-agent</guid><category><![CDATA[llm]]></category><category><![CDATA[RAG ]]></category><category><![CDATA[apple silicon]]></category><category><![CDATA[microsoft-learn]]></category><dc:creator><![CDATA[Jung-hyun, Nam]]></dc:creator><pubDate>Tue, 15 Sep 2026 00:00:00 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/gql/60adcb82557cc70e51211e5c/81f2dcb7-d8f5-4e36-8b4f-3c47551edb5b.webp" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>2026년 9월 13일 기준으로 <a href="https://gist.github.com/rkttu/805dd58e333b7e51b10326168a484c2d">샘플 Gist</a>는 Edge0 서버, Microsoft Learn CLI, Apple Translation을 Python으로 연결하는 코드를 제공합니다. <a href="https://rkttu.hashnode.dev/edge0-setup-microsoft-learn-translation">2편</a>에서 준비한 실행 환경을 바탕으로 이번 글에서는 검색 자료를 모델 입력으로 만드는 부분을 설명합니다.</p>
<p>이번 글에서는 호스트와 모델의 역할 분담, 질문 정규화와 번역, 검색 결과 선택, 그라운딩 프롬프트와 대화 문맥 관리를 다룹니다. 호스트가 검색 순서를 결정하고 모델은 전달받은 자료를 읽어 답을 구성합니다.</p>
<p>데이터 구조와 입력 처리부터 살펴보겠습니다. 검색한 구절에 출처 번호를 붙이고 현재 질문과 함께 전달한 뒤 후속 질문에 필요한 문맥을 구성합니다. 스트리밍 요청과 성능 계측은 4편에서 다룹니다.</p>
<p>본문의 코드와 공개 버전은 다음 범위로 구분합니다.</p>
<blockquote>
<p>공개 자료는 2026년 9월 13일에 확인했습니다. 본문에서는 RAG 흐름을 설명하기 위해 코드를 발췌하고 전체 실행 파일의 일부 보조 처리를 생략합니다. <code>Edge0-35B-A3B-preview</code>의 동작과 외부 도구의 응답 형식은 이후 달라질 수 있습니다.</p>
</blockquote>
<h2>검색과 문맥 구성을 맡는 Python 호스트</h2>
<p>호스트가 담당하는 범위를 정리하겠습니다. <a href="https://gist.github.com/rkttu/805dd58e333b7e51b10326168a484c2d">전체 Python 코드</a>에서 호스트는 입력을 정규화하고 번역한 뒤 Microsoft Learn을 검색합니다. 검색 결과의 URL 중복을 제거하고 자료의 길이를 제한하며 최근 대화를 요청에 포함합니다.</p>
<p>모델에 맡기는 작업은 질문과 문서의 관계 파악, 답변에 사용할 근거 선택, 영어 답변 생성으로 좁힙니다. 제공한 자료로 사실을 확인할 수 없으면 부족하다고 답하도록 프롬프트에 명시합니다.</p>
<p>검색 결과는 제목, URL, 본문을 담는 <code>Source</code> 객체로 관리합니다. 입력량을 제한하는 상수도 함께 정의합니다.</p>
<pre><code class="language-python">from dataclasses import dataclass


@dataclass
class Source:
    title: str
    url: str
    content: str

MAX_SOURCES = 3
MAX_SOURCE_CHARS = 1800
</code></pre>
<p><code>MAX_SOURCE_CHARS</code>로 각 검색 구절의 문자 수를 제한합니다. 호스트가 출처 제목, URL, 시스템 프롬프트와 대화 기록을 이 한도 밖에서 추가하므로 전체 요청 크기는 별도로 계산할 수 있습니다.</p>
<h2>간접 의문문을 직접 의문문으로 바꾸는 규칙</h2>
<p>한국어 질문 정규화는 <a href="https://gist.github.com/rkttu/805dd58e333b7e51b10326168a484c2d">Gist의 <code>normalize_korean_question()</code></a>에서 처리합니다. 생성 여부를 묻는 질문이 번역 과정에서 생성 방법을 묻는 요청으로 바뀌는 사례를 줄이기 위해 정해진 문형을 변환합니다.</p>
<p>다음 함수는 네 가지 패턴에 맞는 문장을 직접 의문문과 후속 요청으로 나눕니다.</p>
<pre><code class="language-python">import re


def make_followup(action: str) -&gt; str:
    if action == "알려주세요":
        return "그 여부도 알려주세요."

    if action == "확인해주세요":
        return "그 여부도 확인해주세요."

    return "그 여부도 설명해주세요."


def normalize_korean_question(text: str) -&gt; str:
    suffix = (
        r"\s*(?:함께\s*)?"
        r"(설명해주세요|알려주세요|확인해주세요)"
        r"\.?$"
    )

    patterns = [
        (
            rf"^(.*)할 수 있는지도{suffix}",
            lambda m:
                f"{m.group(1)}할 수 있습니까? "
                f"{make_followup(m.group(2))}",
        ),
        (
            rf"^(.*)되는지도{suffix}",
            lambda m:
                f"{m.group(1)}됩니까? "
                f"{make_followup(m.group(2))}",
        ),
        (
            rf"^(.*)하는지도{suffix}",
            lambda m:
                f"{m.group(1)}합니까? "
                f"{make_followup(m.group(2))}",
        ),
        (
            rf"^(.*)필요한지도{suffix}",
            lambda m:
                f"{m.group(1)}필요합니까? "
                f"{make_followup(m.group(2))}",
        ),
    ]

    for pattern, replacement in patterns:
        match = re.match(pattern, text)

        if match:
            return replacement(match)

    return text
</code></pre>
<p>패턴이 일치하지 않으면 입력을 그대로 반환합니다. 새로운 문형을 추가할 때에는 원문과 변환 결과, 영어 번역을 함께 비교하면 질문의 의미가 유지되는지 확인할 수 있습니다.</p>
<h2>Swift CLI로 전달하는 영어 번역 요청</h2>
<p>번역 호출은 Python의 하위 프로세스로 분리합니다. <a href="https://developer.apple.com/documentation/translation/translationsession/init%28installedsource%3Atarget%3Apreferredstrategy%3A%29">Apple Translation 초기화 API</a>를 감싼 <code>apple_translate</code> 실행 파일은 2편에서 준비했습니다.</p>
<p>다음 코드는 입력을 구두점 기준으로 나누고 각 구간을 정규화한 뒤 영어로 번역합니다.</p>
<pre><code class="language-python">import subprocess


TRANSLATOR = "./apple_translate"


def run_process(args: list[str]) -&gt; str:
    result = subprocess.run(
        args,
        check=True,
        capture_output=True,
        text=True,
    )

    return result.stdout.strip()


def translate(
    text: str,
    source: str,
    target: str,
) -&gt; str:
    return run_process([
        TRANSLATOR,
        source,
        target,
        text,
    ])

def split_korean_input(text: str) -&gt; list[str]:
    return [
        part.strip()
        for part in re.split(
            r"(?&lt;=[?!])\s+|(?&lt;=\.)\s+",
            text,
        )
        if part.strip()
    ]

def translate_question_to_english(
    question: str,
) -&gt; str:
    translated = []

    for segment in split_korean_input(question):
        normalized = normalize_korean_question(segment)

        english = translate(
            normalized,
            "ko",
            "en",
        )

        translated.append(english)

    return " ".join(translated)
</code></pre>
<p>이 분할 함수는 물음표, 느낌표, 마침표 뒤의 공백을 기준으로 동작합니다. 약어와 제품명에 포함된 구두점까지 구별하는 문장 분석기는 아니므로 복잡한 입력에서는 분할 결과를 확인할 수 있습니다.</p>
<p>본문의 <code>translate_question_to_english()</code>는 흐름을 설명하기 위해 영어 문자열만 반환합니다. Gist의 전체 실행 파일은 원문, 정규화 결과, 영어 번역을 담은 추적 정보도 함께 반환하므로 전체 프로그램을 실행할 때에는 Gist 파일을 기준으로 사용합니다.</p>
<h2>중복 URL과 긴 검색 구절의 제한</h2>
<p>Microsoft Learn 검색 결과를 선택하는 과정을 짚어보겠습니다. <a href="https://github.com/MicrosoftDocs/mcp#-microsoft-learn-cli">Learn CLI</a>의 <code>--json</code> 옵션으로 결과를 받은 뒤 URL과 본문이 있는 항목만 선택합니다.</p>
<p>검색 함수는 같은 URL을 한 번만 사용하고 최대 세 개의 구절을 반환합니다.</p>
<pre><code class="language-python">import json


def search_microsoft_learn(
    query_text: str,
) -&gt; list[Source]:
    raw = run_process([
        "mslearn",
        "search",
        query_text,
        "--json",
    ])

    data = json.loads(raw)

    results = (
        data.get("results")
        or data.get("value")
        or []
    )

    sources = []
    seen_urls = set()

    for item in results:
        url = (
            item.get("contentUrl")
            or item.get("url")
            or item.get("href")
            or ""
        )

        if not url or url in seen_urls:
            continue

        content = (
            item.get("content")
            or item.get("snippet")
            or item.get("description")
            or ""
        ).strip()

        if not content:
            continue

        seen_urls.add(url)

        sources.append(
            Source(
                title=item.get(
                    "title",
                    "(untitled)",
                ),
                url=url,
                content=content[:MAX_SOURCE_CHARS],
            )
        )

        if len(sources) &gt;= MAX_SOURCES:
            break

    return sources
</code></pre>
<p>여러 필드명을 확인하는 처리는 샘플에서 예상하는 JSON 형식에 대응합니다. 모든 응답 형식을 지원하는 검증 계층으로 보지는 않습니다. 관련 구절이 없으면 전체 실행 파일은 해당 질문의 생성을 진행하지 않고 검색 결과가 없다는 안내를 출력합니다.</p>
<p>검색 결과 전체를 그대로 넣는 대신 질문에 필요한 구절을 사용하면 입력량을 줄일 수 있습니다. 이 샘플은 별도의 재정렬 모델을 사용하지 않으므로 결과 순서에 따른 선택과 문자 수 제한의 영향을 함께 관찰합니다.</p>
<h2>출처 번호와 근거 범위를 담은 프롬프트</h2>
<p>출처 번호와 답변 범위를 전달하는 프롬프트를 다루겠습니다. <a href="https://gist.github.com/rkttu/805dd58e333b7e51b10326168a484c2d">Gist의 <code>build_grounding()</code>과 <code>build_user_prompt()</code></a>가 각 자료에 제목과 URL을 포함해 모델이 답변에 출처 번호를 붙일 수 있도록 구성합니다.</p>
<h3>현재 질문과 함께 전달하는 참고 자료</h3>
<p>선택한 검색 구절을 번호가 있는 참고 자료로 묶고 현재 질문 앞에 배치합니다.</p>
<pre><code class="language-python">def build_grounding(
    sources: list[Source],
) -&gt; str:
    blocks = []

    for index, source in enumerate(
        sources,
        start=1,
    ):
        blocks.append(
            f"[{index}] {source.title}\n"
            f"URL: {source.url}\n\n"
            f"{source.content}"
        )

    return "\n\n---\n\n".join(blocks)

def build_user_prompt(
    question: str,
    sources: list[Source],
) -&gt; str:
    grounding = build_grounding(sources)

    return f"""
Microsoft Learn references:

&lt;references&gt;
{grounding}
&lt;/references&gt;

Question:
{question}

Answer the question using the references above.
""".strip()
</code></pre>
<p>자료와 질문을 구분하면 호스트가 어떤 근거를 전달했는지 확인하기 쉽습니다. 다만 <code>&lt;references&gt;</code> 태그 자체가 자료의 신뢰성이나 모델의 지시 준수를 보장하지는 않습니다.</p>
<h3>근거 부족과 출처 표기를 지정한 시스템 프롬프트</h3>
<p>시스템 프롬프트는 자료가 뒷받침하는 사실을 우선 사용하고 확인할 수 없는 사실은 부족하다고 밝히도록 지정합니다.</p>
<pre><code class="language-python">SYSTEM_PROMPT = """
You are a Microsoft technology expert.

Answer using the supplied Microsoft Learn references
as the primary source of factual information.

Rules:
- Prefer facts explicitly supported by the references.
- If the references do not establish a fact, say so.
- Do not invent API names, product behavior, limits,
  or version details.
- Ignore unrelated search results.
- Use short plain-text paragraphs.
- Cite supporting references using [1], [2], [3].
""".strip()
</code></pre>
<p>이 규칙으로 모델의 답변 방향을 제한합니다. 생성한 인용 번호와 실제 근거의 일치 여부는 출력한 출처를 대조해 확인할 수 있습니다.</p>
<h2>최근 두 턴으로 제한하는 요청 문맥</h2>
<p>후속 질문에 포함하는 대화 문맥을 확인하겠습니다. <a href="https://gist.github.com/rkttu/805dd58e333b7e51b10326168a484c2d">전체 코드</a>는 직전 주제를 검색 질의의 보조 정보로 사용합니다. 이전 그라운딩 자료를 대화 기록에 추가하지 않고 사용자 질문과 모델의 영어 답변을 기록합니다.</p>
<p>다음 함수는 가장 최근 사용자 질문을 찾아 현재 질문과 함께 검색 질의를 구성합니다.</p>
<pre><code class="language-python">MAX_HISTORY_TURNS = 2

def make_search_query(
    current_question: str,
    history: list[dict],
) -&gt; str:
    previous_user = None

    for message in reversed(history):
        if message["role"] == "user":
            previous_user = message["content"]
            break

    if previous_user is None:
        return current_question

    return (
        f"Previous topic: {previous_user}\n"
        f"Current question: {current_question}"
    )
</code></pre>
<p>모델 요청을 만들 때에는 <code>history[-MAX_HISTORY_TURNS * 2:]</code>로 최근 두 턴의 질문과 답변만 선택합니다. 현재 질문의 그라운딩 자료는 해당 요청에만 추가하므로 이전 검색 구절이 요청마다 누적되는 것을 피할 수 있습니다.</p>
<p>이 설정은 모델에 보내는 대화 문맥을 제한합니다. 전체 샘플의 <code>history</code> 리스트는 세션 동안 질문과 답변을 계속 보관하며 <code>/clear</code> 명령으로 비웁니다. 최근 두 턴만 메모리에 저장하는 구현과는 구분됩니다.</p>
<h2>입력량과 답변 근거를 함께 관리하는 흐름</h2>
<p>여기까지 정리하면 Python 호스트는 한국어 질문을 영어 검색 질의로 바꾸고 관련 구절을 선택해 현재 요청의 근거로 구성합니다. 출처 번호와 근거 부족 응답 규칙을 함께 전달하며 모델에 보내는 과거 대화는 최근 두 턴으로 제한합니다.</p>
<p>현재 입력량에는 검색 결과의 수, 구절 길이와 대화 문맥이 직접 영향을 줍니다. 검색 재정렬과 더 정교한 문장 정규화는 후속 과제로 남깁니다. <a href="https://rkttu.hashnode.dev/edge0-streaming-ttft-metrics">4편</a>에서는 준비한 프롬프트를 Edge0 서버에 전달하고 첫 응답 대기 시간과 이후 출력 속도를 측정합니다.</p>
<p>연재의 다른 글은 다음 순서로 읽을 수 있습니다.</p>
<ol>
<li><a href="https://rkttu.hashnode.dev/edge0-16gb-mac-overview">16GB Mac의 35B 로컬 LLM과 근거 기반 에이전트</a></li>
<li><a href="https://rkttu.hashnode.dev/edge0-setup-microsoft-learn-translation">Microsoft Learn과 Apple Translation 실행 환경</a></li>
<li><strong>현재 글</strong></li>
<li><a href="https://rkttu.hashnode.dev/edge0-streaming-ttft-metrics">스트리밍 응답의 TTFT와 출력 속도 계측</a></li>
<li><a href="https://rkttu.hashnode.dev/edge0-real-benchmark-and-poc">M2 Air 16GB 실측 결과와 사내 PoC 확장 조건</a></li>
</ol>
]]></content:encoded></item><item><title><![CDATA[Edge0 연재 2: Microsoft Learn과 Apple Translation 실행 환경]]></title><description><![CDATA[Edge0 서버, Microsoft Learn CLI, Apple Translation을 연결할 실행 환경을 구성합니다. 가상 환경 재활성화, 번역 API 조건, 한국어 질문 정규화의 이유를 설명합니다.]]></description><link>https://devwrite.ai/edge0-setup-microsoft-learn-translation</link><guid isPermaLink="true">https://devwrite.ai/edge0-setup-microsoft-learn-translation</guid><category><![CDATA[llm]]></category><category><![CDATA[RAG ]]></category><category><![CDATA[apple silicon]]></category><category><![CDATA[microsoft-learn]]></category><dc:creator><![CDATA[Jung-hyun, Nam]]></dc:creator><pubDate>Mon, 14 Sep 2026 00:00:00 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/gql/60adcb82557cc70e51211e5c/2acda889-5424-43c8-a48a-0dc10b957419.webp" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>2026년 9월 13일 기준으로 이 연재의 샘플은 Edge0-35B, Microsoft Learn CLI, macOS Translation 프레임워크를 사용합니다. <a href="https://rkttu.hashnode.dev/edge0-16gb-mac-overview">1편</a>에서 정한 역할 분담에 따라 추론 서버와 Python 에이전트 호스트를 별도 터미널에서 실행합니다.</p>
<p>이번 글은 Edge0와 모델 설치, 스트리밍 서버 실행, 공식 문서 검색, 한국어와 영어 번역, 질문 정규화를 다룹니다. 전체 파일은 <a href="https://gist.github.com/rkttu/805dd58e333b7e51b10326168a484c2d">샘플 Gist</a>의 <code>README.md</code>, <code>apple_translate.swift</code>, <code>microsoft_expert_agent.py</code>에서 확인할 수 있습니다.</p>
<p>실행 조건과 설치 순서부터 살펴보겠습니다. 첫 번째 터미널에서 서버를 시작한 뒤 검색 도구와 번역 CLI를 준비하고, 두 번째 터미널에서 에이전트를 실행할 수 있는 상태까지 구성합니다.</p>
<p>아래 절차는 다음 공개 버전과 API 조건을 기준으로 설명합니다.</p>
<blockquote>
<p>문서는 2026년 9월 13일에 확인했습니다. <code>Edge0-35B-A3B-preview</code>는 이후 구성이 달라질 수 있습니다. Swift 예제의 <code>TranslationSession(installedSource:target:preferredStrategy:)</code>는 macOS 26.4 이상과 해당 API를 포함한 SDK를 전제로 합니다.</p>
</blockquote>
<h2>Edge0와 35B 모델의 설치 조건</h2>
<p>실험에는 Apple Silicon Mac, Python 3.12, Node.js 22 이상, Xcode Command Line Tools를 사용합니다. 약 23GB의 모델 파일을 저장할 공간과 한국어 및 영어 번역 리소스도 준비합니다. Edge0의 지원 환경과 모델 파일 구성은 <a href="https://github.com/Edge0-AI/Edge0">공식 README</a>에 나와 있습니다.</p>
<h3>저장소와 Python 가상 환경</h3>
<p>작업할 디렉터리에서 저장소를 내려받고 가상 환경을 활성화한 뒤 샘플 의존성을 설치합니다.</p>
<pre><code class="language-bash">git clone https://github.com/Edge0-AI/Edge0.git
cd Edge0

python3.12 -m venv .venv
source .venv/bin/activate

pip install -e '.[dev,fetch]'
pip install flask requests
</code></pre>
<p>이후 명령은 Edge0 저장소 루트를 작업 디렉터리로 사용합니다. <code>flask</code>는 스트리밍 전송에, <code>requests</code>는 Python 호스트의 HTTP 요청에 사용합니다.</p>
<h3>모델 다운로드와 경로 지정</h3>
<p>공식 다운로드 스크립트로 35B 모델을 받은 뒤 현재 셸에 모델 경로를 등록합니다.</p>
<pre><code class="language-bash">python scripts/fetch_models.py \
  --tier edge0-35b \
  --target-dir models

export EDGE0_35B_MODEL="$PWD/models/edge0-35b"
</code></pre>
<p><code>models/edge0-35b/</code>에는 설정, 모델 가중치, 토크나이저와 LoRA 및 프리라우터 어댑터가 함께 들어갑니다. 어댑터를 포함한 디렉터리 전체를 모델 경로로 사용합니다.</p>
<h2>첫 번째 터미널의 스트리밍 서버</h2>
<p>첫 번째 터미널의 서버 실행 절차를 다루겠습니다. Edge0의 <a href="https://github.com/Edge0-AI/Edge0/blob/main/docs/models/edge0-35b.md">35B 모델 문서</a>는 Flask 전송 계층을 통한 SSE 스트리밍과 <code>/healthz</code> 상태 확인 경로를 설명합니다. 이 샘플에서는 접속 주소를 <code>127.0.0.1:8083</code>으로 지정합니다.</p>
<h3>가상 환경 재활성화와 서버 실행</h3>
<p>새 터미널에서는 작업 경로와 가상 환경, 모델 환경 변수를 다시 설정합니다. <code>/path/to/Edge0</code>는 앞에서 저장소를 내려받은 실제 경로로 바꿉니다.</p>
<pre><code class="language-bash">cd /path/to/Edge0
source .venv/bin/activate

export EDGE0_35B_MODEL="$PWD/models/edge0-35b"

edge0 serve edge0-35b \
  --host 127.0.0.1 \
  --port 8083 \
  --flask
</code></pre>
<p>첫 번째 터미널은 서버가 실행되는 동안 유지합니다. 가상 환경을 활성화했던 이전 터미널의 상태가 새 셸에 자동으로 적용되지는 않습니다.</p>
<h3>별도 셸의 상태 확인</h3>
<p>다른 터미널에서 다음 요청으로 서버의 응답을 확인합니다.</p>
<pre><code class="language-bash">curl http://127.0.0.1:8083/healthz
</code></pre>
<p>이 요청이 성공하면 지정한 주소의 HTTP 서버에 접근할 수 있습니다. 실제 생성 동작은 에이전트 질문을 보내는 단계에서 확인합니다.</p>
<h2>Microsoft Learn 검색과 입력 자료 제한</h2>
<p>Microsoft는 <a href="https://github.com/MicrosoftDocs/mcp#-microsoft-learn-cli">Learn MCP 서버와 CLI</a>를 제공합니다. Python 호스트는 <code>mslearn</code>을 하위 프로세스로 실행하고 JSON 결과를 읽습니다. 샘플에서 MCP 전송 계층을 직접 구현하지 않아도 같은 문서 검색 기능을 사용할 수 있습니다.</p>
<h3>CLI 설치와 검색 확인</h3>
<p>Node.js 환경에서 CLI를 설치한 뒤 Native AOT 관련 검색 결과를 확인합니다.</p>
<pre><code class="language-bash">npm install -g @microsoft/learn-cli

mslearn search \
  ".NET NativeAOT Reflection.Emit" \
  --json
</code></pre>
<p>이 검색은 Microsoft Learn 외부 서비스에 질의를 전송합니다. Edge0 추론과 번역을 로컬에서 실행하더라도 검색 단계에는 네트워크 연결을 사용합니다.</p>
<h3>관련 구절의 수와 길이 제한</h3>
<p>샘플은 전체 페이지를 가져오는 대신 검색 결과가 반환한 관련 구절을 사용합니다. <a href="https://gist.github.com/rkttu/805dd58e333b7e51b10326168a484c2d">전체 코드</a>는 다음 상수로 입력량을 제한합니다.</p>
<pre><code class="language-python">MAX_SOURCES = 3
MAX_SOURCE_CHARS = 1800
</code></pre>
<p>최대 세 건을 선택하고 각 구절을 1,800자까지 전달합니다. 이 한도는 문자 수이며 KB나 모델 토큰 수와 같지 않습니다. 질문에 필요한 근거를 유지하면서 한도를 조절한 뒤 응답 품질과 대기 시간을 비교할 수 있습니다.</p>
<h2>Apple Translation을 호출하는 Swift CLI</h2>
<p>번역 계층의 API 조건을 확인하겠습니다. 예제는 <a href="https://developer.apple.com/documentation/translation/translationsession/init%28installedsource%3Atarget%3Apreferredstrategy%3A%29">Apple의 TranslationSession 초기화 API</a>를 사용하며 <code>preferredStrategy</code> 인자는 macOS 26.4 이상에서 사용할 수 있습니다. 운영체제와 컴파일 SDK가 이 API를 지원하는 환경에서 다음 코드를 빌드합니다.</p>
<h3>번역 언어와 텍스트를 전달하는 진입점</h3>
<p>다음 소스를 Edge0 저장소 루트의 <code>apple_translate.swift</code>에 저장합니다.</p>
<pre><code class="language-swift">import Foundation
import Translation

@main
struct AppleTranslateCLI {
    static func main() async {
        guard CommandLine.arguments.count &gt;= 4 else {
            fputs(
                "usage: apple_translate &lt;source&gt; &lt;target&gt; &lt;text&gt;\n",
                stderr
            )
            exit(2)
        }

        let source = Locale.Language(
            identifier: CommandLine.arguments[1]
        )

        let target = Locale.Language(
            identifier: CommandLine.arguments[2]
        )

        let text = CommandLine.arguments
            .dropFirst(3)
            .joined(separator: " ")

        do {
            let session = TranslationSession(
                installedSource: source,
                target: target,
                preferredStrategy: .lowLatency
            )

            let response = try await session.translate(text)

            print(response.targetText)
        }
        catch {
            fputs(
                "translation error: \(error)\n",
                stderr
            )
            exit(1)
        }
    }
}
</code></pre>
<p>CLI는 원본 언어, 대상 언어, 번역할 텍스트를 인자로 받고 번역 결과를 표준 출력으로 전달합니다. <code>installedSource</code> 방식은 이미 설치한 언어 리소스를 전제로 합니다.</p>
<h3>컴파일과 첫 번역</h3>
<p>단일 Swift 파일의 <code>@main</code> 진입점을 사용하도록 <code>-parse-as-library</code>를 지정하고 번역을 시험합니다.</p>
<pre><code class="language-bash">xcrun swiftc \
  -parse-as-library \
  apple_translate.swift \
  -o apple_translate

./apple_translate ko en \
  "NativeAOT에서 Reflection.Emit을 사용할 수 있습니까?"
</code></pre>
<p><code>-parse-as-library</code>를 생략하면 단일 파일의 <code>@main</code>과 최상위 코드에 관한 컴파일 오류가 발생할 수 있습니다. <code>TranslationError.Cause.notInstalled</code> 오류가 발생하면 한국어와 영어 번역 리소스의 설치 상태를 확인합니다. 언어 리소스를 설치한 뒤에는 번역을 온디바이스에서 처리합니다.</p>
<h2>질문의 의미를 보존하는 한국어 정규화</h2>
<p>번역 과정에서 발견한 간접 의문문 문제를 짚어보겠습니다. 제가 NLLB 600M, NLLB 1.3B와 Apple Translation을 시험했을 때 생성 여부를 묻는 질문을 생성 방법을 묻는 요청으로 번역하는 사례가 있었습니다. 이 연재에서는 <a href="https://gist.github.com/rkttu/805dd58e333b7e51b10326168a484c2d">샘플의 정규화 함수</a>로 일부 문형을 처리합니다.</p>
<p>실험에 사용한 질문과 번역 사례, 정규화한 문장을 비교하면 다음과 같습니다.</p>
<ul>
<li><p><strong>원래 질문</strong>: “런타임에 새로운 실행 코드를 생성하는지도 함께 설명해주세요.”라고 질문했습니다. 코드의 생성 여부를 묻습니다.</p>
</li>
<li><p><strong>번역 오류 사례</strong>: 번역기는 질문을 “Explain how to generate new executable code at runtime.”으로 옮겼습니다. 생성 여부를 묻던 질문이 생성 방법을 설명해 달라는 요청으로 바뀌었습니다.</p>
</li>
<li><p><strong>정규화 후</strong>: “런타임에 새로운 실행 코드를 생성합니까? 그 여부도 함께 설명해주세요.”로 문장을 바꿨습니다. 직접 의문문으로 생성 여부를 묻습니다.</p>
</li>
</ul>
<p>정규화 함수는 <code>~할 수 있는지도</code>, <code>~되는지도</code>, <code>~하는지도</code>, <code>~필요한지도</code>와 같은 정해진 패턴을 직접 의문문으로 바꿉니다. 정규식에 맞지 않는 문장은 그대로 번역기에 전달합니다. 한국어 문장 전체를 이해하고 고치는 범용 교정 기능으로 사용하지는 않습니다.</p>
<h2>두 번째 터미널의 에이전트 실행 준비</h2>
<p>에이전트 실행에 필요한 파일과 확인 순서를 정리하겠습니다. <a href="https://gist.github.com/rkttu/805dd58e333b7e51b10326168a484c2d">Gist</a>의 <code>microsoft_expert_agent.py</code>를 Edge0 저장소 루트에 저장하고 번역 실행 파일도 같은 위치에 둡니다.</p>
<p>두 번째 터미널에서는 서버를 실행한 터미널과 별도로 가상 환경을 활성화합니다.</p>
<pre><code class="language-bash">cd /path/to/Edge0
source .venv/bin/activate

pip install requests
</code></pre>
<p>실행 전에 다음 순서로 구성 요소를 확인할 수 있습니다.</p>
<ol>
<li>첫 번째 터미널에서 Edge0 서버의 실행 상태를 확인합니다.</li>
<li>두 번째 터미널에서 <code>/healthz</code> 응답을 확인합니다.</li>
<li><code>mslearn search</code>의 JSON 검색 결과를 확인합니다.</li>
<li><code>./apple_translate</code>로 한국어와 영어 번역을 확인합니다.</li>
<li>저장소 루트에서 <code>python microsoft_expert_agent.py</code>를 실행합니다.</li>
</ol>
<p>3편과 4편에서는 전체 에이전트의 코드 중 검색, 프롬프트 구성, 스트리밍과 측정 부분을 나누어 설명합니다.</p>
<h2>독립적으로 확인할 수 있는 세 구성 요소</h2>
<p>여기까지 정리하면 Edge0 서버, Microsoft Learn 검색, Apple Translation을 각각 실행하고 확인할 수 있습니다. Python 호스트는 이 세 구성 요소를 연결해 한국어 질문에 답하는 흐름을 제어합니다.</p>
<p>현재 실행에는 터미널별 가상 환경과 모델 경로, 번역 API의 운영체제 조건이 직접 영향을 줍니다. 검색 결과 재정렬과 더 짧은 그라운딩 자료는 이후 성능 비교 과제로 남깁니다. <a href="https://rkttu.hashnode.dev/edge0-local-rag-agent">3편</a>에서는 질문 정규화부터 검색 결과 선택과 대화 문맥 구성까지 Python 코드로 연결합니다.</p>
<p>연재의 다른 글은 다음 순서로 읽을 수 있습니다.</p>
<ol>
<li><a href="https://rkttu.hashnode.dev/edge0-16gb-mac-overview">16GB Mac의 35B 로컬 LLM과 근거 기반 에이전트</a></li>
<li><strong>현재 글</strong></li>
<li><a href="https://rkttu.hashnode.dev/edge0-local-rag-agent">Microsoft Learn 검색을 연결한 로컬 RAG 에이전트</a></li>
<li><a href="https://rkttu.hashnode.dev/edge0-streaming-ttft-metrics">스트리밍 응답의 TTFT와 출력 속도 계측</a></li>
<li><a href="https://rkttu.hashnode.dev/edge0-real-benchmark-and-poc">M2 Air 16GB 실측 결과와 사내 PoC 확장 조건</a></li>
</ol>
]]></content:encoded></item><item><title><![CDATA[Edge0 연재 1: 16GB Mac의 35B 로컬 LLM과 근거 기반 에이전트]]></title><description><![CDATA[16GB M2 MacBook Air에서 Edge0-35B를 실행한 경험을 바탕으로 공식 문서 검색, 근거 기반 답변, 한국어 번역을 결합한 로컬 에이전트의 설계 방향을 정리합니다.]]></description><link>https://devwrite.ai/edge0-16gb-mac-overview</link><guid isPermaLink="true">https://devwrite.ai/edge0-16gb-mac-overview</guid><category><![CDATA[llm]]></category><category><![CDATA[RAG ]]></category><category><![CDATA[apple silicon]]></category><category><![CDATA[microsoft-learn]]></category><dc:creator><![CDATA[Jung-hyun, Nam]]></dc:creator><pubDate>Sun, 13 Sep 2026 00:00:00 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/gql/60adcb82557cc70e51211e5c/498e6ccf-1307-408a-bf71-96dfe8ff2c48.webp" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>2026년 9월 13일 기준으로 Edge0는 Apple Silicon용 MLX 백엔드와 <code>Edge0-35B-A3B-preview</code> 모델을 공개하고 있습니다. 저는 M2 MacBook Air 16GB에서 이 모델을 실행한 뒤 Microsoft Learn 자료를 근거로 답하는 기술 전문가 에이전트를 구성했습니다.</p>
<p>이 연재는 35B급 모델의 실행 조건, 검색 자료에 따른 답변 변화, 한국어 입출력 구성, 스트리밍 성능 측정, 사내 PoC로 확장할 때의 조건을 다룹니다. 전체 실행 코드는 <a href="https://gist.github.com/rkttu/805dd58e333b7e51b10326168a484c2d">Edge0 Microsoft Technology Expert Agent Gist</a>에 정리했습니다.</p>
<p>첫 글에서는 모델을 실행한 경험부터 살펴보겠습니다. 외부 근거를 제공한 실험과 입력 자료의 길이를 줄인 결과를 비교한 뒤 나머지 연재에서 구현할 에이전트의 구조를 설명하겠습니다.</p>
<p>공개 상태와 측정 범위는 다음 기준으로 구분합니다.</p>
<blockquote>
<p>공개 문서는 2026년 9월 13일에 확인했습니다. 모델은 preview 단계이며 구성과 성능은 이후 달라질 수 있습니다. 실행 시간과 답변 사례는 제가 수행한 개별 실험에서 기록했으며 모든 장비와 질문에 적용되는 성능을 뜻하지 않습니다.</p>
</blockquote>
<h2>SSD에서 필요한 가중치를 읽는 35B 모델</h2>
<p>Edge0의 메모리 사용 방식부터 짚어보겠습니다. <a href="https://github.com/Edge0-AI/Edge0">프로젝트 설명</a>에 따르면 Edge0는 희소 MoE 모델의 전문가 가중치를 SSD에 두고 추론에 필요한 부분을 읽어 옵니다. 따라서 모델 파일 전체를 처음부터 RAM에 적재하는 구성과 메모리 사용 양상이 다릅니다.</p>
<p>공개 모델의 사양과 공식 측정값, 제가 사용한 실험 환경을 항목별로 구분했습니다.</p>
<ul>
<li><p><strong>공개 모델</strong>: <code>Edge0-35B-A3B-preview</code>는 35B급 MoE 구조에 4비트 양자화를 적용합니다.</p>
</li>
<li><p><strong>모델 파일 크기</strong>: SSD에 저장하는 체크포인트가 약 23GB를 차지합니다.</p>
</li>
<li><p><strong>공식 메모리 측정</strong>: 짧은 문맥에서 MLX 할당기의 최대 활성 메모리가 약 2.9GiB를 기록했습니다.</p>
</li>
<li><p><strong>개인 실험 장비</strong>: 이 연재에서는 M2 MacBook Air 16GB를 사용했습니다.</p>
</li>
<li><p><strong>첫 생성 실험</strong>: 특정 입력과 실행 조건에서 128토큰을 생성하는 데 약 43.8초가 걸렸습니다.</p>
</li>
</ul>
<p>공식 메모리 수치는 시스템 전체의 메모리 사용량을 나타내지 않습니다. 운영체제, 토크나이저, 캐시와 문맥 길이에 따른 추가 사용량을 함께 고려할 수 있습니다. 구체적인 가중치 로딩 경로는 <a href="https://github.com/Edge0-AI/Edge0/blob/main/docs/architecture.md">아키텍처 문서</a>에서 설명합니다.</p>
<p>제 장비에서도 모델이 문장을 생성했습니다. 이 결과를 통해 16GB 노트북에서의 실행 가능성을 확인했지만 응답 속도와 답변의 정확성은 각각 평가했습니다.</p>
<h2>외부 근거를 중심으로 바꾼 답변 구성</h2>
<p>질문만 제공하는 zero-shot 실험에서는 C# Native AOT와 Rust의 컴파일 모델을 잘못 설명하는 답변을 확인했습니다. 영어 질문에서도 비슷한 오류가 반복됐습니다. 질문 수를 충분히 늘린 품질 평가를 수행한 결과는 아니므로 이 경험만으로 모델의 전체 성능을 판단하지는 않았습니다.</p>
<p>이에 따라 모델에 사실 지식을 맡기는 범위를 줄였습니다. 제가 답변을 판정할 수 있는 .NET Native AOT와 JIT 질문을 사용하고 <a href="https://learn.microsoft.com/dotnet/core/deploying/native-aot/">Microsoft Learn의 Native AOT 문서</a>를 함께 제공했습니다.</p>
<p>이후 에이전트에서는 역할을 다음과 같이 나눴습니다.</p>
<pre><code class="language-text">Edge0
    질문과 문서의 내용 파악
    관련 근거 선택
    근거에 따른 답변 생성

외부 시스템과 Python 호스트
    공식 문서 검색
    입력 자료 구성
    대화 상태 관리
    한국어 입출력 처리
</code></pre>
<p>모델이 제공받은 문서를 읽고 질문에 맞게 답을 구성하는지에 실험의 초점을 맞췄습니다.</p>
<h2>근거 부족을 표현한 답변 사례</h2>
<p>근거 제공 방식에 따른 답변 변화를 정리하겠습니다. 실험에서는 질문만 전달하는 방식, Microsoft Learn 자료를 함께 전달하는 방식, 제공한 자료의 범위 안에서 답하도록 더 강하게 제한하는 방식을 차례로 비교했습니다. 여기서는 모델에 전달하는 참고 자료를 그라운딩 자료라고 부르겠습니다.</p>
<p>자료를 제공한 뒤에는 모델이 게시 시점의 네이티브 코드 생성과 JIT 사용 여부를 설명했습니다. 런타임 코드 생성과 동적 로딩의 제약도 답변에 반영했습니다. 이 내용은 <a href="https://learn.microsoft.com/dotnet/core/deploying/native-aot/#limitations-of-native-aot-deployment">Native AOT의 제한 사항</a>과 대조했습니다.</p>
<p>그라운딩 자료에 없는 CoreCLR의 Dynamic PGO 세부 사항을 질문했을 때에는 다음 응답을 받았습니다.</p>
<pre><code class="language-text">The supplied reference does not provide enough information.
</code></pre>
<p>해당 응답에서는 근거가 부족하다는 경계를 표현했습니다. 한 번의 응답이 같은 동작을 항상 보장하지는 않지만 이후 프롬프트에 근거 부족을 알리는 규칙을 포함할 이유가 됐습니다.</p>
<h2>잘못된 질문 전제를 판정한 실험</h2>
<p>질문에 오류를 넣었을 때의 반응도 검토하겠습니다. Native AOT가 게시 과정에서 찾지 못한 코드를 런타임 JIT로 생성하고 <code>Reflection.Emit</code>이 이를 보완한다는 설명을 제시했습니다. 모델에는 Microsoft Learn 자료를 사용해 두 주장을 판정하도록 요청했습니다.</p>
<p>모델은 두 주장을 모두 거부했습니다. <a href="https://learn.microsoft.com/dotnet/core/deploying/native-aot/">공식 설명</a>은 Native AOT 앱이 실행 중 JIT 컴파일러를 사용하지 않으며 <code>System.Reflection.Emit</code>과 같은 런타임 코드 생성을 지원하지 않는다고 명시합니다.</p>
<p>이 실험에서는 모델이 질문의 전제를 제공한 자료와 비교해 판정했습니다. 이후 에이전트에서도 출처를 함께 출력하고 답변을 원문과 대조할 수 있도록 구성했습니다.</p>
<h2>입력 자료 길이에 따른 처리 시간 변화</h2>
<p>같은 질문에 제공하는 그라운딩 자료의 양을 줄이면서 전체 처리 시간을 비교했습니다. <a href="https://gist.github.com/rkttu/805dd58e333b7e51b10326168a484c2d">연재의 샘플 코드</a>에서도 검색 결과의 수와 길이를 제한하는 이유가 여기에 있습니다.</p>
<ul>
<li><p><strong>그라운딩 자료 약 6.7KB</strong>: 전체 처리에 약 94초가 걸렸으며 이때의 답변을 비교 기준으로 사용했습니다.</p>
</li>
<li><p><strong>그라운딩 자료 약 3.4KB</strong>: 전체 처리에 약 78초가 걸렸습니다. 자료를 줄인 뒤의 답변을 비교했습니다.</p>
</li>
<li><p><strong>그라운딩 자료 약 1.7KB</strong>: 전체 처리에 약 48초가 걸렸으며 핵심 답변도 유지했습니다.</p>
</li>
</ul>
<p>다만 이 수치는 개별 실행 기록이며 반복 횟수와 캐시 상태를 통제한 벤치마크 결과는 아닙니다. 자료 크기는 바이트 단위이고 모델이 처리하는 입력 토큰 수와도 다릅니다. 이 결과만으로 처리 시간 감소분 전체를 프리필 단축으로 설명할 수는 없습니다.</p>
<p>검색 결과에서 질문과 관련된 구절을 좁히면 모델에 전달하는 입력량을 줄일 수 있습니다. 자료를 지나치게 줄여 핵심 근거를 잃지 않도록 답변 품질과 지연 시간을 함께 비교하는 방향으로 실험을 이어갔습니다.</p>
<h2>검색과 번역을 연결한 에이전트 구조</h2>
<p>최종 샘플의 질문 처리 흐름을 확인하겠습니다. 한국어 질문을 받아 영어로 검색하고 답변을 생성한 뒤 한국어로 번역합니다. <a href="https://gist.github.com/rkttu/805dd58e333b7e51b10326168a484c2d">Gist의 전체 코드</a>는 이 흐름을 Python 호스트에서 제어합니다.</p>
<p>각 구성 요소의 호출 순서는 다음과 같습니다.</p>
<pre><code class="language-text">한국어 질문
    ↓
질문 정규화와 Apple Translation
    ↓
Microsoft Learn 검색
    ↓
관련 구절을 그라운딩 자료로 구성
    ↓
Edge0-35B의 영어 응답 스트리밍
    ↓
문장 단위 Apple Translation
    ↓
한국어 답변과 출처 출력
</code></pre>
<p>Python 호스트가 검색과 상태를 관리하므로 모델의 자율적인 도구 선택 기능에 의존하지 않습니다. 모델에는 문서를 읽고 답을 합성하는 역할을 맡깁니다.</p>
<p>모델 추론과 번역은 Mac에서 처리하지만 Microsoft Learn 검색은 외부 서비스에 질의를 전송합니다. 따라서 이 연재의 로컬 RAG는 인터넷 검색을 포함하며 완전한 오프라인 구성을 뜻하지 않습니다.</p>
<h2>실행 가능성을 바탕으로 좁힌 다음 실험</h2>
<p>여기까지 정리하면 M2 MacBook Air 16GB에서 35B급 모델을 실행하고 공식 문서를 근거로 답을 구성하는 흐름을 확인했습니다. 질문만 제공했을 때의 오류와 자료를 제공한 뒤의 답변 변화를 함께 기록하면서 모델과 호스트의 역할을 나눴습니다.</p>
<p>현재 구성에는 입력 자료의 길이와 첫 응답 대기 시간이 직접 영향을 줍니다. 더 빠른 장비나 다른 백엔드로의 확장은 후속 비교 과제로 남깁니다. <a href="https://rkttu.hashnode.dev/edge0-setup-microsoft-learn-translation">2편</a>에서는 Edge0 서버, Microsoft Learn CLI, Apple Translation을 준비하고 터미널별 가상 환경과 모델 경로를 설정합니다.</p>
<p>연재의 다른 글은 다음 순서로 읽을 수 있습니다.</p>
<ol>
<li><strong>현재 글</strong></li>
<li><a href="https://rkttu.hashnode.dev/edge0-setup-microsoft-learn-translation">Microsoft Learn과 Apple Translation 실행 환경</a></li>
<li><a href="https://rkttu.hashnode.dev/edge0-local-rag-agent">Microsoft Learn 검색을 연결한 로컬 RAG 에이전트</a></li>
<li><a href="https://rkttu.hashnode.dev/edge0-streaming-ttft-metrics">스트리밍 응답의 TTFT와 출력 속도 계측</a></li>
<li><a href="https://rkttu.hashnode.dev/edge0-real-benchmark-and-poc">M2 Air 16GB 실측 결과와 사내 PoC 확장 조건</a></li>
</ol>
]]></content:encoded></item><item><title><![CDATA[netcoredbg 기반 C# 확장의 8개 플랫폼 자동 릴리스 구축기]]></title><description><![CDATA[AI를 활용해 netcoredbg 통합 C# 확장을 Open VSX에 출시한 과정을 기록합니다. 기존 커뮤니티의 기여와 8개 플랫폼 자동 검증, 배포 복구, VS Code OSS 기반 .NET 개발 도구 구상을 다룹니다.]]></description><link>https://devwrite.ai/csharp-netcoredbg-openvsx-release</link><guid isPermaLink="true">https://devwrite.ai/csharp-netcoredbg-openvsx-release</guid><category><![CDATA[C#]]></category><category><![CDATA[dotnet]]></category><category><![CDATA[Open VSX]]></category><category><![CDATA[GitHub Actions]]></category><dc:creator><![CDATA[Jung-hyun, Nam]]></dc:creator><pubDate>Sun, 06 Sep 2026 13:25:17 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/gql/60adcb82557cc70e51211e5c/82d6551e-1881-47d7-9243-d8d33da21816.webp" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>2026년 9월 6일 제가 운영하는 <a href="https://github.com/rkttu/vscode-csharp-autobuild">vscode-csharp-autobuild</a> 저장소에서 <strong>C# (with netcoredbg) 2.148.23001</strong>의 첫 릴리스를 완료했습니다. Windows, Linux, Alpine Linux, macOS의 x64와 ARM64용 패키지를 모두 Open VSX에 게시했고, 공개한 파일의 해시가 검증에 사용한 VSIX와 일치하는지 확인했습니다. <a href="https://github.com/rkttu/vscode-csharp-autobuild/releases/tag/csharp-v2.148.23-netcoredbg-v3.2.0-1092-g9744e1f05186-r1">첫 릴리스</a>는 C# 확장과 netcoredbg의 소스 버전, 플랫폼별 패키지, 검증 기록을 함께 제공합니다.</p>
<p>이번 글에서는 기존 커뮤니티의 기여와 AI를 활용한 프로젝트의 출발 취지, 8개 플랫폼의 호환성 검증, 게시 중단 후 복구를 다룹니다. 정기 작업이 새 버전을 발견하면 소스 빌드부터 공개 파일 확인까지 처리하고, 문제가 생기면 해당 후보의 게시를 멈추도록 구성했습니다. 이번 릴리스를 바탕으로 생각하고 있는 후속 개발 도구의 방향도 덧붙입니다.</p>
<p>아래에서는 별도 확장을 만든 이유에서 시작해 플랫폼 호환 문제와 테스트 범위를 설명합니다. 이어서 버전 연결 방식, 첫 게시에서 발견한 운영 문제, 실험용 워크플로를 정리한 결과를 살펴보겠습니다. 끝으로 VS Code OSS 기반 .NET 개발 도구 구상을 소개합니다. 글에서 다루는 지원 범위와 실행 결과는 2026년 9월 6일의 첫 릴리스를 기준으로 합니다.</p>
<h2>기존 C# 배포를 유지하는 별도 확장 ID</h2>
<p>배포를 둘로 나눈 이유부터 정리하겠습니다. 기존 저장소는 Microsoft의 C# 확장 소스를 자동으로 빌드해 Open VSX에 게시해 왔습니다. 여기서 다루는 대상은 C# 확장이며 C# Dev Kit를 포함하지 않습니다. 기존 배포는 게시용 메타데이터와 빌드 환경을 조정하면서 상류 확장의 동작과 디버거 구현을 유지합니다.</p>
<p>C# 확장의 소스를 공개한다는 사실과 함께 제공하는 디버거의 사용 범위는 구분할 수 있습니다. Microsoft는 <a href="https://github.com/dotnet/vscode-csharp/blob/main/docs/debugger/Microsoft-.NET-Core-Debugger-licensing-and-Microsoft-Visual-Studio-Code.md"><code>vsdbg</code> 관련 문서</a>에서 디버거를 독점 구성 요소로 설명하고 Microsoft IDE에서의 사용으로 제한합니다. 그래서 확장을 Open VSX에 옮기는 작업만으로 VS Code 파생 편집기의 디버거 제약까지 해결할 수는 없습니다.</p>
<p>기존 배포에는 상류 동작을 가능한 한 유지한다는 가치가 있었습니다. 디버거 교체를 기존 사용자에게 일괄 적용하는 대신 별도 확장 ID를 만들었습니다. 두 배포의 선택 기준은 다음과 같습니다.</p>
<table>
<thead>
<tr>
<th>배포</th>
<th>확장 ID</th>
<th>유지하거나 변경하는 범위</th>
</tr>
</thead>
<tbody><tr>
<td>기존 C# 배포</td>
<td><code>dotnetdev-kr-custom.csharp</code></td>
<td>상류 확장의 동작과 디버거 구현 유지</td>
</tr>
<tr>
<td>C# (with netcoredbg)</td>
<td><code>dotnetdev-kr-custom.csharp-with-netcoredbg</code></td>
<td><code>coreclr</code> 디버그 어댑터를 자체 빌드한 netcoredbg로 교체</td>
</tr>
</tbody></table>
<p>커뮤니티에서는 <a href="https://github.com/muhammadsammy/free-vscode-csharp">muhammadsammy/free-vscode-csharp</a>가 이미 netcoredbg를 통합해 VS Code 파생 편집기에서 사용할 수 있는 C# 개발 환경을 제공해 왔습니다. 저는 이 프로젝트가 마련해 온 선택지와 그 과정에서 축적한 기여를 역사적으로 매우 값지게 생각합니다. 대안을 실제 확장으로 배포하고 유지해 온 muhammadsammy와 기여자들의 노력에 경의와 감사를 전합니다.</p>
<p>저는 빠르게 변화하는 .NET 생태계의 성과를 더 많은 사람에게 알리고 각자의 편집기에서 직접 접할 수 있도록 돕고 싶어 이 프로젝트를 시작했습니다. AI를 조사와 구현, 실패 원인 분석에 활용하면서 관리자의 반복 개입을 줄이는 배포 체계를 만들고자 했습니다. 이번 첫 릴리스에서는 그 취지를 8개 플랫폼의 패키지와 자동 검증 절차로 구체화할 수 있었습니다.</p>
<p>이번 배포는 상류 동작을 보존하는 기존 배포를 함께 유지하면서 태그별 소스 빌드, 플랫폼 전체 검증, 별도 확장 게시를 하나의 운영 흐름으로 연결하는 데 초점을 맞췄습니다. 기존 커뮤니티 확장과의 차이도 이러한 배포 목적과 운영 구조에서 설명할 수 있습니다. AI를 활용해 마련한 스크립트와 테스트가 정기 배포를 수행하고, 검증에 실패한 회차는 관리자가 로그를 살펴 대응하도록 구성했습니다.</p>
<p>이름도 처음 검토했던 Samsung 표기 대신 <code>C# (with netcoredbg)</code>로 정했습니다. 아이콘은 밝은 갈색 악보 위에 C와 #을 놓는 형태로 구분했습니다. 프로젝트 출처는 설명과 고지에 남기고 공식 배포나 후원 관계를 암시하는 브랜드 표현은 넣지 않았습니다. <a href="https://github.com/rkttu/vscode-csharp-autobuild/blob/main/README.md">배포 구분과 패키지 정책</a>에 두 확장의 역할을 기록했습니다.</p>
<h2>원본 소스 보존과 외부 호환 코드의 경계</h2>
<p>Samsung 원본을 보존하면서 어디까지 수정했는지 짚어보겠습니다. 출발점은 netcoredbg의 새 태그를 가져와 플랫폼별로 빌드한 뒤 C# 확장에 연결하는 방식이었습니다. <a href="https://github.com/Samsung/netcoredbg/blob/9744e1f051866215611b8440c638042aa2aa2f72/LICENSE">netcoredbg의 MIT 라이선스</a>는 저작권과 허가 고지를 포함하는 조건으로 복제, 수정, 배포를 허용합니다. 실제 패키지에는 함께 넣는 라이브러리의 고지도 별도로 보존했습니다.</p>
<p>원본 보존 여부는 파일 해시로 판단했습니다. 빌드 전후에 Samsung 입력 파일 498개의 SHA-256을 비교했고, 첫 릴리스의 모든 네이티브 대상에서 변경이 없음을 확인했습니다. 중간 산출물과 테스트용 프로젝트, 호환 코드는 원본 소스 트리 밖에서 관리했습니다.</p>
<p>컴파일러와 런타임 환경의 차이는 빌드 자동화만 추가한다고 사라지지 않았습니다. Windows에서는 네이티브 빌드와 관리 코드 빌드가 중간 출력 경로를 공유하면서 NuGet 자산 파일이 충돌했습니다. 네이티브 부분과 ManagedPart의 빌드를 분리하고 출력 경로를 나누어 해결했습니다.</p>
<p>Alpine에서는 디버거를 빌드한 뒤에도 .NET 런타임을 초기화하는 과정에서 충돌했습니다. 호출 스택과 재현 결과를 토대로 외부 호환 코드를 추가했고, CoreCLR 초기화를 자체적으로 확보한 8 MiB 스레드 스택에서 실행하도록 구성했습니다. 이 변경은 원본 파일을 수정하지 않으면서도 런타임 동작에 관여합니다. 따라서 원본 파일을 보존했다는 사실과 저장소가 호환 코드의 유지보수를 맡았다는 사실을 함께 설명했습니다. <a href="https://github.com/rkttu/vscode-csharp-autobuild/blob/main/docs/research/2026-09-06-build-troubleshooting.md">빌드 문제와 해결 기록</a>에 재현 조건과 근거를 남겼습니다.</p>
<p>C# 확장 쪽에도 코드 변경이 들어갔습니다. 임시 체크아웃에 적용하는 오버레이가 확장 ID와 표시 이름, 디버거 다운로드 경로, 어댑터 선택, SDK 환경 전달과 패키징을 조정합니다. 상류 코드가 예상과 달라지면 오버레이가 실패하도록 검사합니다. <a href="https://github.com/rkttu/vscode-csharp-autobuild/blob/main/scripts/variant/overlay.py">통합 코드</a>에 이러한 변경을 모았습니다. 디버거를 교체해도 C# 확장의 다른 구성 요소에 적용되는 라이선스와 사용 조건은 각각 유지합니다.</p>
<h2>빌드 성공 이후에 드러난 디버거 동작 오류</h2>
<p>기본적인 중단점 검증을 통과한 macOS 디버거에서도 종료 코드 오류가 드러났습니다. 처음 만든 검증용 프로그램은 정상 종료 코드 0을 반환했습니다. Samsung의 <code>VSCodeTestExitCode</code>는 macOS에서 종료 코드 3을 기대했는데, 당시 자체 빌드한 디버거는 DAP 응답으로 0을 전달했습니다. 정상 종료만 확인하는 테스트로는 발견할 수 없는 문제였습니다.</p>
<p>DAP(Debug Adapter Protocol)는 편집기와 디버거가 중단점, 스택, 변수, 프로세스 종료 같은 정보를 주고받는 규약입니다. 종료 코드가 달라지면 프로세스는 끝났더라도 편집기가 전달받는 실행 결과는 틀릴 수 있습니다.</p>
<p>macOS의 프로세스 종료 상태를 관찰하는 외부 라이브러리를 연결해 문제를 수정했습니다. .NET 8에서 동작한 뒤에도 .NET 10에서는 추가 조정이 필요했습니다. .NET 10의 런타임 구성 요소가 <code>waitpid$NOCANCEL</code> 진입점을 사용한다는 점을 확인하고 그 경로까지 처리했습니다. 이후 같은 테스트가 두 런타임에서 모두 종료 코드 3을 반환했습니다. 실패한 테스트는 검증 목록에 그대로 유지했으며 <a href="https://github.com/rkttu/vscode-csharp-autobuild/blob/main/docs/research/2026-09-06-functional-gate-and-darwin-exit.md">Darwin 호환 코드 조사 기록</a>에 수정 전후의 결과를 구분했습니다.</p>
<p>기능 검증은 자체 프로그램의 8개 검사 항목에 Samsung의 자동 DAP 시나리오 30개를 더하는 방식으로 확장했습니다. 상류 테스트의 C# 소스와 단언문은 유지하고 외부 프로젝트에서 .NET 8과 .NET 10을 대상으로 빌드했습니다. 수동 실행용으로 분류된 별도 시나리오는 자동 검사 수에 포함하지 않았습니다.</p>
<p>첫 릴리스에서 실행한 플랫폼 범위는 다음과 같습니다.</p>
<table>
<thead>
<tr>
<th>운영체제 계열</th>
<th>CPU 대상</th>
<th>실행한 런타임</th>
<th>검증 단계</th>
</tr>
</thead>
<tbody><tr>
<td>Windows</td>
<td>x64, ARM64</td>
<td>.NET 8.0.24, .NET 10.0.11</td>
<td>소스 빌드 후, VSIX 추출 후</td>
</tr>
<tr>
<td>Linux glibc</td>
<td>x64, ARM64</td>
<td>.NET 8.0.24, .NET 10.0.11</td>
<td>소스 빌드 후, VSIX 추출 후</td>
</tr>
<tr>
<td>Alpine Linux</td>
<td>x64, ARM64</td>
<td>.NET 8.0.24, .NET 10.0.11</td>
<td>소스 빌드 후, VSIX 추출 후</td>
</tr>
<tr>
<td>macOS</td>
<td>x64, ARM64</td>
<td>.NET 8.0.24, .NET 10.0.11</td>
<td>소스 빌드 후, VSIX 추출 후</td>
</tr>
</tbody></table>
<p>8개 플랫폼과 2개 런타임을 두 단계에서 검증하므로 총 32개 조합을 실행했습니다. 같은 시나리오를 빌드 직후와 VSIX에서 꺼낸 디버거에 각각 적용해 패키징 이후의 동작도 확인했습니다. <a href="https://github.com/rkttu/vscode-csharp-autobuild/actions/runs/34031151621">첫 릴리스 실행</a>은 모든 네이티브 빌드, VSIX 패키징, 추출 후 기능 검증을 첫 시도에 통과했습니다. 게시 단계의 실패는 뒤에서 따로 다룹니다.</p>
<p>다만 전체 플랫폼의 DAP 검증과 실제 편집기 UI 검증은 범위가 다릅니다. 별도의 설치 검증은 macOS ARM64의 VS Code 1.135.0에서 수행했습니다. VSCodium을 포함한 모든 파생 편집기나 원격 디버깅, 통합 터미널, Hot Reload, C# Dev Kit의 전체 기능까지 확인한 결과로 확대하지 않았습니다.</p>
<p>아래 실행 화면에서는 <code>Program.cs</code>의 7번째 줄에 설정한 중단점에서 실행을 멈추고 지역 변수와 호출 스택을 확인할 수 있습니다.</p>
<p><img src="https://cdn.hashnode.com/uploads/gql/60adcb82557cc70e51211e5c/86dc4ebf-ac81-418c-abff-767a46c64fc6.png" alt="C# 디버깅 화면에서 Program.cs의 7번째 줄에 멈춘 실행과 지역 변수 x=7, y=1 및 호출 스택을 표시한 모습" /></p>
<p><em>중단점에서 지역 변수 x=7과 y=1을 확인한 실제 실행 화면</em></p>
<p>조사 중에는 macOS 시작 지연과 예외 스택 관련 테스트가 간헐적으로 실패했습니다. 같은 후보의 재실행이 통과한 기록도 있지만 근본 원인은 확정하지 못했습니다. 실패 기록을 보존했고, 이후 후보에서도 같은 문제가 발생하면 게시를 차단하도록 유지했습니다.</p>
<h2>C# 버전과 디버거 버전을 연결하는 배포 기록</h2>
<p>두 프로젝트의 버전을 하나의 확장 버전에 연결하는 방식을 다루겠습니다. 사용자가 설치하는 버전은 C# 확장의 버전 흐름을 따라가되, 디버거만 바뀌거나 패키징 코드를 수정했을 때도 새 패키지를 구분할 수 있도록 배포 차수를 추가했습니다.</p>
<p>첫 릴리스의 입력과 출력은 다음과 같습니다.</p>
<table>
<thead>
<tr>
<th>항목</th>
<th>값</th>
<th>기록하는 의미</th>
</tr>
</thead>
<tbody><tr>
<td>상류 C# 태그</td>
<td><code>v2.148.23-prerelease</code></td>
<td>언어 서비스와 확장 소스의 기준</td>
</tr>
<tr>
<td>netcoredbg 태그</td>
<td><code>3.2.0-1092</code></td>
<td>디버거 소스의 기준</td>
</tr>
<tr>
<td>패키징 차수</td>
<td><code>1</code></td>
<td>같은 C# 버전 안에서의 배포 구분</td>
</tr>
<tr>
<td>공개 VSIX 버전</td>
<td><code>2.148.23001</code></td>
<td>편집기가 설치와 업데이트에 사용하는 버전</td>
</tr>
</tbody></table>
<p>숫자 패치 부분은 <code>상류 C# 패치 × 1000 + 배포 차수</code>로 계산합니다. 이번에는 <code>23 × 1000 + 1 = 23001</code>이므로 <code>2.148.23001</code>을 사용했습니다. 다음 차수는 <code>2.148.23002</code>로 구분하고 C# 패치가 24로 바뀌면 <code>2.148.24001</code>부터 시작합니다. 배포 차수는 1부터 999까지 허용하며 범위를 넘으면 자동 작업을 실패 처리합니다.</p>
<p>GitHub 릴리스 태그에는 C# 버전, netcoredbg 태그, 디버거 커밋의 축약값과 배포 차수를 함께 넣습니다. 전체 커밋 ID와 빌드 설정 지문, 검증 실행 ID, 파일 해시는 매니페스트와 패키지 메타데이터에 보존합니다. 숫자 버전만으로 세부 입력을 모두 표현하려고 하지 않고, 설치 버전에서 정확한 소스와 검증 파일을 찾아갈 수 있도록 연결했습니다. <a href="https://github.com/rkttu/vscode-csharp-autobuild/blob/main/scripts/variant/versioning.py">버전 계산 코드</a>와 <a href="https://github.com/rkttu/vscode-csharp-autobuild/blob/main/docs/research/cross-platform-2026-09-06/first-release-34031151621/release-manifest.json">첫 릴리스 매니페스트</a>에서 실제 대응 관계를 확인할 수 있습니다.</p>
<p>상류 태그의 <code>-prerelease</code> 표기도 기록에 남겼습니다. VSIX에 숫자 버전을 부여했다고 해서 상류 프리릴리스 소스의 성격까지 바뀌지는 않습니다. 게시 전 초안 릴리스와 완료한 릴리스는 사용한 차수를 예약하고, 게시 없는 검증 실행은 차수를 소비하지 않습니다.</p>
<h2>첫 게시에서 발견한 공개 지연과 초안 조회 권한</h2>
<p>첫 Open VSX 업로드는 모든 기능 검증을 통과한 뒤에 실패했습니다. 게시 도구가 Windows x64 패키지를 접수했다는 응답을 반환했지만, 직후 공개 메타데이터 조회는 HTTP 404를 반환했습니다. 당시 게시 코드는 공개 파일을 즉시 확인할 수 있다고 가정했기 때문에 작업을 중단했습니다.</p>
<p>약 4분 뒤에는 같은 버전의 Windows x64 패키지를 공개 주소에서 조회할 수 있었습니다. <a href="https://github.com/eclipse-openvsx/openvsx/blob/v1.1.2/server/src/main/java/org/eclipse/openvsx/publish/PublishExtensionVersionHandler.java">Open VSX의 게시 처리 코드</a>는 파일 저장과 검사 등 일부 처리를 비동기로 수행하고, 활성화가 끝나기 전에는 버전을 공개하지 않습니다. CLI의 접수 성공과 공개 다운로드 가능 시점을 각각 확인하는 방식으로 게시 절차를 수정했습니다.</p>
<p>수정한 게시기는 아직 없는 플랫폼을 한 번씩 업로드한 뒤 공개 상태를 기다립니다. 모든 업로드를 제출한 뒤부터 공통 15분 한도를 적용하고, 공개한 파일을 내려받아 검증한 VSIX의 SHA-256과 비교합니다. 이 한도를 넘거나 공개 파일의 내용이 다르면 해당 실행을 실패 처리합니다. 공개를 기다리는 동안 같은 파일을 반복해서 업로드하지는 않습니다.</p>
<p>복구에 사용할 파일은 첫 업로드 전에 GitHub 초안 릴리스에 보관합니다. 8개 디버거 압축 파일, 8개 VSIX, 검증 매니페스트, 릴리스 매니페스트, 압축한 검증 기록까지 총 19개 자산을 보존했습니다. 일부 플랫폼만 게시한 상태에서 작업이 멈추면 다음 실행이 초안의 파일을 복원하고 이미 공개한 파일의 해시를 비교합니다. 내용이 일치하는 플랫폼은 건너뛰고 나머지 게시를 이어갑니다.</p>
<p>초안을 복구하는 첫 실행에서는 또 다른 문제가 드러났습니다. 탐지 작업에 부여한 <code>contents: read</code> 권한으로는 공개 릴리스 목록을 읽을 수 있었지만 비공개 초안은 목록에 나타나지 않았습니다. <a href="https://docs.github.com/en/rest/releases/releases#list-releases">GitHub 릴리스 API 문서</a>는 푸시 권한이 있는 호출자에게만 초안 목록을 제공한다고 설명합니다. 탐지 작업에 <code>contents: write</code>를 부여한 뒤에는 보존한 첫 릴리스를 찾을 수 있었습니다. 빌드와 패키징 작업의 저장소 권한은 읽기로 유지했습니다.</p>
<p>이로써 <a href="https://github.com/rkttu/vscode-csharp-autobuild/actions/runs/34034255861">복구 실행</a>은 첫 릴리스의 버전과 파일을 유지한 채 남은 7개 플랫폼을 게시했습니다. 한국 시각 2026년 9월 6일 21시 57분 19초에 GitHub 릴리스 확정까지 완료했습니다. 이미 공개했던 Windows x64 패키지는 다시 빌드하거나 업로드하지 않았으며, 별도로 수행한 다운로드 검사에서도 8개 플랫폼 모두 원래 검증 해시와 일치했습니다. <a href="https://github.com/rkttu/vscode-csharp-autobuild/blob/main/docs/research/2026-09-06-first-release.md">첫 게시와 복구 기록</a>에 실패 당시 상태와 복구 결과를 함께 남겼습니다.</p>
<h2>세션 없이 실행하는 배포와 유지보수 범위</h2>
<p>정기 배포는 기본 브랜치 <code>main</code>에서 6시간마다 실행합니다. C#과 netcoredbg의 태그를 확인하고 새로운 소스 또는 빌드 설정 조합을 발견하면 전체 검증을 시작합니다. 완료한 조합은 건너뛰며 게시 중단으로 남은 초안이 있으면 그 파일의 복구를 먼저 처리합니다. 모든 단계는 GitHub 호스팅 러너에서 실행하므로 로컬 터미널이나 이번 작업 세션을 계속 열어둘 이유가 없습니다. <a href="https://github.com/rkttu/vscode-csharp-autobuild/blob/main/.github/workflows/release-netcoredbg.yml">정기 배포 워크플로</a>에 이 진입점을 모았습니다.</p>
<p>운영 정책은 실패한 Actions 실행과 그 증거를 중심으로 구성했습니다. 기능 검사, 파일 해시, 플랫폼 결과 중 하나라도 맞지 않으면 그 후보의 게시를 멈춥니다. 실패한 입력은 다음 주기에도 다시 검토할 수 있고, 관리자는 로그를 토대로 원인을 조사합니다. 알림 수신은 관리자의 GitHub 설정을 따르며 별도 알림 서버나 격리 큐는 추가하지 않았습니다. 토큰 유효성이나 서비스 장애, GitHub의 <a href="https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#schedule">예약 실행 지연과 비활동 저장소 처리</a>는 계속 운영 조건에 포함됩니다.</p>
<p>여러 플랫폼을 Open VSX에 게시하는 과정은 한 번에 전부 성공하거나 전부 취소하는 트랜잭션으로 묶이지 않습니다. 일부 플랫폼이 먼저 공개될 수 있으므로 원래 검증 파일을 보존해 이어서 게시하는 쪽을 선택했습니다. 자동 롤백은 넣지 않았고, 게시 후 기능 문제를 수정할 때는 높은 배포 차수로 새 패키지를 제공하는 경로를 사용합니다. 배포를 철회하더라도 사용자가 이미 설치한 파일까지 자동으로 되돌아가지는 않습니다. <a href="https://github.com/rkttu/vscode-csharp-autobuild/blob/main/docs/research/2026-09-06-publication-recovery-and-rollback.md">복구와 롤백 검토 기록</a>에 이 범위를 구분했습니다.</p>
<p>릴리스 뒤에는 실험 과정에서 만든 Windows 전용 검증과 Alpine 진단 워크플로를 정리했습니다. 기존 C# 게시, 새 확장의 배포 진입점과 내부 검증 워크플로, GitHub 관리 Copilot 작업을 유지했습니다. 수동 검증도 새 배포 진입점에서 게시 옵션을 끄는 방식으로 통일했습니다. 임시 브랜치와 승인한 진단 실행 기록을 삭제한 뒤에도 조사 문서와 정식 릴리스 자산은 보존했습니다. <a href="https://github.com/rkttu/vscode-csharp-autobuild/blob/main/docs/research/2026-09-06-workflow-cleanup.md">정리 기록</a>을 남기고 <a href="https://github.com/rkttu/vscode-csharp-autobuild/issues/2#issuecomment-5559474828">이슈 #2</a>를 해결 완료 상태로 닫았습니다.</p>
<h2>VS Code OSS 기반 .NET 개발 도구로 이어지는 구상</h2>
<p>이번 릴리스의 경험을 바탕으로 다음에 기회가 닿으면 VS Code OSS 기반의 오픈 소스 .NET 개발 도구에도 착수해 보고자 합니다. C# Dev Kit이 제공하는 개발 경험을 참고해 솔루션과 프로젝트 탐색, 빌드, 테스트, 디버깅을 편집기 안에서 연결하는 방향을 생각하고 있습니다. Microsoft의 <a href="https://code.visualstudio.com/docs/languages/csharp">C# 개발 문서</a>는 C# Dev Kit을 통한 솔루션 관리와 통합 테스트 등을 소개합니다. 이러한 작업 흐름 가운데 오픈 소스 도구로 구성할 수 있는 범위부터 검토할 계획입니다.</p>
<p>후속 개발 도구의 진행 상태를 기준일과 함께 남깁니다.</p>
<blockquote>
<p>2026년 9월 6일 현재 후속 개발 도구에는 아직 착수하지 않았습니다. 착수 시점과 세부 기능은 향후 검토를 거쳐 구체화할 예정입니다.</p>
</blockquote>
<p>이번 확장에서 마련한 디버거 통합과 플랫폼별 검증 경험은 후속 작업의 출발점으로 삼을 수 있습니다. 솔루션 관리와 테스트 실행까지 연결하려면 기존 오픈 소스 구성 요소의 역할과 라이선스를 따로 조사하고 실제 편집기에서의 동작도 검증할 예정입니다. 후속 작업에서도 AI를 조사와 구현에 활용하고 실행 결과를 근거로 공개할 기능과 지원 범위를 정해 나가고자 합니다.</p>
<h2>검증한 범위에서 시작하는 별도 C# 배포</h2>
<p>여기까지 정리하면 이번 프로젝트에서는 커뮤니티가 마련해 온 대안에 감사를 표하며, AI를 활용해 최신 .NET 개발 환경을 더 넓게 전달하려는 취지를 실제 배포로 연결했습니다. 상류 C# 확장과 netcoredbg의 소스를 조합하고 검증한 플랫폼별 파일을 반복해서 출시하는 운영 경로를 마련했습니다. <a href="https://github.com/rkttu/vscode-csharp-autobuild/blob/main/docs/research/2026-09-06-first-release.md">첫 릴리스 기록</a>은 기능 검사와 공개 파일 확인 결과, 남은 한계를 함께 보존합니다.</p>
<p>현재 설치할 패키지는 <a href="https://open-vsx.org/extension/dotnetdev-kr-custom/csharp-with-netcoredbg">Open VSX의 C# (with netcoredbg)</a>에서 선택할 수 있습니다. 기존 상류 동작의 유지를 우선한다면 원래 배포를 계속 사용할 수 있고, netcoredbg 통합판을 선택한다면 기록한 플랫폼과 기능 범위를 기준으로 판단할 수 있습니다. 당장의 운영에서는 새 태그와 런타임, 컴파일러 변화에 같은 검증을 반복하고 실패 원인을 조사합니다. VS Code OSS 기반 개발 도구는 다음 기회에 착수를 검토할 장기 구상으로 두고, 이번 확장은 공개한 지원 범위 안에서 유지해 나가겠습니다.</p>
]]></content:encoded></item><item><title><![CDATA[dotnetup 프리뷰: global.json에서 SDK와 런타임 관리까지]]></title><description><![CDATA[dotnetup 프리뷰가 운영체제 패키지와 개발용 SDK를 분리하고 global.json, 런타임, 업데이트 상태를 관리하는 방식을 정리합니다.]]></description><link>https://devwrite.ai/dotnetup-preview-first-look</link><guid isPermaLink="true">https://devwrite.ai/dotnetup-preview-first-look</guid><category><![CDATA[dotnet]]></category><category><![CDATA[dotnet-sdk]]></category><dc:creator><![CDATA[Jung-hyun, Nam]]></dc:creator><pubDate>Sat, 22 Aug 2026 16:35:51 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/gql/60adcb82557cc70e51211e5c/2d64bc3b-a691-40ed-b99b-86e4eaaa9389.webp" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>Microsoft는 Microsoft Build 2026 사전 녹화 세션 OD804 <a href="https://www.youtube.com/watch?v=ZMnyohA5yrw">「Simplifying .NET installs with .NET Up」</a>에서 사용자 단위 .NET 설치를 관리하는 새 도구 <code>dotnetup</code>을 소개했습니다. 2026년 8월 22일 현재 <code>dotnet/sdk</code> 저장소의 <code>release/dnup</code> 브랜치는 Windows, macOS, Linux용 프리뷰 설치 방법과 명령 참조 문서를 제공합니다. 이 글은 세션이 제시한 문제와 설계 의도를 토대로 현재 프리뷰에서 확인할 수 있는 동작을 정리합니다.</p>
<p><code>dotnetup</code>은 관리자 권한 없이 사용자 프로필 아래에 .NET SDK와 런타임을 설치합니다. 저장소의 <code>global.json</code>을 읽어 필요한 SDK 채널을 추적하고 여러 요구 사항이 공유하는 설치 파일을 업데이트하거나 정리합니다. 셸과 애플리케이션이 관리 대상 <code>dotnet</code>을 찾는 방식도 선택할 수 있습니다. 이 글에서는 설치 방식, <code>global.json</code> 해석, SDK와 런타임의 분리, 설치 상태 관리, 자동화 활용을 다룹니다.</p>
<p>먼저 기존 설치 방식에서 남아 있던 관리 공백을 살펴봅니다. 이후 프리뷰 설치와 저장소 단위 SDK 준비 과정을 따라갑니다. 런타임과 업데이트 모델을 설명하고 현재 구현과 OD804 로드맵 사이의 차이로 글을 마무리합니다.</p>
<blockquote>
<p>기준일: 2026년 8월 22일. <code>dotnetup</code>은 프리뷰 단계이며 명령 이름과 동작이 달라질 수 있습니다. 이 글은 <a href="https://github.com/dotnet/sdk/tree/release/dnup/documentation/general/dotnetup"><code>release/dnup</code> 브랜치의 공식 문서</a>와 이날 내려받은 <code>0.2.0-preview.1.26410.1</code>을 기준으로 작성했습니다.</p>
</blockquote>
<h2>설치 스크립트보다 rustup에 가까운 상태 관리자</h2>
<p>.NET 설치 경로가 왜 하나의 관리 도구로 모이는지 살펴보겠습니다. OD804 세션은 Windows에서 Visual Studio가 도구 체인을 관리하는 경우와 그 밖의 경우를 대비합니다. 후자에는 운영체제 패키지 관리자, 웹 설치 프로그램, <code>dotnet-install</code> 스크립트, DNVM과 mise 같은 버전 관리 도구가 섞여 있습니다. 설치 주체와 업데이트 주기가 서로 달라지면 저장소마다 필요한 SDK를 준비하고 오래된 설치를 제거하는 절차도 달라집니다. <a href="https://www.youtube.com/watch?v=ZMnyohA5yrw&amp;t=69s">세션의 문제 정의 구간</a>은 이 차이를 도구가 해결하려는 출발점으로 제시합니다.</p>
<p>기존 <code>dotnet-install</code> 스크립트도 관리자 권한 없는 설치를 지원합니다. 다만 Microsoft는 이 스크립트를 SDK가 실행마다 사라져도 되는 CI 환경에 주로 사용한다고 설명합니다. 개발 환경에는 설치 프로그램을 안내해 왔습니다. <a href="https://learn.microsoft.com/dotnet/core/tools/dotnet-install-script"><code>dotnet-install</code> 공식 문서</a>는 이 사용 범위를 명시합니다.</p>
<p>이 지점에서 <code>dotnetup</code>은 설치 스크립트보다 Rust의 <code>rustup</code>과 가까운 도구 체인 관리자입니다. Ubuntu처럼 <a href="https://learn.microsoft.com/dotnet/core/install/linux-ubuntu-install">배포판 패키지의 SDK 기능 밴드와 더 최신 SDK 배포 사이에 차이가 생길 수 있는 환경</a>에서는 시스템 패키지를 유지한 채 개발용 최신 SDK만 사용자 계정에 분리할 수 있습니다. 패키지 관리자를 교체하거나 관리자 권한을 얻지 않고도 프로젝트마다 다른 채널을 추적할 수 있다는 점을 <a href="https://forum.dotnetdev.kr/t/dotnetup-rustup-net-toolchain-manager/14805">닷넷데브의 초기 소개 글</a>에서도 강조했습니다.</p>
<p><code>dotnetup</code>은 원하는 구성 요소와 채널을 기록한 뒤 실제 설치 버전과 연결합니다. 그래서 <code>latest</code>, <code>lts</code>, <code>10.0.1xx</code>처럼 계속 이동하는 요구 사항을 나중에 다시 해석할 수 있습니다. 정확한 버전을 지정하면 해당 요구 사항을 고정합니다. 설치 파일을 받는 작업과 설치 상태를 관리하는 작업을 한 명령 체계에 넣었다는 점에서 기존 스크립트와 역할이 갈립니다. <a href="https://github.com/dotnet/sdk/blob/release/dnup/documentation/general/dotnetup/index.md">공식 개요 문서</a>는 설치, 업데이트, 제거, 환경 구성을 현재 범위로 설명합니다.</p>
<h2>관리자 권한 없는 사용자 단위 설치</h2>
<p>프리뷰 설치와 접근 모드를 정리하겠습니다. macOS와 Linux에서는 공식 스크립트로 시작할 수 있습니다.</p>
<pre><code class="language-bash">curl -fsSL https://aka.ms/dotnet/dotnetup/preview/get-dotnetup.sh | bash
export PATH="$HOME/.dotnetup:$PATH"
dotnetup init
dotnetup --version
</code></pre>
<p>스크립트는 운영체제와 CPU에 맞는 실행 파일을 내려받고 SHA-512 체크섬을 검증한 뒤 기본적으로 <code>~/.dotnetup</code>에 <code>dotnetup</code> 실행 파일을 둡니다. Windows용 PowerShell 절차와 <code>daily</code> 빌드 설치법은 <a href="https://github.com/dotnet/sdk/blob/release/dnup/documentation/general/dotnetup/README.md">시작 문서</a>에서 함께 확인할 수 있습니다. 보안 정책상 파이프 실행을 허용하지 않는 환경이라면 스크립트를 파일로 저장해 검토한 뒤 실행할 수 있습니다.</p>
<p><code>dotnetup init</code>은 SDK 채널과 접근 모드를 묻습니다. 접근 모드는 기존 <code>dotnet</code> 설치와의 우선순위를 결정합니다.</p>
<table>
<thead>
<tr>
<th>표시 이름</th>
<th>설정값</th>
<th>관리 대상 <code>dotnet</code>을 찾는 범위</th>
</tr>
</thead>
<tbody><tr>
<td>Isolation Mode</td>
<td><code>none</code></td>
<td><code>PATH</code>를 바꾸지 않고 <code>dotnetup dotnet &lt;command&gt;</code>로 실행</td>
</tr>
<tr>
<td>Terminal Mode</td>
<td><code>shell</code></td>
<td>선택한 셸 프로필을 갱신하고 해당 셸에서 시작한 프로세스에 적용</td>
</tr>
<tr>
<td>Everywhere Mode</td>
<td><code>everywhere</code></td>
<td>Windows 사용자 환경과 셸 프로필에 적용</td>
</tr>
</tbody></table>
<p>macOS와 Linux에서는 지원하는 셸을 감지하면 Terminal Mode를 기본 후보로 표시합니다. Windows에서는 Everywhere Mode를 기본 후보로 제시합니다. <code>dotnetup</code>이 관리하는 SDK와 런타임의 기본 설치 루트는 운영체제별 사용자 데이터 디렉터리 아래에 두며 시스템 관리 경로에는 쓰지 않습니다. <a href="https://github.com/dotnet/sdk/blob/release/dnup/documentation/general/dotnetup/concepts/environment.md">환경 구성 문서</a>가 경로와 환경 변수의 실제 동작을 설명합니다.</p>
<p>이번 확인에서는 공식 프리뷰 스크립트가 macOS arm64용 <code>0.2.0-preview.1.26410.1</code> 실행 파일을 선택하고 체크섬 검증을 마쳤습니다. OD804는 빠른 시작과 작은 런타임 의존성을 위해 Native AOT를 설계 방향으로 설명합니다. 내려받은 파일도 .NET SDK를 먼저 설치하지 않은 상태에서 바로 실행할 수 있는 플랫폼별 실행 파일이었습니다. 이 결과는 2026년 8월 22일의 macOS arm64 확인에 한정됩니다.</p>
<p>첫 실행에서는 사용량 텔레메트리 수집을 고지합니다. 기존 .NET CLI와 같은 <code>DOTNET_CLI_TELEMETRY_OPTOUT=1</code> 환경 변수로 전송을 중단할 수 있습니다. 프리뷰를 자동화 환경에 넣을 때에는 <a href="https://aka.ms/dotnetup-telemetry">공식 텔레메트리 안내</a>와 조직 정책을 함께 적용할 수 있습니다.</p>
<h2>global.json을 설치 요청으로 해석하는 채널 모델</h2>
<p>저장소 요구 사항을 설치 상태로 바꾸는 과정을 짚어보겠습니다. 다음 <code>global.json</code>은 10.0.1xx 기능 밴드 안에서 최신 패치를 허용합니다.</p>
<pre><code class="language-json">{
  "sdk": {
    "version": "10.0.100",
    "rollForward": "latestPatch"
  }
}
</code></pre>
<p>저장소 루트에서 <code>dotnetup sdk install</code>을 실행하면 도구가 현재 디렉터리부터 상위 디렉터리 방향으로 가장 가까운 <code>global.json</code>을 찾습니다. 채널을 명령줄에 적지 않았고 사용할 수 있는 파일도 없다면 <code>latest</code>를 선택합니다. 파일을 찾으면 <code>sdk.version</code>과 <code>rollForward</code>를 다음 규칙으로 설치 요청에 대응시킵니다.</p>
<table>
<thead>
<tr>
<th><code>rollForward</code></th>
<th><code>10.0.103</code>에서 추적하는 요청</th>
</tr>
</thead>
<tbody><tr>
<td>생략 또는 <code>latestPatch</code></td>
<td><code>10.0.1xx</code></td>
</tr>
<tr>
<td><code>latestFeature</code></td>
<td><code>10.0</code></td>
</tr>
<tr>
<td><code>latestMinor</code></td>
<td><code>10</code></td>
</tr>
<tr>
<td><code>latestMajor</code></td>
<td><code>latest</code></td>
</tr>
<tr>
<td><code>disable</code>, <code>patch</code>, <code>feature</code>, <code>minor</code>, <code>major</code></td>
<td>정확한 버전 <code>10.0.103</code></td>
</tr>
</tbody></table>
<p>이 대응은 .NET 호스트가 설치된 SDK 중 하나를 고르는 규칙과 목적이 다릅니다. <code>dotnetup</code>은 어떤 버전을 설치하고 계속 추적할지 결정하고 .NET 호스트는 설치를 마친 SDK 중 실행에 사용할 버전을 고릅니다. <a href="https://learn.microsoft.com/dotnet/core/tools/global-json"><code>global.json</code> 공식 문서</a>는 SDK 선택과 런타임 대상 지정을 서로 독립된 항목으로 설명합니다. <code>dotnetup</code>의 변환 규칙은 <a href="https://github.com/dotnet/sdk/blob/release/dnup/documentation/general/dotnetup/usecases/install-with-global-json.md">저장소 연동 문서</a>에서 확인할 수 있습니다.</p>
<p>이번 확인에서는 위 파일을 읽은 <code>dotnetup</code>이 요청을 <code>10.0.1xx</code>로 기록하고 <code>10.0.111</code>을 별도 설치 루트에 배치했습니다. <code>dotnetup list</code>도 설치 출처로 해당 <code>global.json</code>의 전체 경로를 표시했으며 설치한 <code>dotnet --version</code>은 <code>10.0.111</code>을 반환했습니다. 같은 명령을 다른 날 실행하면 채널이 가리키는 버전이 달라질 수 있습니다.</p>
<p><code>--update-global-json</code>을 추가하면 설치한 구체 버전을 <code>sdk.version</code>에 반영합니다. 다른 속성과 서식, 감지한 텍스트 인코딩은 유지합니다. <code>sdk.paths</code>가 있는 저장소에서는 첫 번째 경로를 설치 루트로 사용할 수도 있습니다. 명령줄의 <code>--install-path</code>가 <code>sdk.paths</code>보다 먼저 적용됩니다.</p>
<h2>최신 SDK와 과거 런타임의 분리</h2>
<p>SDK와 런타임을 따로 설치하는 이유를 다루겠습니다. SDK는 컴파일러, MSBuild, CLI 같은 개발 도구를 제공합니다. 런타임은 빌드한 애플리케이션과 테스트를 실제로 실행합니다. 최신 SDK로 여러 대상 프레임워크를 빌드하더라도 해당 버전의 테스트를 실행할 런타임은 별도로 필요할 수 있습니다.</p>
<p>OD804 데모는 .NET 10 SDK로 <code>net8.0</code>, <code>net9.0</code>, <code>net10.0</code> 테스트를 빌드한 뒤 .NET 8과 .NET 9 런타임이 없어 두 테스트가 시작되지 않는 상황을 보여 줍니다. 이전 SDK 전체를 나란히 설치하는 대신 필요한 런타임만 추가하는 해법을 다음과 같이 시연합니다.</p>
<pre><code class="language-console">dotnetup runtime install 8.0 9.0 10.0
dotnetup runtime install aspnetcore@8.0 aspnetcore@10.0
dotnet --list-runtimes
</code></pre>
<p>버전만 쓰면 <code>Microsoft.NETCore.App</code> 런타임을 선택합니다. <code>aspnetcore@10.0</code>은 ASP.NET Core 런타임을 선택하고 Windows에서는 <code>windowsdesktop@10.0</code>도 사용할 수 있습니다. 정확한 런타임 버전을 적으면 고정 요청으로 저장합니다. <a href="https://github.com/dotnet/sdk/blob/release/dnup/documentation/general/dotnetup/usecases/install-components.md">구성 요소 설치 문서</a>는 현재 지원하는 명령 형식을 설명합니다.</p>
<p>세션에서 보여 준 <code>global.json</code>의 런타임 선언은 미래 구상을 설명하기 위한 가상 문법이었습니다. 현재 프리뷰 문서는 <code>global.json</code>에서 SDK 요구 사항만 읽습니다. 런타임은 <code>dotnetup runtime install</code>에 직접 지정합니다. <a href="https://www.youtube.com/watch?v=ZMnyohA5yrw&amp;t=1505s">세션의 런타임 데모 구간</a>도 이 문법이 확정되지 않았다고 밝힙니다.</p>
<h2>요구 상태와 실제 설치를 나누는 매니페스트</h2>
<p>설치 이후의 업데이트와 정리 방식을 검토하겠습니다. <code>dotnetup</code>은 사용자가 요청한 채널과 디스크에 배치한 구체 버전을 별도로 기록합니다.</p>
<table>
<thead>
<tr>
<th>상태 요소</th>
<th>기록하는 내용</th>
<th>쓰임새</th>
</tr>
</thead>
<tbody><tr>
<td>설치 사양</td>
<td>구성 요소, 채널 또는 정확한 버전, 요청 출처</td>
<td>업데이트할 범위와 고정 여부 판단</td>
</tr>
<tr>
<td>설치 항목</td>
<td>구체 버전, 아키텍처, 설치 루트, 공유 하위 구성 요소</td>
<td>파일 검증과 제거 범위 계산</td>
</tr>
<tr>
<td>환경 설정</td>
<td><code>dotnet</code> 접근 모드와 <code>dotnetup</code>의 <code>PATH</code> 포함 여부</td>
<td>셸 프로필과 현재 설정의 차이 탐지</td>
</tr>
</tbody></table>
<p>상태를 조회하고 갱신하는 기본 흐름은 다음과 같습니다.</p>
<pre><code class="language-console">dotnetup list
dotnetup update
dotnetup list --format json
</code></pre>
<p><code>dotnetup update</code>는 각 이동 채널을 다시 해석해 새 버전을 설치합니다. 정확한 버전 요청은 건너뜁니다. 업데이트가 끝나면 남아 있는 설치 사양이 더 이상 요구하지 않는 버전과 다른 설치 항목이 공유하지 않는 하위 구성 요소를 정리합니다. 여러 요청이 같은 설치를 가리키면 파일을 한 번만 유지합니다. <a href="https://github.com/dotnet/sdk/blob/release/dnup/documentation/general/dotnetup/usecases/update-installations.md">업데이트 문서</a>와 <a href="https://github.com/dotnet/sdk/blob/release/dnup/documentation/general/dotnetup/concepts/how-dotnetup-works.md">상태 모델 문서</a>가 이 동작을 나누어 설명합니다.</p>
<p>OD804는 사용자 데이터 디렉터리의 매니페스트를 선언한 시스템 상태에 대한 잠금 파일에 비유합니다. 이 비유는 저장소에 커밋하는 계약까지 뜻하지 않습니다. 저장소 계약은 <code>global.json</code>이 담당하며 매니페스트는 각 컴퓨터에서 설치 사양과 실제 파일을 연결하는 장부에 가깝습니다. 도구는 매니페스트 내용이 자신이 기록한 상태에서 달라졌는지 검사하는 해시 파일도 유지하므로 해당 파일을 직접 편집하지 않습니다.</p>
<h2>사람과 자동화가 함께 쓰는 개발용 경계</h2>
<p>사람과 에이전트가 같은 설치 절차를 사용하는 범위를 확인하겠습니다. OD804는 <code>dotnetup</code>의 주요 사용자를 개발자와 자동화된 실행 주체로 나눕니다. 자동화에는 LLM 기반 코딩 에이전트뿐 아니라 CI도 포함합니다. 관리자 권한을 주지 않은 샌드박스에서도 저장소에 맞는 SDK를 준비할 수 있고 명시적인 명령과 JSON 출력으로 상태를 읽을 수 있기 때문입니다.</p>
<p>자동화에서는 대화형 초기 설정에 의존하지 않는 다음 형태를 사용할 수 있습니다.</p>
<pre><code class="language-console">dotnetup sdk install 10.0.1xx --no-progress --interactive false
dotnetup dotnet test -- --logger trx
dotnetup list --format json --no-verify
</code></pre>
<p><code>dotnetup</code>은 CI 또는 리디렉션된 출력을 감지하면 첫 실행 안내를 비활성화합니다. <code>--no-progress</code>는 터미널 진행 표시가 로그에 섞이는 문제를 피하고 <code>--interactive false</code>는 입력 대기를 막습니다. 검증이 필요한 자동화에서는 <code>--no-verify</code>를 빼면 기록된 파일이 실제로 존재하고 유효한지 검사합니다. 세부 옵션은 <a href="https://github.com/dotnet/sdk/blob/release/dnup/documentation/general/dotnetup/usecases/automation.md">자동화 문서</a>에서 확인할 수 있습니다.</p>
<p><code>dotnetup dotnet</code>은 관리 대상 기본 설치 루트의 환경을 자식 프로세스에만 적용합니다. 임의의 <code>--install-path</code>로 만든 설치를 자동으로 고르지 않으므로 사용자 지정 루트에서는 그 안의 <code>dotnet</code> 실행 파일을 직접 호출하거나 환경 스크립트로 활성화합니다. 이 제약은 <a href="https://github.com/dotnet/sdk/blob/release/dnup/documentation/general/dotnetup/reference/dotnetup-dotnet.md">명령 참조</a>에 적혀 있습니다.</p>
<p><code>dotnetup dotnet</code>은 File-based App의 실행 경로로도 연결할 수 있습니다. <code>env -S</code>를 지원하는 Unix 환경에서 <code>sample.cs</code>의 첫 줄을 <code>#!/usr/bin/env -S dotnetup dotnet</code>으로 지정하고 실행 권한을 부여하면 관리 대상 SDK로 파일을 직접 실행할 수 있습니다. 시스템에 <code>dotnetup</code> CLI만 준비하면 관리자 권한이 없는 환경에서도 같은 실행 경로를 구성할 수 있습니다. <a href="https://forum.dotnetdev.kr/t/dotnetup-rustup-net-toolchain-manager/14805/2">닷넷데브 글의 추가 예시</a>가 이 구성을 보여 줍니다.</p>
<p>도구의 범위는 개발 환경에 머뭅니다. <a href="https://www.youtube.com/watch?v=ZMnyohA5yrw&amp;t=2055s">세션의 사용 대상 설명</a>은 프로덕션의 프레임워크 종속 배포에는 운영체제 패키지 관리자를 사용하고 다른 경우에는 자체 포함 배포를 선택하는 기존 방식을 유지한다고 설명합니다. 실제 배포 형태에 따른 런타임 포함 여부는 <a href="https://learn.microsoft.com/dotnet/core/deploying/">.NET 애플리케이션 게시 개요</a>에서 구분할 수 있습니다.</p>
<h2>현재 프리뷰와 OD804 로드맵의 간격</h2>
<p>OD804에서 예고한 기능 가운데 일부가 현재 명령 표면에 들어왔고 나머지는 공개 문서에서 아직 확인되지 않습니다. 세션은 내부 프리뷰, 공개 프리뷰, GA 이후를 나눠 일일 빌드, 한 번의 명령에 특정 SDK를 고르는 실행 방식, 자체 업데이트, 서명 검증, 에이전트 스킬, CI 공급자 통합을 제시했습니다.</p>
<table>
<thead>
<tr>
<th>항목</th>
<th>2026년 8월 22일 확인 결과</th>
</tr>
</thead>
<tbody><tr>
<td>안정판, LTS, 프리뷰, 일일 빌드, 숫자 채널</td>
<td>SDK와 런타임 채널로 제공</td>
</tr>
<tr>
<td><code>global.json</code> 연동</td>
<td>SDK 버전과 <code>rollForward</code>, <code>sdk.paths</code>, 선택적 파일 갱신 지원</td>
</tr>
<tr>
<td>SDK와 런타임 구성 요소</td>
<td>설치, 업데이트, 제거, 목록 조회 지원</td>
</tr>
<tr>
<td>한 번의 명령으로 실행</td>
<td><code>dotnetup dotnet</code> 전달 명령 제공. 특정 SDK 버전을 명령 옵션으로 고르는 기능은 이번 프리뷰 도움말에서 확인되지 않음</td>
</tr>
<tr>
<td><code>dotnetup</code> 자체 업데이트</td>
<td>이번 프리뷰의 공개 명령 목록에서 확인되지 않음</td>
</tr>
<tr>
<td><code>global.json</code>의 런타임 선언</td>
<td>세션의 가상 문법에 머물며 현재 문서는 SDK 요구 사항만 설명</td>
</tr>
<tr>
<td>에이전트 스킬과 CI 공급자 통합</td>
<td>세션의 장기 방향이며 현재 공개 사용 문서에서 확인되지 않음</td>
</tr>
<tr>
<td>다운로드 검증</td>
<td>프리뷰 설치 스크립트는 SHA-512 체크섬을 검증. 일일 빌드는 코드 서명을 거치지 않았다고 공식 문서가 고지</td>
</tr>
</tbody></table>
<p>SHA-512 체크섬 검증과 코드 서명 검증은 같은 보장을 뜻하지 않습니다. 현재 <a href="https://github.com/dotnet/sdk/blob/release/dnup/documentation/general/dotnetup/README.md">시작 문서</a>는 프리뷰 설치 스크립트의 체크섬 검증을 안내합니다. OD804의 <a href="https://www.youtube.com/watch?v=ZMnyohA5yrw&amp;t=2539s">로드맵 구간</a>은 .NET SDK와 런타임, <code>dotnetup</code> 자체의 서명 검증을 공개 프리뷰 목표로 설명했습니다.</p>
<p>일일 빌드 채널은 <code>11.0.1xx-daily</code>처럼 메이저 버전과 기능 밴드, 프리뷰 단계를 좁혀 지정할 수 있습니다. <a href="https://github.com/dotnet/sdk/blob/release/dnup/documentation/general/dotnetup/channels/daily.md">일일 채널 문서</a>는 지원 릴리스가 아니며 코드 서명을 거치지 않았다고 경고합니다. 장기간 유지할 개발 환경보다 짧은 시험에 맞는 선택입니다.</p>
<p>현재 문서는 <a href="https://github.com/dotnet/sdk/blob/release/dnup/documentation/general/dotnetup/index.md">.NET SDK 저장소 안의 구현 문서</a>로 제공됩니다. 공식 개요도 배포 방식이 내부 릴리스마다 달라질 수 있다고 고지합니다. 블로그의 설치 예시를 나중에 다시 사용할 때에는 <code>dotnetup --version</code>과 <code>dotnetup --help</code>를 함께 기록하면 당시 명령 표면을 남길 수 있습니다.</p>
<h2>프리뷰 적용 전 점검 항목</h2>
<p>프리뷰 적용 전에는 <a href="https://github.com/dotnet/sdk/blob/release/dnup/documentation/general/dotnetup/README.md">공식 시작 문서</a>와 현재 환경의 요구 사항을 기준으로 다음 순서를 사용할 수 있습니다.</p>
<ol>
<li>공식 시작 문서의 설치 URL과 지원 운영체제를 다시 확인합니다.</li>
<li>기존 <code>dotnet</code>을 유지하려면 Isolation Mode를 선택하고 <code>dotnetup dotnet</code>으로 실행합니다.</li>
<li>저장소의 <code>global.json</code>과 <code>rollForward</code>가 어떤 채널로 바뀌는지 기록합니다.</li>
<li>이동 채널이 필요한 환경과 정확한 버전 고정이 필요한 빌드를 분리합니다.</li>
<li>일일 빌드는 별도 설치 루트에서 짧게 시험하고 결과에 버전을 남깁니다.</li>
<li>CI에서는 진행 표시와 대화형 입력을 끄고 종료 코드를 검사합니다.</li>
<li>텔레메트리를 보내지 않는 환경에서는 <code>DOTNET_CLI_TELEMETRY_OPTOUT=1</code>을 설정합니다.</li>
</ol>
<h2>개발 환경의 선언과 설치를 잇는 dotnetup</h2>
<p>여기까지 정리하면 <code>dotnetup</code>은 개발 환경에서 .NET SDK와 런타임의 요구 상태를 설치 파일과 연결합니다. <code>global.json</code>을 새 형식으로 대체하지 않고 저장소가 이미 가진 선언을 설치와 업데이트의 입력으로 활용합니다. SDK와 런타임을 구성 요소로 나눈 명령 체계는 다중 대상 테스트와 여러 저장소를 오가는 작업에서 특히 쓸모가 드러납니다.</p>
<p>장기적으로는 OD804가 제시한 자체 업데이트, 서명 검증 확대, 에이전트 스킬, CI 통합이 도구의 관리 범위를 넓힐 수 있습니다. 지금 바로 영향을 주는 부분은 사용자 권한 설치, <code>global.json</code> 기반 SDK 준비, 런타임 분리 설치, 추적한 채널의 일괄 업데이트입니다. 프리뷰와 일일 빌드의 검증 수준은 서로 다르므로 같은 신뢰 수준으로 다루지 않습니다.</p>
<p>여러 .NET 저장소를 로컬에서 다루거나 격리된 에이전트가 빌드 환경을 준비한다면 현재 프리뷰를 별도 설치 루트에서 시험할 만합니다. 운영체제 패키지 정책이 중요한 프로덕션 서버에는 기존 배포 방식을 유지할 수 있습니다. 팀이 SDK 버전을 정확히 고정하는 경우에는 정확한 버전 채널을 사용하고 기능 밴드 안에서 패치를 따라가려는 경우에는 <code>global.json</code>의 <code>rollForward</code>와 <code>dotnetup</code>의 채널 대응을 기준으로 판단할 수 있습니다.</p>
]]></content:encoded></item><item><title><![CDATA[출시를 앞둔 .NET 11의 변경 사항과 도입 판단]]></title><description><![CDATA[.NET 11 Preview 7의 지원 주기, 하드웨어 기준선, Runtime Async, C# 15와 프레임워크 변화를 바탕으로 도입 판단 기준을 정리합니다.]]></description><link>https://devwrite.ai/dotnet-11-preview-7-adoption-guide</link><guid isPermaLink="true">https://devwrite.ai/dotnet-11-preview-7-adoption-guide</guid><category><![CDATA[dotnet]]></category><category><![CDATA[dotnet 11]]></category><category><![CDATA[C#]]></category><category><![CDATA[asp.net core]]></category><category><![CDATA[entity framework core]]></category><dc:creator><![CDATA[Jung-hyun, Nam]]></dc:creator><pubDate>Sat, 22 Aug 2026 15:52:15 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/gql/60adcb82557cc70e51211e5c/761d3da6-41af-466f-9738-ccf03f9acc9d.webp" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>Microsoft는 .NET 11 정식 버전을 2026년 11월 10일에 출시할 예정입니다. 2026년 8월 23일 현재 Microsoft는 8월 11일에 공개한 .NET 11 Preview 7을 최신 빌드로 제공합니다. Microsoft는 런타임과 SDK, C# 15, ASP.NET Core, .NET MAUI, Entity Framework Core를 포함한 제품군 전반을 계속 다듬고 있습니다. 정식 출시 전까지 기능과 동작이 달라질 가능성도 남아 있습니다. <a href="https://devblogs.microsoft.com/dotnet/dotnet-11-preview-7/">Microsoft의 .NET 11 Preview 7 발표</a></p>
<p>이 글에서는 .NET 11의 변화를 지원 주기, 하드웨어 기준선, 런타임과 개발 도구, C# 15, 응용 프레임워크라는 다섯 가지 축으로 정리합니다. 기능의 수보다 기존 서비스를 옮길 때 영향을 받는 지점을 중심에 두었습니다.</p>
<p>먼저 지원 주기와 실행 환경을 다룬 뒤 Runtime Async와 SDK로 범위를 옮깁니다. 이어서 C# 15의 타입 모델과 ASP.NET Core, EF Core의 주요 기능을 검토합니다. 마지막에는 정식 출시 전에 적용할 수 있는 점검 절차를 제시합니다.</p>
<p>이 글은 아래 기준일에 공개된 미리 보기 자료를 토대로 작성했습니다.</p>
<blockquote>
<p>기준일: 2026년 8월 23일</p>
<p>대상 버전: .NET 11 Preview 7, SDK 11.0.100-preview.7</p>
<p>상태: 미리 보기 기능과 호환성 변경 목록은 정식 출시 전까지 달라질 수 있습니다. 미리 보기 빌드는 일반적으로 프로덕션 사용을 지원하지 않습니다.</p>
</blockquote>
<h2>지원 기간을 늘리지 않는 STS 릴리스</h2>
<p>.NET 11의 지원 주기부터 정리하겠습니다. Microsoft는 .NET 11을 STS로 분류하고 2026년 11월 10일부터 2028년 11월 9일까지 2년간 지원할 계획입니다. LTS와 STS는 품질 수준이 같고 지원 기간만 다릅니다. LTS는 3년, STS는 2년간 패치와 기술 지원을 제공합니다. 이 일정은 <a href="https://github.com/dotnet/core/blob/main/release-notes/11.0/README.md">.NET 11 릴리스 계획</a>과 <a href="https://dotnet.microsoft.com/en-us/platform/support/policy">.NET 지원 정책</a>에서 확인할 수 있습니다.</p>
<p>현재 버전별 일정을 함께 놓으면 업그레이드 판단 기준이 드러납니다.</p>
<table>
<thead>
<tr>
<th>버전</th>
<th>릴리스 유형</th>
<th>정식 출시일</th>
<th>지원 종료일</th>
</tr>
</thead>
<tbody><tr>
<td>.NET 8</td>
<td>LTS</td>
<td>2023년 11월 14일</td>
<td>2026년 11월 10일</td>
</tr>
<tr>
<td>.NET 9</td>
<td>STS</td>
<td>2024년 11월 12일</td>
<td>2026년 11월 10일</td>
</tr>
<tr>
<td>.NET 10</td>
<td>LTS</td>
<td>2025년 11월 11일</td>
<td>2028년 11월 14일</td>
</tr>
<tr>
<td>.NET 11</td>
<td>STS</td>
<td>2026년 11월 10일 예정</td>
<td>2028년 11월 9일 예정</td>
</tr>
</tbody></table>
<p>.NET 10 LTS에서 .NET 11로 옮겨도 지원 종료일이 늘어나지 않습니다. 오히려 현재 계획으로는 .NET 11의 지원이 닷새 먼저 끝납니다. .NET 10을 운영 중인 팀이라면 새 기능과 성능, 개발 경험이 마이그레이션 비용을 상쇄하는지를 기준으로 판단할 수 있습니다. .NET 8이나 .NET 9를 운영 중이라면 두 버전의 지원이 .NET 11 출시 예정일에 끝나므로 .NET 10과 .NET 11을 함께 후보로 놓고 검토할 수 있습니다.</p>
<h2>기존 장비에 영향을 주는 하드웨어 기준선</h2>
<p>.NET 11은 x86/x64의 JIT 및 AOT 최소 기준을 모든 운영체제에서 <code>x86-64-v1</code>에서 <code>x86-64-v2</code>로 상향합니다. <code>SSE3</code>, <code>SSSE3</code>, <code>SSE4.1</code>, <code>SSE4.2</code>, <code>POPCNT</code> 같은 명령어를 지원하지 않는 CPU에서는 .NET 11 애플리케이션이 실행되지 않습니다. <a href="https://learn.microsoft.com/en-us/dotnet/core/whats-new/dotnet-11/runtime#updated-minimum-hardware-requirements">.NET 11 런타임의 최소 하드웨어 요구 사항</a></p>
<p>ReadyToRun 대상도 운영체제에 따라 달라집니다.</p>
<table>
<thead>
<tr>
<th>운영체제</th>
<th>x86/x64 JIT 및 AOT 최소 기준</th>
<th>ReadyToRun 대상</th>
</tr>
</thead>
<tbody><tr>
<td>macOS</td>
<td><code>x86-64-v2</code></td>
<td><code>x86-64-v2</code></td>
</tr>
<tr>
<td>Linux</td>
<td><code>x86-64-v2</code></td>
<td><code>x86-64-v3</code></td>
</tr>
<tr>
<td>Windows</td>
<td><code>x86-64-v2</code></td>
<td><code>x86-64-v3</code></td>
</tr>
</tbody></table>
<p>Linux와 Windows의 ReadyToRun 대상이 <code>x86-64-v3</code>로 올라가지만 실행 최소 기준은 <code>v2</code>를 유지합니다. <code>v2</code>를 지원하는 장비에서도 실행할 수 있습니다. 다만 미리 컴파일된 코드를 사용할 수 없는 구간에서 JIT 컴파일이 늘어 시작 시간이 길어질 수 있습니다.</p>
<p>Arm64에서는 Apple과 Linux의 실행 최소 기준이 유지됩니다. Windows Arm64는 <code>LSE</code> 명령어를 요구하고 ReadyToRun 대상을 <code>armv8.2-a + RCPC</code>로 상향합니다. 최근 클라우드 인스턴스에서는 영향이 제한적일 가능성이 크지만 오래된 사내 서버, 엣지 장비, 고객사 설치형 제품은 별도 확인 대상으로 남습니다.</p>
<h2>비동기 실행과 개발 도구의 기본 동작 변화</h2>
<p>런타임과 SDK의 실행 경로를 살펴보겠습니다. Runtime Async는 비동기 메서드의 중단과 재개를 런타임으로 옮기고, SDK는 NativeAOT CLI와 MSBuild 서버를 기본 경로에 배치합니다. 두 변화 모두 애플리케이션 코드를 크게 바꾸지 않아도 실행과 빌드 과정에 영향을 줄 수 있습니다.</p>
<h3>비동기 실행을 런타임으로 옮기는 Runtime Async</h3>
<p>기존 C# 컴파일러는 <code>async</code> 메서드마다 상태 머신을 생성합니다. Runtime Async V2는 중단과 재개 상태를 런타임에서 관리합니다. Microsoft는 이 구조를 통해 라이브 호출 스택을 간결하게 만들고 디버깅 경험과 실행 오버헤드를 개선하려고 합니다. <a href="https://learn.microsoft.com/en-us/dotnet/core/whats-new/dotnet-11/runtime#runtime-async">.NET 11 Runtime Async 설명</a></p>
<p>현재 애플리케이션 코드에서 Runtime Async를 시험하려면 프로젝트 파일에 다음 설정을 추가합니다.</p>
<pre><code class="language-xml">&lt;PropertyGroup&gt;
  &lt;Features&gt;runtime-async=on&lt;/Features&gt;
&lt;/PropertyGroup&gt;
</code></pre>
<p><code>net11.0</code> 프로젝트에서는 <code>EnablePreviewFeatures</code>를 별도로 켜지 않아도 이 기능을 사용할 수 있습니다. .NET 11 런타임 라이브러리 자체도 Runtime Async를 적용해 빌드합니다. 애플리케이션 코드에서는 여전히 기능을 명시적으로 켭니다.</p>
<p>공개된 예시에서는 라이브 호출 스택에서 컴파일러 상태 머신 프레임이 줄고 실제 메서드 호출 관계가 더 잘 드러납니다. 예외 객체에 기록되는 스택 추적은 기존 방식에서도 정리되므로 차이가 없습니다. NativeAOT와 ReadyToRun도 Runtime Async를 지원합니다. 처리량과 할당량 개선 폭은 애플리케이션의 비동기 호출 패턴에 따라 달라집니다. 대상 서비스의 부하 시험 결과를 기준으로 정식 도입을 판단할 수 있습니다.</p>
<h3>반복 작업을 줄이는 SDK와 테스트 도구</h3>
<p>Preview 7은 NativeAOT 기반 <code>dotnet</code> CLI 경로와 MSBuild 서버를 기본으로 켰습니다. 또한 Microsoft.Testing.Platform을 사용하는 <code>dotnet test</code>에 실행 전체를 제어하는 옵션을 추가했습니다. <a href="https://learn.microsoft.com/en-us/dotnet/core/whats-new/dotnet-11/sdk">.NET 11 SDK와 도구 변경 사항</a></p>
<ul>
<li><p><strong>NativeAOT CLI 경로</strong>: <code>dotnet --info</code>, 도움말, 일부 <code>dotnet sln</code> 명령, 도구 검색과 실행은 NativeAOT 경로를 사용합니다. <code>build</code>, <code>run</code>, <code>test</code>, <code>pack</code>, <code>publish</code>처럼 MSBuild나 NuGet을 프로세스 안에서 사용하는 명령은 관리형 CLI로 돌아갑니다.</p>
</li>
<li><p><strong>기본 MSBuild 서버</strong>: SDK는 준비된 MSBuild 작업자 프로세스를 명령 사이에 유지합니다. 연속해서 실행하는 <code>dotnet build</code>, <code>dotnet test</code>, <code>dotnet run</code>은 MSBuild 시작 비용을 줄일 수 있습니다. 커스텀 빌드 태스크가 프로세스 격리를 전제로 한다면 <code>DOTNET_CLI_USE_MSBUILD_SERVER=false</code>로 기존 동작과 비교할 수 있습니다.</p>
</li>
<li><p><strong>테스트 실행 정책</strong>: Microsoft.Testing.Platform 모드에서는 <code>dotnet test --timeout 90s</code>와 <code>dotnet test --maximum-failed-tests 5</code>처럼 전체 실행의 시간과 실패 수를 제한할 수 있습니다. <code>Microsoft.Build.Traversal</code> 프로젝트도 테스트 대상을 모아 실행할 수 있습니다.</p>
</li>
<li><p><strong>로컬 컨테이너 선택</strong>: SDK의 컨테이너 게시 기능은 Windows에서 <code>wslc</code>, macOS에서 <code>container</code>를 먼저 찾습니다. Docker와 Podman은 그다음 후보로 이동합니다. 빌드 환경에서 특정 엔진 동작에 의존한다면 <code>LocalRegistry</code> 속성으로 대상을 고정할 수 있습니다.</p>
</li>
</ul>
<p>이 변화들은 SDK만 교체한 비교 시험에서도 빌드 시간과 프로세스 수, 커스텀 태스크의 상태 유지 여부를 함께 기록해야 원인을 구분할 수 있음을 보여 줍니다.</p>
<h2>닫힌 타입 집합을 표현하는 C# 15</h2>
<p>C# 15의 타입 모델 변화를 짚어보겠습니다. 이번 버전은 컬렉션 식 인수, 유니언 타입, 닫힌 계층, 확장 인덱서, 레이블을 지정한 <code>break</code>와 <code>continue</code>, 메모리 안전성 작업을 포함합니다. 이 가운데 유니언 타입과 닫힌 계층은 컴파일러가 가능한 타입의 집합을 파악하고 <code>switch</code>의 완전성을 검사할 수 있게 합니다. <a href="https://learn.microsoft.com/en-us/dotnet/csharp/whats-new/csharp-15">C# 15의 새로운 기능</a></p>
<p>유니언 타입으로 결제 결과를 표현하면 다음과 같이 모든 경우를 나눌 수 있습니다.</p>
<pre><code class="language-csharp">public record Paid(string TransactionId);
public record Declined(string Reason);
public record Pending(DateTimeOffset RetryAt);

public union PaymentResult(Paid, Declined, Pending);

static string Describe(PaymentResult result) =&gt; result switch
{
    Paid paid =&gt; $"승인: {paid.TransactionId}",
    Declined declined =&gt; $"거절: {declined.Reason}",
    Pending pending =&gt; $"재시도: {pending.RetryAt:O}",
};
</code></pre>
<p><code>closed</code> 한정자는 같은 어셈블리 안에서만 직접 파생 타입을 선언할 수 있게 합니다. 컴파일러가 직접 파생 타입을 모두 알 수 있으므로 기본 처리 항목이 없는 <code>switch</code>도 완전성을 검사합니다. 닫힘은 자동으로 하위 계층 전체에 전파되지 않습니다. 중간 타입 아래까지 제한하려면 해당 타입에도 <code>closed</code>를 지정합니다.</p>
<p>유니언 타입 명세의 일부 기능은 Preview 7에도 아직 구현되지 않았습니다. 메모리 안전성 개선도 여러 릴리스에 걸쳐 진행할 계획입니다. C# 15 기능을 제품 코드에 반영할 때에는 현재 구문을 최종 사양으로 간주하지 않고 정식 컴파일러와 호환성 문서를 다시 대조할 여지가 있습니다.</p>
<h2>응용 계층에서 체감하는 라이브러리와 프레임워크 변화</h2>
<p>응용 계층의 개선은 작업 부하별로 나누어 보겠습니다. .NET 11 기본 라이브러리는 프로세스 실행, 압축, 직렬화, 진단, 수치 연산을 넓힙니다. ASP.NET Core와 EF Core도 서버 자원 관리와 쿼리 변환을 보완합니다. <a href="https://learn.microsoft.com/en-us/dotnet/core/whats-new/dotnet-11/overview">.NET 11 전체 변경 사항</a></p>
<ul>
<li><p><strong>기본 라이브러리</strong>: <code>Process</code>에 실행과 출력 수집을 다루는 API가 추가됩니다. <code>System.IO.Compression</code>은 Zstandard 압축과 ZIP 암호, CRC32 검증을 지원합니다. <code>System.Text.Json</code>은 C# 유니언 타입 직렬화와 닫힌 타입 계층의 다형성 추론을 지원합니다. IEEE 754 10진 부동소수점 타입과 제네릭 <code>Complex&lt;T&gt;</code>도 수치 처리 범위를 넓힙니다. <a href="https://github.com/dotnet/core/blob/main/release-notes/11.0/preview/preview7/libraries.md">.NET 11 Preview 7 라이브러리 릴리스 노트</a></p>
</li>
<li><p><strong>ASP.NET Core</strong>: Blazor Interactive Server는 숨겨진 브라우저 탭의 회로를 일정 시간이 지난 뒤 멈추고 사용자가 돌아오면 재개할 수 있습니다. 이 기능은 별도 패키지와 설정으로 활성화합니다. Blazor SSR 출력 캐시, 검증 메시지 현지화, OpenAPI 3.2의 Server-Sent Events 표현도 Preview 7에 들어왔습니다. <a href="https://github.com/dotnet/core/blob/main/release-notes/11.0/preview/preview7/aspnetcore.md">ASP.NET Core Preview 7 릴리스 노트</a></p>
</li>
<li><p><strong>Entity Framework Core</strong>: SQL Server 공급자는 <code>int.Parse</code>와 여러 숫자 파싱 메서드를 서버의 <code>CAST</code>로 변환합니다. 참조 탐색을 거치는 <code>GroupBy</code> 집계는 상관 서브쿼리 대신 하나의 조인과 그룹화로 변환할 수 있습니다. 기존 쿼리의 SQL 형태가 달라질 수 있으므로 실제 데이터 분포에서 실행 계획과 수행 시간을 비교할 만합니다. <a href="https://github.com/dotnet/core/blob/main/release-notes/11.0/preview/preview7/efcore.md">EF Core Preview 7 릴리스 노트</a></p>
</li>
</ul>
<p>모든 애플리케이션이 이 기능을 같은 비중으로 활용하지는 않습니다. 압축 파일을 교환하는 서비스는 ZIP 검증 동작을 먼저 볼 수 있고 Blazor Server 서비스는 회로 중단이 메모리 사용량에 미치는 영향을 측정할 수 있습니다. 데이터 접근 비중이 큰 서비스는 EF Core가 생성한 SQL을 기존 버전과 비교하는 방식으로 범위를 좁힐 수 있습니다.</p>
<h2>정식 출시 전 점검 항목</h2>
<p>정식 출시 전 검증 절차를 확인하겠습니다. Microsoft가 공개한 <a href="https://learn.microsoft.com/en-us/dotnet/core/compatibility/11">.NET 11 호환성 변경 목록</a>은 아직 작성 중이며 완전한 목록이 아닙니다. 따라서 Preview 7 시험 결과와 정식 버전의 결과가 같다고 전제하지 않습니다.</p>
<ol>
<li>운영 서버와 빌드 에이전트, 고객사 장비의 CPU 명령어 지원 범위를 수집합니다.</li>
<li>격리한 시험 환경에서 SDK <code>11.0.100-preview.7</code>을 고정하고 기존 소스의 빌드 경고와 테스트 결과를 기록합니다.</li>
<li>MSBuild 서버를 켠 상태와 끈 상태에서 연속 빌드 시간과 커스텀 태스크 동작을 비교합니다.</li>
<li>비동기 호출이 많은 서비스에 한해 Runtime Async를 적용하고 처리량, 지연 시간, 할당량, 라이브 호출 스택을 기존 방식과 비교합니다.</li>
<li>ASP.NET Core와 EF Core 애플리케이션은 생성한 OpenAPI 문서, 인증 흐름, 주요 LINQ 쿼리의 SQL과 실행 계획을 대조합니다.</li>
<li>압축, 인증서, 파일과 파이프, 호스팅 종료 동작과 관련된 호환성 변경을 서비스 사용 범위와 연결합니다.</li>
<li>RC와 정식 버전이 나오면 미리 보기에서 사용한 기능의 상태와 호환성 목록을 다시 확인합니다.</li>
</ol>
<h2>지원 기간보다 실행 조건이 먼저 보이는 업그레이드</h2>
<p>여기까지 정리하면 .NET 11은 비동기 실행 구조와 하드웨어 기준선, 타입 모델, 개발 도구의 기본 동작을 함께 손봅니다. API 추가만 보고 넘어가기에는 실행 환경과 빌드 경로의 변화가 큽니다.</p>
<p>장기 과제로는 Runtime Async와 C# 15가 향후 .NET 애플리케이션의 코드 생성과 타입 설계에 미칠 영향을 살펴볼 수 있습니다. 당장 영향을 주는 사안으로는 x86/x64 최소 기준 상향, MSBuild 서버와 NativeAOT CLI의 기본 활성화, 일부 라이브러리의 동작 변경이 앞에 놓입니다.</p>
<p>.NET 8이나 .NET 9를 운영하는 팀은 2026년 11월 10일의 지원 종료에 맞춰 .NET 10 LTS와 .NET 11 STS 중 어느 쪽으로 옮길지 정할 수 있습니다. .NET 10을 이미 운영한다면 지원 기간 때문에 서두를 이유는 적습니다. 오래된 장비나 설치형 제품을 다룬다면 CPU 기준선부터 조사하고 최신 클라우드 환경과 자동화된 시험 체계를 갖췄다면 Preview 7로 호환성 자료를 모으는 순서가 적합합니다.</p>
]]></content:encoded></item><item><title><![CDATA[OpenAI Codex CLI를 Claude·Gemini·Llama 위에서 돌리기 — C# 50줄로]]></title><description><![CDATA[OpenAI Codex CLI는 Responses API에 lock-in 돼 있습니다. Cadenza.Agent로 IChatClient 앞단에 Responses 호환 서버를 세우면, OpenRouter를 통해 Codex의 두뇌를 자유롭게 고를 수 있습니다.]]></description><link>https://devwrite.ai/cadenza-agent</link><guid isPermaLink="true">https://devwrite.ai/cadenza-agent</guid><category><![CDATA[C#]]></category><category><![CDATA[dotnet]]></category><category><![CDATA[AI]]></category><category><![CDATA[Codex Cli]]></category><category><![CDATA[openrouter]]></category><dc:creator><![CDATA[Jung-hyun, Nam]]></dc:creator><pubDate>Tue, 26 May 2026 15:00:00 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/gql/60adcb82557cc70e51211e5c/b8bb7da8-3f4e-41b6-a909-c8c2f3410880.webp" length="0" type="image/jpeg"/><content:encoded><![CDATA[<blockquote>
<p>OpenAI의 <a href="https://github.com/openai/codex">Codex CLI</a>는 훌륭한 에디터 에이전트 UX를 제공합니다(shell 도구, <code>apply_patch</code>, plan tracking이 모두 갖춰져 있습니다). 문제는 2026년 2월 기준 OpenAI <strong>Responses API</strong>만 지원한다는 점입니다. Chat Completion 지원은 제거됐고(<code>codex-rs/model-provider-info/src/lib.rs</code>의 <code>WireApi</code> enum에는 <code>Responses</code>만 남아 있습니다), Chat Completion만 지원하는 엔드포인트(Ollama, LM Studio, 즐겨 쓰는 Llama runner)는 그대로 막혀버립니다. 이 글은 .NET 10 file-based 프로그램과 <code>Microsoft.Extensions.AI</code>의 <code>IChatClient</code> 추상화를 활용해 50줄짜리 C# 한 파일로 Responses 호환 서버를 세우고, OpenRouter를 거쳐 Codex CLI가 임의의 모델 위에서 동작하도록 만든 과정을 정리합니다.</p>
</blockquote>
<hr />
<h2>들어가며</h2>
<p>Codex CLI는 Responses를 말하는 <strong>어떤</strong> 서버와도 행복하게 대화합니다. <code>model_provider</code> config 블록이 정확히 이걸 위해 존재합니다. 즉, 원하는 모델로 백킹되는 Responses 호환 HTTP 엔드포인트를 세울 수만 있다면, Codex는 일반화된 프론트엔드가 되고 두뇌는 사용자가 고를 수 있습니다.</p>
<p>요즘 저는 다음 트릭을 즐겨 씁니다. <code>Microsoft.Extensions.AI</code>의 벤더 중립 <code>IChatClient</code> 추상화 위에서, OpenAI Chat Completion 서버와 Responses API 서버를 동시에 굴리는 50줄짜리 C# 스크립트를 띄웁니다. 백엔드는 <a href="https://openrouter.ai/">OpenRouter</a>로 향하게 합니다(API 키 하나로 Claude, Gemini, Llama, GPT 등 수백 개 모델을 쓸 수 있습니다). 그리고 Codex에게 OpenAI 대신 이 로컬 스크립트와 대화하라고 알려줍니다.</p>
<p>최종 결과는 <strong>OpenAI Codex CLI가 Anthropic의 Claude 3.5 Sonnet 위에서 동작</strong> 하는 상태입니다(또는 그날 끌리는 다른 모델 위에서).</p>
<h2>구성 요소</h2>
<p>제가 직접 배포하는 <a href="https://www.nuget.org/packages/Cadenza.Agent">Cadenza.Agent</a> 라는 MSBuild SDK를 사용합니다. 단일 <code>.cs</code> 파일을 실행 가능한 에이전트 서버로 바꿔주는 SDK이며, .NET 10의 file-based 프로그램용 단일 파일 스크립팅 SDK 패밀리의 일부입니다(<code>dotnet run script.cs</code> 와 같은 발상이지만 더 풍부한 Tier-1 API(<code>Tool</code>, <code>UseOllama</code>, <code>UseOpenAi</code>, <code>Run</code> 등)를 제공합니다). Agent 변종은 다음을 노출합니다.</p>
<ul>
<li><code>POST /v1/chat/completions</code> — Aider / Continue / Cursor / Copilot BYOK / sgpt 용</li>
<li><code>POST /v1/responses</code> — Codex CLI 용</li>
</ul>
<p>둘 다 사용자가 구성한 동일한 <code>IChatClient</code> 로 백킹됩니다. 백엔드를 바꿔도 wire 포맷은 그대로입니다.</p>
<p>LLM 쪽은 OpenRouter를 사용합니다. OpenAI의 Chat Completion wire 포맷을 다른 base URL로 그대로 제공하기 때문에, <code>Microsoft.Extensions.AI.OpenAI</code> 의 <code>ChatClient</code> 를 그대로 꽂아 쓸 수 있습니다. 환경변수 하나, 임의의 모델.</p>
<p>Codex 설정은 <code>CODEX_HOME</code> 환경변수 트릭을 활용합니다. <code>~/.codex/config.toml</code> 을 편집하는 대신, Codex가 가리키는 디렉터리를 샘플 전용으로 따로 만들면 거기서 새 <code>config.toml</code> 을 읽습니다. 덕분에 사용자의 글로벌 config를 절대 건드리지 않는 자급자족 샘플을 만들 수 있습니다.</p>
<h2>스크립트</h2>
<p>전체 백엔드, 파일 하나입니다.</p>
<pre><code class="language-csharp">#!/usr/bin/env dotnet run
#:sdk Cadenza.Agent@1.0.14

using System.ClientModel;
using OpenAI;

var apiKey = Env.Get("OPENROUTER_API_KEY")
    ?? throw new InvalidOperationException("OPENROUTER_API_KEY env var missing");
var model = Env.Get("OPENROUTER_MODEL") ?? "anthropic/claude-3.5-sonnet";

ServedModelName = "cadenza-codex-openrouter";

// 샘플 전용 Codex home 디렉터리 생성.
var codexHome = Path.Combine(Env.Cwd, ".cadenza-codex-openrouter");
MakeDir(codexHome);

var catalogPath = Path.Combine(codexHome, "cadenza-catalog.json").Replace('\\', '/');
var configToml = $"""
    model          = "cadenza-codex-openrouter"
    model_provider = "cadenza"
    model_catalog_json = "{catalogPath}"

    [model_providers.cadenza]
    name     = "Cadenza.Agent (OpenRouter-backed)"
    base_url = "http://localhost:8080/v1"
    wire_api = "responses"
    env_key  = "CADENZA_API_KEY"
    stream_idle_timeout_ms = 300000
    """;
WriteText(Path.Combine(codexHome, "config.toml"), configToml);

// Catalog JSON: Codex에 우리가 제공하는 모델 id를 선언해서 "Defaulting to
// fallback metadata" 경고를 막습니다. 필드는 codex-rs/protocol/src/
// openai_models.rs의 ModelInfo schema 기준 — 모든 키가 필수입니다.
var catalogJson = """
    {
      "models": [{
        "slug": "cadenza-codex-openrouter",
        "display_name": "Cadenza (OpenRouter)",
        "description": "OpenRouter-backed agent served by Cadenza.Agent",
        "supported_reasoning_levels": [],
        "shell_type": "default",
        "visibility": "list",
        "supported_in_api": true,
        "priority": 50,
        "availability_nux": null,
        "upgrade": null,
        "base_instructions": "",
        "supports_reasoning_summaries": false,
        "support_verbosity": false,
        "default_verbosity": null,
        "apply_patch_tool_type": "freeform",
        "truncation_policy": { "mode": "tokens", "limit": 8192 },
        "supports_parallel_tool_calls": true,
        "context_window": 200000,
        "max_context_window": 200000,
        "auto_compact_token_limit": 180000,
        "effective_context_window_percent": 95,
        "experimental_supported_tools": []
      }]
    }
    """;
WriteText(Path.Combine(codexHome, "cadenza-catalog.json"), catalogJson);

WriteLine($"Codex config generated at: {codexHome}");
WriteLine("In another terminal, run:");
WriteLine($"  $env:CODEX_HOME      = \"{codexHome}\"");
WriteLine($"  $env:CADENZA_API_KEY = \"any-non-empty-string\"");
WriteLine($"  codex");

// OpenRouter를 LLM 백엔드로 연결.
var openAiOptions = new OpenAIClientOptions { Endpoint = new Uri("https://openrouter.ai/api/v1") };
var chatClient = new OpenAI.Chat.ChatClient(model, new ApiKeyCredential(apiKey), openAiOptions)
    .AsIChatClient();

UseChatClient(chatClient);

await Run();
</code></pre>
<p>그게 다입니다. 프로젝트 파일도, <code>.csproj</code> 도, <code>Program.cs</code> 도 없습니다. 맨 위의 <code>#:sdk</code> 디렉티브가 .NET 10 file-based 프로그램 시스템에 "이 스크립트는 <code>Cadenza.Agent</code> SDK를 쓴다"고 알려주고, SDK가 HTTP 서버, Responses wire 포맷, 모든 패키지 레퍼런스를 끌어다 붙이면서 <code>Tool</code>, <code>UseOllama</code>, <code>UseChatClient</code>, <code>Run</code> 을 namespace 없이 바로 호출할 수 있는 이름으로 노출합니다.</p>
<h2>실행</h2>
<p>스크립트를 <code>agent-codex-openrouter.cs</code> 로 저장한 뒤 다음과 같이 실행합니다.</p>
<pre><code class="language-pwsh"># Terminal 1 — 에이전트 서버 기동
$env:OPENROUTER_API_KEY = "sk-or-v1-..."
$env:OPENROUTER_MODEL   = "anthropic/claude-3.5-sonnet"  # 또는 다른 OpenRouter slug
dotnet run agent-codex-openrouter.cs
</code></pre>
<p>첫 실행은 의존성(<code>Microsoft.Extensions.AI</code>, OpenAI SDK, ASP.NET Core)을 가져옵니다. 그 이후로는 1초 안에 부팅됩니다. 스크립트가 두 번째 터미널에 붙여 넣을 정확한 내용을 출력해 줍니다.</p>
<pre><code class="language-text">Codex config generated at: D:\work\.cadenza-codex-openrouter

In another terminal, run:
  $env:CODEX_HOME      = "D:\work\.cadenza-codex-openrouter"
  $env:CADENZA_API_KEY = "any-non-empty-string"
  codex
</code></pre>
<p>이 내용을 다른 터미널에 그대로 붙여 넣고 <code>codex</code> 를 실행하면, Codex UX를 통해 Claude 3.5 Sonnet(또는 선택한 OpenRouter 모델)과 대화하는 상태가 됩니다. <code>shell</code>, <code>apply_patch</code> 같은 도구는 Codex가 매 요청마다 직접 보내고, 에이전트는 그걸 모델에 그대로 전달한 뒤 모델이 내뱉는 <code>function_call</code> 출력을 다시 Codex로 스트림해서 Codex가 로컬에서 실행하게 합니다.</p>
<h2>내부에서 일어나는 일</h2>
<p>Codex가 <code>POST /v1/responses</code> 를 보내면 에이전트는 다음과 같이 처리합니다.</p>
<ol>
<li><strong>Responses input 파싱</strong>. Codex는 <code>message</code> / <code>function_call</code> / <code>function_call_output</code> 배열을 보내는데, 이를 <code>Microsoft.Extensions.AI</code> 의 <code>IList&lt;ChatMessage&gt;</code> 형태로 평탄화합니다.</li>
<li><strong><code>previous_response_id</code> 존중</strong>. Codex는 매 턴마다 전체 히스토리를 다시 보내는 대신 이 id로 연쇄를 만듭니다. 에이전트는 과거 턴들을 bounded in-memory dictionary로 들고 있으면서 context를 재구성합니다.</li>
<li><strong>Codex의 도구를 passthrough</strong>. Codex의 <code>shell</code>, <code>apply_patch</code>, <code>update_plan</code> 은 raw 스키마로 도착합니다. 이들을 JSON 스키마만 있고 실제 핸들러는 없는 <code>PassthroughFunction</code> 인스턴스로 모델에 선언합니다. 이 엔드포인트에서는 function-invocation 미들웨어를 우회하므로, 모델이 내뱉는 함수 호출은 그대로 Codex로 스트림됩니다.</li>
<li><strong><code>IChatClient.GetStreamingResponseAsync</code> 호출</strong>. 구성한 백엔드(OpenRouter, Ollama, OpenAI, Anthropic, Azure OpenAI)로 디스패치됩니다.</li>
<li><strong>Responses SSE로 다시 emit</strong>. <code>ChatResponseUpdate</code> 스트림을 Codex가 기대하는 ~15개의 SSE 이벤트 타입으로 번역합니다(<code>response.created</code>, <code>response.in_progress</code>, <code>response.output_item.added</code>, <code>response.output_text.delta</code>, <code>response.function_call_arguments.delta</code>, <code>response.completed</code> 등).</li>
</ol>
<p>이걸 composable 하게 만드는 핵심은 <code>IChatClient</code> 추상화입니다. Cadenza.Agent는 OpenRouter가 "사실은 Anthropic-한 번-Claude-다음번-Llama"라는 사실에 관심이 없습니다. 그냥 chat client 하나를 보고, 호출하고, 돌아온 걸 Codex가 원하는 wire 포맷으로 직렬화할 뿐입니다.</p>
<h2><code>CODEX_HOME</code> 패턴</h2>
<p>이 부분은 잠깐 멈춰서 칭찬하고 싶습니다. Codex CLI는 <code>CODEX_HOME</code> 환경변수를 honor 해서 <code>config.toml</code> 을 어디서 읽을지 override 합니다(<code>~/.codex/</code> 대신 사용자가 가리키는 디렉터리에서 읽습니다). 샘플은 이걸 최대한 활용합니다. 자기만의 <code>config.toml</code> 과 <code>cadenza-catalog.json</code> 이 들어 있는 sample-local 디렉터리를 만들고, 정확히 어떤 <code>$env:CODEX_HOME = ...</code> 줄을 붙여 넣어야 하는지 출력해 줍니다.</p>
<p>결과적으로 <strong>글로벌 <code>~/.codex/config.toml</code> 이 그대로 보존</strong>됩니다. 서로 다른 샘플(Ollama 백엔드, OpenRouter 백엔드, gpt-5 reasoning effort 튜닝)이 각자 격리된 디렉터리를 가지게 되고, 10개를 동시에 둬도 서로 안 부딪힙니다. 동료와 설정을 공유하고 싶다면 <code>.cs</code> 파일 하나만 건네면 됩니다. 동료의 codex 명령은 그 스크립트가 생성한 로컬 디렉터리를 가리키게 됩니다.</p>
<h2>"Defaulting to fallback metadata" 경고 해제</h2>
<p>Codex가 모르는 모델 id를 가리키면 context window와 출력 limit에 기본 metadata로 폴백하고, 매 턴마다 경고를 출력합니다.</p>
<pre><code class="language-text">⚠ Model metadata for `cadenza-codex-openrouter` not found.
   Defaulting to fallback metadata; this can degrade performance and cause issues.
</code></pre>
<p>이건 <code>model_catalog_json</code> config 키가 우리 slug를 선언한 JSON 파일을 가리키게 하면 사라집니다. 스키마는 <code>codex-rs/protocol/src/openai_models.rs::ModelInfo</code> 이며 필수 필드가 17개입니다. 샘플은 완전한 catalog 항목을 포함합니다. 만약 더 작은 context window를 가진 모델(예: <code>openai/gpt-4o-mini</code> 의 128K)로 바꾼다면, <code>context_window</code> 와 <code>max_context_window</code> 를 그에 맞춰 낮춰야 합니다. Codex는 이 숫자에 맞춰 prompt를 truncate 하므로, 과대 선언은 실제 backing 모델에서 조용히 token overflow를 일으킵니다.</p>
<p>추가 주의: <code>model_catalog_json</code> 은 Codex의 번들 카탈로그와 <strong>merge되지 않고 대체</strong>됩니다. <code>gpt-5-codex</code> 같이 기존 슬러그를 같이 쓰고 싶다면 우리 JSON에도 같이 넣어둬야 합니다.</p>
<h2>만난 footgun 하나 (고친 이야기)</h2>
<p>처음 돌렸을 때 Codex가 시작을 거부했습니다.</p>
<pre><code class="language-text">Error loading configuration: failed to parse model_catalog_json path
`...\cadenza-catalog.json` as JSON: expected value at line 1 column 1
</code></pre>
<p>원인은 BOM이었습니다. .NET의 <code>Encoding.UTF8</code> 은 BOM-emitting variant 이므로, <code>File.WriteAllText(path, content, Encoding.UTF8)</code> 는 데이터 앞에 <code>EF BB BF</code> 를 prepend 합니다. Rust의 <code>serde_json</code>(Codex가 쓰는 라이브러리)은 이걸 거부합니다. RFC 8259 spec을 엄격히 준수하므로, JSON 구현은 BOM을 추가해선 안 됩니다.</p>
<p>Cadenza의 <code>Fs.WriteText</code> 도 그 BOM-emitting 기본값을 그대로 물려받고 있었습니다. <code>new UTF8Encoding(encoderShouldEmitUTF8Identifier: false)</code> 로 바꿔서 SDK <code>1.0.14</code> 로 출시했습니다. 같은 수정이 <code>Console.OutputEncoding</code> 에도 적용됩니다. 그게 없으면 <code>dotnet-script | jq</code> 가 파이프를 깨뜨립니다.</p>
<p>엄격한 파서로 파일을 쓰는 본인의 .NET 코드도 점검할 만한 부분입니다. 만약 <code>File.WriteAllText(path, text, Encoding.UTF8)</code> 을 거친다면, BOM을 emit 하고 있는 상태입니다. 한 줄짜리 수정으로 해결됩니다.</p>
<pre><code class="language-csharp">File.WriteAllText(path, text, new UTF8Encoding(encoderShouldEmitUTF8Identifier: false));
</code></pre>
<h2>이 패턴이 의미 있는 이유</h2>
<p>Codex CLI의 tool loop는 정말 유용합니다. Responses API lock-in은 그대로 두면 열린 도구 생태계를 죽이는 종류의 vendor coupling으로 느껴집니다. <code>model_providers</code> config + <code>wire_api = "responses"</code> 라는 탈출구는 OpenAI가 명시적으로 "다른 곳에서 쓰고 싶을 수 있다는 걸 인정한다"고 말한 것이며, 그 제안을 받아들이는 게 올바른 행동입니다.</p>
<p>여러분이 통제하는 Responses 서버가 한 번 생기면 생태계가 열립니다.</p>
<ul>
<li>Codex를 무료 로컬 Ollama 모델 위에 올려 오프라인 작업을 하고 싶다면? <code>UseChatClient</code> 를 <code>UseOllama</code> 로 바꾸면 됩니다. 같은 스크립트, 같은 Codex config, 다른 두뇌.</li>
<li>모든 Codex 세션이 보게 될 프로젝트 핀 시스템 프롬프트를 주입하고 싶다면? <code>Run()</code> 호출 전에 넣으면 됩니다.</li>
<li>모든 Codex 턴을 감사 목적으로 로깅하고 싶다면? <code>IChatClient</code> 를 본인의 미들웨어로 감싸면 됩니다.</li>
<li>prompt 크기에 따라 OpenRouter와 로컬 모델을 라운드 로빈하고 싶다면? C#으로 로직 쓰고 같은 엔드포인트로 제공하면 됩니다.</li>
</ul>
<p>이걸 지속 가능하게 만드는 건 단일 파일 포맷입니다. 유지보수해야 할 프로젝트도 없고, 관리해야 할 SDK도 없고, 배포해야 할 별도 바이너리도 없습니다. 그냥 레포에 복사해 넣을 <code>.cs</code> 파일 하나입니다. <code>dotnet run script.cs</code> 가 동작하는 환경이라면(.NET 10 이상에서 동작합니다) 스크립트가 실행됩니다.</p>
<h2>직접 해보기</h2>
<p>.NET 10 설치 후 다음과 같이 실행합니다.</p>
<pre><code class="language-pwsh">dotnet new install Cadenza.Templates
dotnet new cadenza-agent -n my-codex-backend -o ./my-codex-backend
cd my-codex-backend
# my-codex-backend.cs를 위의 OpenRouter 패턴으로 편집
$env:OPENROUTER_API_KEY = "sk-or-v1-..."
dotnet run my-codex-backend.cs
</code></pre>
<p>또는 <a href="https://github.com/rkttu/cadenza/tree/main/samples">Cadenza 레포</a>에서 바로 실행 가능한 샘플을 받아도 됩니다. <code>agent-codex-openrouter.cs</code> 가 위에 적은 그 버전입니다. 레포에는 <code>agent-codex-backend.cs</code>(Ollama 변형)와 <code>agent-openrouter.cs</code>(Aider / Continue / Cursor용 Chat Completion 변형)도 같이 들어 있습니다.</p>
<p>이게 도움이 됐다면 어떤 백엔드를 연결했는지 알려주세요. 누군가 fine-tuned 로컬 모델과 오프라인용 로컬 fallback 조합으로 Codex를 돌리는지가 다음 실험거리입니다. 궁금합니다.</p>
<hr />
<p><em>Cadenza는 MIT 라이선스입니다. 소스: <a href="https://github.com/rkttu/cadenza">https://github.com/rkttu/cadenza</a>. 글 작성 시점 기준 <code>Cadenza.Agent</code> 패키지는 <code>1.0.14</code> 입니다.</em></p>
]]></content:encoded></item><item><title><![CDATA[C#에서 허깅페이스 모델 호출하기: DotNetPy 0.6.0으로 Whisper · sentence-transformers · Stable Diffusion 돌려보기]]></title><description><![CDATA[DotNetPy 0.6.0으로 C# 앱 안에서 CPython C API를 직접 호출해 Whisper, sentence-transformers, Stable Diffusion을 실행한 경험과, PEP 703 free-threaded 빌드까지 검증한 설계 과정을 정리합니다.]]></description><link>https://devwrite.ai/dotnetpy-huggingface-from-csharp</link><guid isPermaLink="true">https://devwrite.ai/dotnetpy-huggingface-from-csharp</guid><category><![CDATA[dotnet]]></category><category><![CDATA[C#]]></category><category><![CDATA[Python]]></category><category><![CDATA[huggingface]]></category><category><![CDATA[AI]]></category><dc:creator><![CDATA[Jung-hyun, Nam]]></dc:creator><pubDate>Sun, 10 May 2026 15:00:00 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/gql/60adcb82557cc70e51211e5c/a6cca4cc-8b5a-43b9-893a-cdc0aee56b90.webp" length="0" type="image/jpeg"/><content:encoded><![CDATA[

<blockquote>
<p>주말에 작은 C# 라이브러리 <a href="https://github.com/rkttu/dotnetpy">DotNetPy</a> 의 0.6.0을 출시했습니다. CPython C API를 직접 호출해 .NET 앱 안에서 Python을 실행하는 인터롭 라이브러리입니다. 이 글은 0.6.0에 포함된 세 가지 머신러닝 샘플 — <code>sentence-transformers</code> 의미 검색, Whisper 음성 인식, Stable Diffusion Turbo 이미지 생성 — 을 어떻게 묶었고, 그 과정에서 PEP 703 free-threaded CPython까지 어떻게 검증했는지에 대한 기록입니다.</p>
</blockquote>
<hr />
<h2>시작점: C#만 손에 잡혔는데 모델은 허깅페이스에 있을 때</h2>
<p>몇 달에 한 번씩 같은 패턴이 반복됩니다. 자막용 Whisper가 필요하거나, 검색용 sentence-transformer가 필요하거나, 가끔은 Stable Diffusion 같은 모델을 써야 하는데 정작 손에 잡은 도구는 C# 한 가지입니다. 이럴 때 흔히 쓰는 우회로는 하나씩 다 결정적인 단점이 있습니다.</p>
<ul>
<li><strong>ONNX로 변환.</strong> 비전이나 인코더 모델에는 잘 맞지만, 새 아키텍처나 diffusion 파이프라인에서는 변환 자체가 별도 프로젝트가 됩니다.</li>
<li><strong>Python 마이크로서비스로 띄우기.</strong> 프로세스가 두 개, 배포 시나리오가 두 개, 그리고 핫 패스에 네트워크 홉 하나가 더 붙습니다.</li>
<li><strong>외부 API 호출.</strong> 비용이 들고, 인터넷이 필요하고, 데이터가 박스 밖으로 나갑니다.</li>
<li><strong><a href="https://github.com/pythonnet/pythonnet">pythonnet</a> 이나 <a href="https://github.com/tonybaloney/csnakes">CSnakes</a> 사용.</strong> 견실한 선택지지만, pythonnet은 아직 Native AOT를 지원하지 않고, CSnakes는 Source Generator 기반 워크플로를 강제합니다. 그리고 두 라이브러리 모두 free-threaded CPython 빌드에 대한 공개된 검증을 아직 내놓지 않았습니다.</li>
</ul>
<p>저는 좀 더 얇은 선택지를 원했습니다. <strong>C# 코드 안에 Python 스니펫을 문자열로 인라인 작성하고, 배열을 그대로 넘기고, JSON 형태로 결과를 돌려받고, 전체가 AOT 컴파일되어 단일 바이너리로 나오는</strong> 형태입니다. 그것이 DotNetPy의 목표였고, 아래 세 샘플은 모두 GPU 없는 평범한 Windows 11 노트북에서 처음부터 끝까지 동작합니다.</p>
<hr />
<h2>샘플 1 — <code>sentence-transformers</code> 로 의미 검색</h2>
<p>첫 번째 샘플은 작은 코퍼스를 임베딩한 뒤, 쿼리를 인코딩해서 가장 비슷한 top-K 문장을 받아옵니다. 반환 값은 <code>DotNetPyValue</code> 인데, 내부적으로는 JSON 문서를 감싼 래퍼이고 <code>GetString()</code>, <code>GetInt32()</code>, <code>GetDouble()</code>, 경로 기반 프로퍼티 접근으로 .NET 세계로 되돌아옵니다.</p>
<pre><code class="language-csharp">using DotNetPy;
using DotNetPy.Uv;

using var project = PythonProject.CreateBuilder()
    .WithProjectName("dotnetpy-ml-embeddings")
    .WithPythonVersion("==3.12.*")
    .AddDependencies(
        "sentence-transformers==2.7.0",
        "transformers==4.40.2",
        "torch&gt;=2.2,&lt;2.5")
    .Build();

await project.InitializeAsync();
var executor = project.GetExecutor();

executor.Execute(@"
import numpy as np
from sentence_transformers import SentenceTransformer
model = SentenceTransformer('all-MiniLM-L6-v2')
");

var corpus = new[]
{
    "Python is a popular programming language for data science.",
    "C# and .NET are great for building enterprise applications.",
    "Rust offers memory safety without garbage collection.",
    "Pizza is delicious with various toppings.",
    // …
};
var query = "Tell me about programming languages";

using var hits = executor.ExecuteAndCapture(@"
corpus_emb = model.encode(corpus, normalize_embeddings=True)
query_emb = model.encode([query], normalize_embeddings=True)[0]
sims = corpus_emb @ query_emb
top_idx = np.argsort(-sims)[:3]
result = [
    {'rank': int(rank + 1), 'score': float(sims[i]), 'text': corpus[int(i)]}
    for rank, i in enumerate(top_idx)
]
", new Dictionary&lt;string, object?&gt; { { "corpus", corpus }, { "query", query } });

foreach (var hit in hits!.RootElement.EnumerateArray())
{
    Console.WriteLine($"  {hit.GetProperty("rank").GetInt32()}. " +
                      $"[{hit.GetProperty("score").GetDouble():F3}] " +
                      $"{hit.GetProperty("text").GetString()}");
}
</code></pre>
<p>실제 출력은 이렇게 나옵니다.</p>
<pre><code class="language-text">  1. [0.578] Python is a popular programming language for data science.
  2. [0.370] C# and .NET are great for building enterprise applications.
  3. [0.203] Rust offers memory safety without garbage collection.
</code></pre>
<p>여기서 흥미로운 지점은 <strong>두 세계의 경계</strong>입니다. <code>corpus</code> 는 .NET 의 <code>string[]</code> 이고 <code>query</code> 는 .NET 의 <code>string</code> 인데, Python 쪽에서는 네이티브 list 와 str 로 자연스럽게 도착합니다. 점수가 매겨진 결과는 JSON 문서 한 덩어리로 되돌아오고, .NET 에서는 평소처럼 <code>JsonElement</code> API 로 읽으면 끝입니다.</p>
<hr />
<h2>샘플 2 — Whisper 로 음성-텍스트 변환</h2>
<p>모양은 거의 같습니다. 모달리티만 바뀐 셈입니다. <code>.wav</code> 나 <code>.flac</code> 파일 경로를 넘기면 텍스트와 chunk 단위 타임스탬프가 돌아옵니다. 한 가지 핵심은 <strong>오디오 바이트가 .NET ↔ Python 경계를 절대 건너지 않는다</strong>는 것입니다. Python 이 파일을 직접 열고, 경계로는 구조화된 transcript 만 흐릅니다.</p>
<pre><code class="language-csharp">var executor = project.GetExecutor();
executor.Execute(@"
from transformers import pipeline
import torch
asr = pipeline(
    'automatic-speech-recognition',
    model='openai/whisper-base.en',
    chunk_length_s=30,
    return_timestamps=True,
    torch_dtype=torch.float32,
)
");

using var transcript = executor.ExecuteAndCapture(@"
out = asr(audio_path)
chunks = [
    {'start': float(c['timestamp'][0]), 'end': float(c['timestamp'][1]),
     'text': c['text'].strip()}
    for c in out.get('chunks', [])
    if c['timestamp'][0] is not None and c['timestamp'][1] is not None
]
result = {'text': out['text'].strip(), 'chunks': chunks}
", new Dictionary&lt;string, object?&gt; { { "audio_path", audioPath } });

Console.WriteLine($"\"{transcript!.GetString("text")}\"");
foreach (var c in transcript.RootElement.GetProperty("chunks").EnumerateArray())
    Console.WriteLine($"  [{c.GetProperty("start").GetDouble():F2}s → " +
                      $"{c.GetProperty("end").GetDouble():F2}s] " +
                      $"{c.GetProperty("text").GetString()}");
</code></pre>
<p>샘플에 함께 들어있는 퍼블릭 도메인 JFK 클립을 돌리면 이런 결과가 나옵니다.</p>
<pre><code class="language-text">"And so my fellow Americans, ask not what your country can do for you,
 ask what you can do for your country."

  [0.00s → 11.00s] And so my fellow Americans, ask not what your country can
                   do for you, ask what you can do for your country.
</code></pre>
<p><code>whisper-base.en</code> 은 290 MB 짜리 모델이고, 11초 클립을 제 노트북 CPU에서 transcribe 하는 데 7초쯤 걸립니다. 두 번째 실행부터는 모델과 가상환경이 캐시되어 첫 실행의 다운로드 비용이 사라집니다.</p>
<hr />
<h2>샘플 3 — Stable Diffusion Turbo 로 텍스트-이미지</h2>
<p><code>stabilityai/sd-turbo</code> 는 1-step diffusion 모델입니다. CPU 에서 512×512 한 장을 만드는 데 약 30초, 요즘 GPU 에서는 2초 안팎입니다. 여기서도 .NET 쪽은 이미지 바이트를 보지 않습니다. Python 이 PNG 를 디스크에 저장하고, 메타데이터만 돌려줍니다.</p>
<pre><code class="language-csharp">executor.Execute(@"
import torch
from diffusers import AutoPipelineForText2Image
pipe = AutoPipelineForText2Image.from_pretrained(
    'stabilityai/sd-turbo',
    torch_dtype=torch.float32,
    safety_checker=None, requires_safety_checker=False,
)
pipe.set_progress_bar_config(disable=True)
");

using var meta = executor.ExecuteAndCapture(@"
import time, os
t0 = time.time()
img = pipe(prompt=prompt, num_inference_steps=1, guidance_scale=0.0).images[0]
elapsed = time.time() - t0
out_path = os.path.join(out_dir, 'generated.png')
img.save(out_path)
result = {
    'path': out_path,
    'width': img.size[0],
    'height': img.size[1],
    'size_bytes': os.path.getsize(out_path),
    'elapsed_seconds': elapsed,
}
", new Dictionary&lt;string, object?&gt;
{
    { "prompt", "a serene mountain lake at sunset, oil painting style" },
    { "out_dir", outDir },
});

Console.WriteLine($"  Saved:   {meta!.GetString("path")}");
Console.WriteLine($"  Size:    {meta.GetInt32("width")}×{meta.GetInt32("height")} px, " +
                  $"{meta.GetInt32("size_bytes"):N0} bytes");
Console.WriteLine($"  Inference: {meta.GetDouble("elapsed_seconds"):F2}s");
</code></pre>
<p>출력은 다음과 같습니다.</p>
<pre><code class="language-text">  Saved:   .../samples/ml-image-gen/output/generated.png
  Size:    512×512 px, 434,242 bytes
  Inference: 31.19s
</code></pre>
<p>세 샘플을 거치면서 강조하고 싶은 패턴이 하나 있습니다. <strong>경계를 건너는 것은 구조화된 데이터뿐</strong>이라는 것입니다. PNG 바이트 (~400KB), 임베딩 행렬, float32 텐서는 모두 Python 쪽에 머무릅니다. .NET 쪽에서는 작은 프롬프트 한 줄이 들어가고 작은 JSON 객체 하나가 돌아오는 것만 보면 됩니다. 이 분리가 Native AOT 호환을 가능하게 해주는 가장 중요한 설계 결정입니다.</p>
<hr />
<h2>설치와 첫 실행</h2>
<p>라이브러리 자체는 평범한 NuGet 패키지입니다.</p>
<pre><code class="language-bash">dotnet add package DotNetPy --version 0.6.0
</code></pre>
<p>위 샘플을 그대로 따라하고 싶다면, 저장소의 <a href="https://github.com/rkttu/dotnetpy/tree/main/samples"><code>samples/</code></a> 디렉터리에 위 세 가지에 더해 AOT 로 빌드한 네이티브 DLL을 C export 로 호출하는 <a href="https://github.com/rkttu/dotnetpy/tree/main/samples/native-aot"><code>native-aot</code></a> 컨슈머가 같이 들어있습니다. DotNetPy를 C / C++ / Rust 호스트에 임베드하는 경로입니다.</p>
<p>ML 샘플들은 <a href="https://docs.astral.sh/uv/">uv</a> 를 사용해서 C# 안에서 선언적으로 Python + 허깅페이스 스택을 프로비저닝합니다.</p>
<pre><code class="language-csharp">using var project = PythonProject.CreateBuilder()
    .WithProjectName("my-app")
    .WithPythonVersion("==3.12.*")
    .AddDependencies("transformers==4.40.2", "torch&gt;=2.2,&lt;2.5")
    .Build();

await project.InitializeAsync();
</code></pre>
<p>이것이 전부입니다. 별도의 Python 설치도 필요 없고, venv 를 직접 만들 일도 없습니다.</p>
<hr />
<h2>진짜 신경 쓴 부분 — PEP 703 free-threaded Python</h2>
<p>인터롭 라이브러리 관점에서 흥미로운 변곡점이 2025–26년에 도착했습니다. CPython 3.13 에 <strong>free-threaded 빌드</strong> (<code>t</code> 접미사가 붙은 <code>python3.13t</code>) 가 도입되면서, GIL 이 사라지고 동시에 실행되는 스레드들이 <em>진짜로</em> 병렬로 Python 코드를 실행할 수 있게 됩니다. ML 서빙에는 환상적인 변화입니다. 한 프로세스 안에 추론 워커를 여러 개 두고 싶을 테니까요. 동시에, 기존 GIL 가정 위에 쓰여 있던 수많은 라이브러리의 암묵적 불변 조건이 깨지는 시점이기도 합니다.</p>
<p>특히 pythonnet 도 이 작업을 진행 중인데, <a href="https://github.com/pythonnet/pythonnet/pull/2721">PR #2721</a> 이 필요한 작업을 다섯 가지 범주로 정리해 두었습니다.</p>
<ol>
<li>Refcount 레이아웃 변경 (<code>ob_refcnt</code> 가 split 구조로 바뀜)</li>
<li>동시 타입 / 객체 캐시 경합</li>
<li><code>Reflection.Emit</code> 스레드 안전성</li>
<li><code>GCHandle</code> 슬롯 소유권 원자성</li>
<li>Finalizer / <code>Py_Finalize</code> 경합</li>
</ol>
<p>DotNetPy 0.6.0 을 만들 때 저는 pythonnet의 PR 을 일종의 <strong>감사용 체크리스트</strong> 처럼 활용했습니다. 다섯 가지 범주를 하나하나 적용해 보면서 DotNetPy 가 같은 함정에 빠지는지 점검한 것입니다. 결과적으로, <strong>다섯 항목 중 네 가지는 DotNetPy 의 설계 자체가 해당 사항을 비껴갑니다.</strong> .NET 과 Python 의 타입 시스템을 다리 놓지 않고, CLR 타입을 Python 서브클래스로 만들지도 않으며, <code>Reflection.Emit</code> 을 사용하지 않고, Python 에 <code>GCHandle</code> 슬롯을 노출하지도 않고, <code>Py_Finalize</code> 를 호출하지도 않기 때문입니다. 다섯 번째 항목(finalizer / shutdown)은 <code>SafeHandle.ReleaseHandle</code> 의 <code>Py_DecRef</code> 호출 주변에 명시적인 <code>PyGILState_Ensure</code> 가드를 두어 해결했습니다.</p>
<p>감사 과정에서 실제로 발견되어 0.6.0 에서 수정한 문제는 다음과 같습니다.</p>
<ul>
<li><strong>공유 <code>__main__</code> globals 안의 내부 임시 변수 이름 충돌.</strong> 모든 헬퍼 변수(<code>_json_result</code>, <code>_is_valid</code>, …)를 <code>Interlocked.Increment</code> 로 호출마다 고유하게 발급하도록 바꿔서, 동시에 실행되는 두 호출자가 같은 슬롯을 두고 경합하지 않도록 했습니다.</li>
<li><strong><code>Evaluate</code> 가 공유 <code>result</code> 전역을 흘려보내던 문제.</strong> 같은 패턴으로 해결했습니다. 호출마다 고유한 싱크 이름을 발급하고, <code>finally</code> 에서 깔끔하게 정리합니다.</li>
<li>위 두 수정이 미묘하게 맞물리는데, 출시 시점에도 사용자 변수 주입(<code>Execute</code> / <code>ExecuteAndCapture</code> 의 <code>variables:</code> 파라미터) 은 여전히 공유 <code>__main__</code> globals 로 들어갑니다. 동시 호출자가 같은 사용자 변수 이름을 쓰면 충돌이 그대로 남아 있습니다.</li>
</ul>
<p>세 번째 문제에 대한 해법이 0.6.0 의 가장 눈에 띄는 추가 기능, 격리된 실행기 팩토리 메서드입니다.</p>
<pre><code class="language-csharp">using var iso = Python.CreateIsolated();
iso.Execute("import json");
iso.Execute("data = {'k': 1}");   // `data` 는 이 실행기만 봅니다
</code></pre>
<p><code>CreateIsolated()</code> 는 자체 Python dict (사전 채워진 <code>__builtins__</code> 포함) 을 소유한 실행기를 만듭니다. 격리된 실행기들은 공유 싱글톤, 그리고 다른 격리 실행기들과 같은 프로세스에서 공존하지만, 서로 사이로 변수가 새지 않습니다.</p>
<p>이 덕분에 동시 ML 패턴이 굉장히 간결해집니다.</p>
<pre><code class="language-csharp">Parallel.For(0, Environment.ProcessorCount, threadId =&gt;
{
    using var iso = Python.CreateIsolated();
    iso.Execute("import torch; from transformers import pipeline");
    iso.Execute(@"
asr = pipeline('automatic-speech-recognition',
               model='openai/whisper-base.en')
");
    using var r = iso.ExecuteAndCapture(@"
out = asr(audio_path)
result = {'text': out['text']}
", new Dictionary&lt;string, object?&gt; { { "audio_path", path } });

    Console.WriteLine(r?.GetString("text"));
});
</code></pre>
<p>free-threaded CPython 빌드 위에서 이 루프는 <strong>진짜로 병렬로 돕니다.</strong> 모든 워커가 자기만의 <code>asr</code> 파이프라인과 자기만의 Python 네임스페이스를 가집니다. 기존 GIL 빌드에서는 같은 코드가 정확하게 동작하긴 해도 인터프리터에서 직렬화됩니다. 어차피 이건 어떤 인터롭 라이브러리를 써도 부딪히는 벽이라서 DotNetPy 가 해결할 수 있는 문제는 아닙니다.</p>
<p>세 가지 빌드 조합으로 매트릭스 검증을 마쳤습니다.</p>
<table>
<thead>
<tr>
<th>Python 빌드</th>
<th>단위 테스트</th>
<th>Native AOT 컨슈머</th>
</tr>
</thead>
<tbody><tr>
<td>CPython 3.13 (GIL, auto-discovered)</td>
<td>209 / 1 / <strong>0</strong></td>
<td>8 / 8 ✅</td>
</tr>
<tr>
<td>CPython 3.13.13t (free-threaded)</td>
<td>205 / 5 / <strong>0</strong></td>
<td>8 / 8 ✅</td>
</tr>
<tr>
<td>CPython 3.14.4t (free-threaded)</td>
<td>205 / 5 / <strong>0</strong></td>
<td>8 / 8 ✅</td>
</tr>
</tbody></table>
<p>전체 감사 결과는 <a href="https://github.com/rkttu/dotnetpy/blob/main/docs/FREETHREADED-AUDIT.md"><code>docs/FREETHREADED-AUDIT.md</code></a> 에 정리해 두었습니다. 의도적으로 공개 문서로 두었습니다. "검증했습니다" 라고 말할 때 그 말이 정확히 무슨 의미인지를 독자가 직접 읽어볼 수 있도록 하기 위해서입니다.</p>
<hr />
<h2>솔직하게 짚어둘 한계</h2>
<p>몇 가지는 분명하게 짚고 가야 합니다.</p>
<ul>
<li><strong>DotNetPy 는 아직 0.6.0.</strong> 실험 단계이며, 프로덕션 안정 단계가 아닙니다. 적지 않은 패턴이 아직 정리되는 중입니다.</li>
<li><strong>Python ML 스택 자체가 완전히 free-threaded 가 아닙니다.</strong> PyTorch 의 FT 지원은 활발히 마이그레이션 중이고, NumPy 2.1+ 가 PEP 703 을 지원합니다. <code>transformers</code> 와 <code>diffusers</code> 는 동작은 하지만, 내부 C 확장 모듈들의 상태는 제각각입니다. 업스트림 스택이 따라잡기 전까지는 DotNetPy 인터롭 계층에서는 free-threaded 환경의 정합성을 얻지만, Python 쪽 ML 성능 자체는 여전히 라이브러리 내부 락을 통해 직렬화될 수 있습니다.</li>
<li><strong>Native AOT 퍼블리시는 플랫폼별 C 툴체인을 요구합니다.</strong> Windows 는 Visual Studio C++ build tools, Linux 는 <code>clang</code> / <code>lld</code> 가 필요합니다. AOT 컴파일하는 일반 .NET 앱과 동일한 제약입니다.</li>
<li><strong>JSON 마샬링이 데이터 평면.</strong> 모든 결과 변수는 Python 쪽에서 직렬화되고 .NET 쪽에서 <code>System.Text.Json</code> 으로 역직렬화됩니다. Native AOT 호환을 얻기 위한 의도된 트레이드오프입니다. 결과 객체가 매우 큰 워크로드라면, 여러 값을 한 번의 capture 호출 안에서 묶고 작은 구조화 요약만 반환하는 패턴을 권장합니다.</li>
</ul>
<hr />
<h2>더 알아보려면</h2>
<ul>
<li><strong>코드</strong>: <a href="https://github.com/rkttu/dotnetpy">https://github.com/rkttu/dotnetpy</a></li>
<li><strong>NuGet</strong>: <code>dotnet add package DotNetPy --version 0.6.0</code></li>
<li><strong>샘플</strong>: <a href="https://github.com/rkttu/dotnetpy/tree/main/samples/ml-embeddings"><code>samples/ml-embeddings</code></a>, <a href="https://github.com/rkttu/dotnetpy/tree/main/samples/ml-whisper"><code>samples/ml-whisper</code></a>, <a href="https://github.com/rkttu/dotnetpy/tree/main/samples/ml-image-gen"><code>samples/ml-image-gen</code></a> — 각각 <code>dotnet run sample.cs</code> 한 번으로 끝납니다.</li>
<li><strong>Free-threaded 감사 문서</strong>: <a href="https://github.com/rkttu/dotnetpy/blob/main/docs/FREETHREADED-AUDIT.md"><code>docs/FREETHREADED-AUDIT.md</code></a></li>
<li><strong>pythonnet / CSnakes / IronPython 과의 비교 (의사 결정 트리 포함)</strong>: <a href="https://github.com/rkttu/dotnetpy/blob/main/docs/COMPARISON.md"><code>docs/COMPARISON.md</code></a></li>
<li><strong>영문 원문</strong>: <a href="https://dev.to/rkttu/speech-search-and-stable-diffusion-calling-huggingface-from-c-2bkk">dev.to</a></li>
</ul>
<p>"C# 으로 지금 막 발표된 허깅페이스 모델을 어떻게 돌리지" 라는 질문에 한 가지 답이 될 수 있었으면 좋겠습니다. 이슈, PR, 댓글 모두 환영합니다. 한국 닷넷 커뮤니티에서 같은 고민을 하고 계신 분들이 있다면 한 번 시도해 보시고 피드백 주세요.</p>
]]></content:encoded></item><item><title><![CDATA[RoleEntryPoint에서 FoundryCBAgent까지 — .NET 개발자가 본 Microsoft Foundry Hosted Agent의 아키텍처]]></title><description><![CDATA[Microsoft Foundry Hosted Agent의 아키텍처를 Windows Azure Cloud Services부터 이어온 .NET PaaS 계보 속에서 분석합니다.]]></description><link>https://devwrite.ai/hosted-agent-deep-dive</link><guid isPermaLink="true">https://devwrite.ai/hosted-agent-deep-dive</guid><category><![CDATA[Azure]]></category><category><![CDATA[dotnet]]></category><category><![CDATA[AI]]></category><category><![CDATA[PaaS]]></category><category><![CDATA[microsoft foundry]]></category><dc:creator><![CDATA[Jung-hyun, Nam]]></dc:creator><pubDate>Mon, 16 Mar 2026 15:00:00 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/gql/60adcb82557cc70e51211e5c/af4a70ac-096a-47fc-a57c-ee3fdeb0bf2e.webp" length="0" type="image/jpeg"/><content:encoded><![CDATA[<blockquote>
<p>이 글은 2026년 3월 기준, 퍼블릭 프리뷰 상태인 Microsoft Foundry Hosted Agent의 설계를 .NET 아키텍처의 계보 속에서 분석합니다. 현시점에서 프로덕션 사용을 권장하는 글이 아니며, 엔터프라이즈 AI 아키텍트가 주목해야 할 설계 방향성에 초점을 맞춥니다.</p>
</blockquote>
<hr />
<h2>에이전트를 프로덕션에 올린다는 것</h2>
<p>엔터프라이즈에서 AI 에이전트를 프로덕션에 배포하려 할 때, 현재 선택지는 두 가지입니다.</p>
<p><strong>선언적 에이전트.</strong> Microsoft Foundry 포털에서 프롬프트와 도구를 조합해 만드는 no-code 방식입니다. 빠르게 만들 수 있지만, 복잡한 분기 로직이나 멀티스텝 워크플로우, 외부 시스템과의 정밀한 연동을 코드로 제어할 수 없습니다. 일정 수준을 넘어서는 순간 한계에 부딪힙니다.</p>
<p><strong>자체 컨테이너.</strong> 에이전트 로직을 직접 코드로 작성하고, 컨테이너에 담아 배포하는 방식입니다. 자유도는 완전하지만, HTTP 서버 구성, 인증, 대화 상태 관리, 스케일링, 모니터링, 버전 관리를 전부 직접 구현해야 합니다. 그리고 결정적으로, 이 컨테이너 안에서 에이전트가 무엇을 하는지 <strong>플랫폼이 전혀 알 수 없습니다.</strong> LLM을 어떻게 호출했는지, 도구를 어떤 순서로 사용했는지, 왜 그런 응답을 생성했는지가 블랙박스입니다.</p>
<p>Hosted Agent는 이 사이의 공백을 메웁니다. 코드 수준의 자유도를 유지하면서, 에이전트의 동작이 플랫폼에 구조적으로 투명하게 노출되는 제3의 경로입니다.</p>
<hr />
<h2>Windows Azure를 기억하는가</h2>
<p>지금의 Microsoft Azure는 2010년 2월에 <strong>Windows Azure</strong>라는 이름으로 상용 출시되었습니다. 2014년 3월에 Microsoft Azure로 리브랜딩되기까지, 이 플랫폼의 정체성은 지금과는 상당히 달랐습니다.</p>
<p>Windows Azure는 태생적으로 <strong>PaaS 플랫폼</strong>이었습니다. VM을 직접 다루는 IaaS는 초기에 존재하지 않았고, 2012년에 가서야 Virtual Machines가 추가되었습니다. 출발점은 Cloud Services(Web Role, Worker Role), SQL Azure(지금의 Azure SQL Database), Storage Services 같은 관리형 서비스였습니다. 개발자가 인프라를 의식하지 않고 코드와 구성 파일만으로 배포하는 것이 핵심 약속이었고, 이것은 당시 AWS가 EC2 중심의 IaaS로 시장을 열어가던 것과는 근본적으로 다른 접근이었습니다.</p>
<p>2014년 리브랜딩 이후, Azure는 AWS를 강하게 의식하면서 IaaS 기능을 빠르게 확충했습니다. VM, VNET, Load Balancer, 그리고 이후의 AKS까지. 시장에서 "클라우드 = 가상 머신을 빌려 쓰는 것"이라는 인식이 지배적이었던 시기에 IaaS를 강화한 것은 상업적으로 옳은 판단이었지만, 그 과정에서 Windows Azure 시절의 PaaS 중심 철학은 다소 희석되었습니다.</p>
<p>그러나 Microsoft의 본래 강점은 언제나 PaaS와 SaaS에 있었습니다. .NET Framework, Visual Studio, SQL Server, Office 365, SharePoint — 이 회사는 개발자와 정보 근로자에게 <strong>관리형 플랫폼</strong> 위에서 일하도록 하는 데 30년 이상의 역사를 가지고 있습니다. Windows Azure 시절의 Cloud Services가 그 철학의 클라우드 확장이었고, 이후의 App Service, Azure Functions, Container Apps도 같은 맥락에 있습니다.</p>
<p>이 배경을 이해해야, Hosted Agent가 왜 이런 형태로 설계되었는지가 명확해집니다. Microsoft는 AI 에이전트라는 새로운 워크로드 앞에서, IaaS적 접근(자체 컨테이너를 직접 관리)이 아니라 PaaS적 접근(플랫폼이 호스팅하고 개발자는 로직에 집중)을 선택한 것입니다. 이것은 AWS가 Bedrock Agents에서 취하는 방향과도, Google이 Vertex AI Agent Builder에서 취하는 방향과도 다릅니다. Microsoft의 고유한 PaaS DNA가 AI 시대에 다시 발현된 것으로 볼 수 있습니다.</p>
<hr />
<h2>어디서 많이 본 패턴</h2>
<p>.NET 개발자라면, 그리고 Azure의 역사를 함께 걸어온 개발자라면, Hosted Agent의 아키텍처에서 강한 기시감을 느낄 것입니다.</p>
<p>Windows Azure Cloud Services 시절을 떠올려 보겠습니다. 그때도 "개발자는 비즈니스 로직만 작성하고, 플랫폼이 제공하는 호스트 프로세스가 그 로직을 감싸서 인프라에 올린다"는 것이 핵심 약속이었습니다. <code>RoleEntryPoint</code>를 상속하고, <code>OnStart()</code>, <code>Run()</code>, <code>OnStop()</code>을 구현하면, <code>WaWorkerHost.exe</code>가 그 코드를 로딩해서 실행했고, Fabric Controller가 인스턴스의 프로비저닝과 헬스 모니터링을 담당했습니다.</p>
<p>Hosted Agent의 구조는 이 패턴을 AI 에이전트 도메인으로 재해석한 것입니다.</p>
<table>
<thead>
<tr>
<th>Windows Azure Cloud Services</th>
<th>Microsoft Foundry Hosted Agent</th>
</tr>
</thead>
<tbody><tr>
<td><code>RoleEntryPoint</code> 추상 클래스</td>
<td><code>FoundryCBAgent</code> / <code>IAgentInvocation</code> 인터페이스</td>
</tr>
<tr>
<td><code>OnStart()</code>, <code>Run()</code>, <code>OnStop()</code></td>
<td><code>InvokeAsync()</code> + liveness/readiness 프로브</td>
</tr>
<tr>
<td><code>WaIISHost.exe</code> / <code>WaWorkerHost.exe</code></td>
<td>AgentServer 어댑터 내장 Kestrel 서버</td>
</tr>
<tr>
<td><code>.csdef</code> + <code>.cscfg</code></td>
<td><code>agent.yaml</code> + 환경 변수</td>
</tr>
<tr>
<td>Fabric Controller</td>
<td>Agent Service Runtime</td>
</tr>
<tr>
<td>DiagnosticMonitor (WAD)</td>
<td>OpenTelemetry 자동 계측 + Application Insights</td>
</tr>
<tr>
<td>Input/Internal Endpoint 선언</td>
<td>Foundry Responses API 프로토콜 자동 노출</td>
</tr>
</tbody></table>
<p>핵심 공통점은 세 가지입니다. 플랫폼의 호스트 프로세스가 개발자 코드를 로딩하는 구조, 플랫폼이 정의한 계약(contract)에 맞춰 코드를 작성해야 하는 규칙, 인프라 관심사가 플랫폼으로 이전되는 효과. 15년 전에 Cloud Services에서 작동했던 이 설계 원칙이, 이제 AI 에이전트라는 새로운 워크로드에 다시 적용되고 있습니다.</p>
<hr />
<h2>Hosting Adapter의 실체: 사전 구성된 Kestrel</h2>
<p>.NET 관점에서 Hosting Adapter의 실체를 정확히 파악하는 것이 중요합니다.</p>
<p><code>Azure.AI.AgentServer.Core</code> 패키지는 ASP.NET Core의 Kestrel 서버, DI 컨테이너, 미들웨어 파이프라인을 공유합니다. 일반적인 ASP.NET Core 앱과 기술 스택의 근간이 같습니다. 차이는, <code>WebApplicationBuilder</code>를 직접 구성하는 대신, <strong>어댑터 패키지가 제공하는 사전 구성된 호스트를 사용한다</strong>는 점입니다.</p>
<p>일반적인 ASP.NET Core 앱에서 <code>Program.cs</code>에 <code>builder.Services.AddXxx()</code>, <code>app.MapPost()</code>, <code>app.UseMiddleware()</code>를 직접 조합하는 것과 달리, Hosted Agent에서는 이 조합이 이미 끝나 있는 상태에서 <code>IAgentInvocation.InvokeAsync</code> 하나만 구현합니다. 라우팅(<code>/responses</code>, <code>/liveness</code>, <code>/readiness</code>), SSE 스트리밍을 위한 chunked response 설정, OpenTelemetry 미들웨어 등록, 인증 처리 파이프라인이 전부 어댑터 내부에서 구성 완료된 채로 제공됩니다.</p>
<pre><code class="language-text">기술 스택의 수직 단면:

┌─────────────────────────────────────────┐
│  IAgentInvocation.InvokeAsync           │  ← 개발자가 구현
│  (에이전트 비즈니스 로직)                    │
├─────────────────────────────────────────┤
│  Azure.AI.AgentServer 어댑터 계층          │  ← 패키지가 제공
│  - Foundry Responses API 프로토콜 변환      │
│  - SSE 스트리밍 이벤트 직렬화               │
│  - OpenTelemetry 자동 계측                 │
│  - OAuth consent 처리                     │
│  - Tool Client 프로비저닝                  │
├─────────────────────────────────────────┤
│  ASP.NET Core 미들웨어 파이프라인            │  ← 공유 스택
│  Kestrel HTTP 서버                        │
│  DI 컨테이너, 설정 시스템                    │
└─────────────────────────────────────────┘
</code></pre>
<p>Python 쪽은 Starlette(ASGI 프레임워크)를 내장 웹 서버로 사용합니다. "어댑터가 임베디드 웹 서버를 내장한다"는 아키텍처 패턴은 동일하되, 언어별로 해당 생태계에서 가장 자연스러운 웹 스택을 선택한 것입니다.</p>
<hr />
<h2>왜 어댑터를 우회할 수 없는가</h2>
<p>"Foundry가 기대하는 엔드포인트 스펙을 직접 구현하면 되지 않느냐"는 질문이 나올 수 있습니다. <code>/responses</code>, <code>/liveness</code>, <code>/readiness</code> 세 개의 경로만 맞추면 되는 것 아닌가?</p>
<p>이것이 단순한 REST 엔드포인트 몇 개를 맞추는 문제가 아닌 이유는, <strong>HTTP 프로토콜 수준의 재정의가 요구되기 때문</strong>입니다.</p>
<p>에이전트의 응답은 일반적인 JSON 한 덩어리가 아닙니다. <code>ResponseTextDeltaEvent</code> → <code>ResponseTextDoneEvent</code> → <code>ResponseContentPartDoneEvent</code> → <code>ResponseOutputItemDoneEvent</code> → <code>ResponseCompletedEvent</code>로 이어지는 <strong>순서가 정해진 이벤트 체인</strong>입니다. 이것이 HTTP 응답으로 나갈 때는 chunked transfer encoding 기반의 SSE 스트림이 되어야 하고, 각 이벤트의 JSON 스키마, 시퀀스 넘버링, 종료 조건까지 프로토콜이 규정합니다.</p>
<p>.NET의 <code>IAgentInvocation</code> 구현 코드를 보면 이 구조가 명확해집니다. <code>InvokeAsync</code>가 <code>IAsyncEnumerable&lt;ResponseStreamEvent&gt;</code>를 반환하고, 어댑터가 이 스트림을 받아 SSE로 변환합니다. 각 이벤트에는 시퀀스 번호(<code>seq</code>)가 부여되고, <code>ResponseOutputItemDoneEvent</code>에는 완성된 콘텐츠가, <code>ResponseCompletedEvent</code>에는 전체 응답 객체가 포함되어야 합니다.</p>
<p>이것을 직접 구현한다는 것은, "이 경로에서 이 순서로 이 스키마의 이벤트를 청크 단위로 스트리밍하되, 비동기 제너레이터의 백프레셔 처리와 연결 중단 시의 정리까지 올바르게 수행한다"는 뜻이 됩니다. 여기에 OpenTelemetry span의 시작/종료 타이밍, OAuth consent가 필요한 상황에서의 특수 응답 포맷까지 더하면, 사실상 어댑터 패키지를 처음부터 다시 만드는 것과 같습니다.</p>
<p>그래서 정확한 표현은 이것입니다: <strong>에이전트 로직은 무엇으로든 작성할 수 있지만, HTTP 서버 계층은 어댑터 패키지가 제공하는 것을 사용하는 것이 공식 경로.</strong> "웹 서버를 자유롭게 선택한다"가 아니라, "어댑터가 제공하는 사전 구성된 웹 서버 위에서, 비즈니스 로직 구현의 자유도가 완전하다"는 것입니다.</p>
<p>Cloud Services 시절, IIS를 직접 설정해서 Web Role처럼 동작하게 만들 수는 있었겠지만, <code>RoleEntryPoint</code>를 상속하고 <code>.csdef</code>를 작성해야 Fabric Controller가 그 인스턴스를 관리할 수 있었던 것과 정확히 같은 맥락입니다.</p>
<hr />
<h2>엔터프라이즈 AI가 놓치고 있는 것: 계약 기반 투명성</h2>
<p>Hosted Agent의 진짜 가치는 "구현이 단순해진다"가 아닙니다.</p>
<p>자체 컨테이너 방식의 근본적 문제는 <strong>불투명성</strong>입니다. 컨테이너 안에서 에이전트가 LLM을 어떻게 호출하고, 도구를 어떤 순서로 사용했는지, 왜 그 응답을 생성했는지를 플랫폼이 알 수 없습니다. 개발자가 로깅을 아무리 열심히 해도, 그것은 개발자의 자발적 노력이지 플랫폼이 보장하는 구조가 아닙니다.</p>
<p>Hosted Agent는 어댑터가 강제하는 프로토콜 계약 덕분에, 에이전트의 동작이 플랫폼에 구조적으로 노출됩니다.</p>
<p><strong>관측 가능성(Observability)이 계약 수준에서 보장됩니다.</strong> 어댑터가 HTTP 요청, 모델 호출, 도구 사용을 자동으로 계측합니다. 개발자가 OpenTelemetry를 설정할 필요가 없습니다. Foundry 포털의 Traces 탭에서 에이전트가 어떤 판단을 거쳐 응답에 도달했는지를 확인할 수 있습니다.</p>
<p><strong>정량적 평가(Evaluation)가 플랫폼에 통합됩니다.</strong> 어댑터가 강제하는 응답 프로토콜 덕분에, 플랫폼이 응답 구조를 이해할 수 있고, Intent Resolution, Task Adherence, Tool Call Accuracy 같은 빌트인 평가 메트릭을 직접 적용할 수 있습니다. 자체 컨테이너에서는 이 평가 파이프라인을 처음부터 별도로 구축해야 합니다.</p>
<p><strong>거버넌스가 아이덴티티 수준에서 적용됩니다.</strong> 퍼블리시 전에는 프로젝트의 시스템 할당 관리 ID로 동작하다가, 퍼블리시 시 전용 에이전트 아이덴티티가 분리되고, Microsoft Entra 에이전트 레지스트리에 등록됩니다. 조직 차원에서 "어떤 에이전트가 어떤 리소스에 접근 가능한지"를 중앙에서 통제할 수 있습니다.</p>
<p><strong>대화 상태가 플랫폼 관리입니다.</strong> 컨테이너 자체는 stateless한 HTTP 서버로 동작하고, "이 사용자와 이전에 어떤 대화를 했는지"는 Agent Service Runtime이 <code>CreateResponse</code> 요청 안에 컨텍스트로 주입합니다. 개발자가 대화 상태 저장소를 직접 구현할 필요가 없습니다.</p>
<p>이것이 PoC를 넘어 프로덕션으로 갈 때 결정적인 차이입니다. 보안 팀은 "에이전트가 무엇을 했는지 추적 가능한가?"를 묻고, 컴플라이언스 팀은 "에이전트의 접근 권한이 관리되는가?"를 묻고, 경영진은 "에이전트의 품질을 어떻게 측정하는가?"를 묻습니다. 자체 컨테이너 방식에서는 이 모든 질문에 "직접 구현했습니다"라고 답해야 하지만, Hosted Agent에서는 "플랫폼이 보장합니다"라고 답할 수 있습니다.</p>
<hr />
<h2>런타임 동작 모델</h2>
<p>실제 운영 환경에서 Hosted Agent의 동작을 정확히 이해하는 것이 중요합니다.</p>
<p>에이전트 코드를 담은 어셈블리는 "세션별로 인스턴스화되는 에이전트"가 아니라, "요청이 올 때마다 주입된 컨텍스트에 기반해서 stateless하게 응답을 생성하는 서비스"로 동작합니다.</p>
<pre><code class="language-text">[사용자 A 세션] ──┐
[사용자 B 세션] ──┤   Agent Service Runtime
[사용자 C 세션] ──┘   (대화 상태 관리 + 라우팅)
                          │
                 ┌────────┼────────┐
                 ▼        ▼        ▼
             [Replica 1] [Replica 2] [Replica 3]
             (동일한 컨테이너 이미지, stateless)
             (각 요청에 해당 세션의 대화 컨텍스트가 주입됨)
</code></pre>
<p>세션마다 별도 컨테이너가 뜨는 것이 아닙니다. 소수의 replica가 다수의 세션 요청을 처리하되, 각 요청에 해당 세션의 대화 컨텍스트가 플랫폼으로부터 주입됩니다. 에이전트 로직은 하나인데, 대화의 연속성은 플랫폼이 보장하는 구조입니다.</p>
<p><code>min-replicas 0</code>으로 설정하면 scale-to-zero까지 가능하고, 첫 요청 시 cold start가 발생합니다. 지속적인 응답 지연이 허용되지 않는 환경에서는 <code>min-replicas 1</code> 이상을 유지하는 것이 권장됩니다.</p>
<hr />
<h2>코드로 보는 Hosted Agent: MCP 도구 통합 예제</h2>
<p>아키텍처 논의를 코드 수준으로 구체화하겠습니다. Microsoft의 공식 샘플 중 Hosted Agent에서 MCP 서버를 도구로 사용하는 C# 예제를 중심으로, 앞서 설명한 개념들이 코드에서 어떻게 실현되는지 해설합니다.</p>
<h3>환경 설정과 에이전트 정의</h3>
<pre><code class="language-csharp">var endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("AZURE_FOUNDRY_PROJECT_ENDPOINT is not set.");
var model = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_MODEL_ID") ?? "gpt-4.1-mini";

const string AgentName = "MicrosoftLearnAgent";
const string AgentInstructions = "You answer questions by searching the Microsoft Learn content only.";
</code></pre>
<p>첫 번째로 주목할 것은, 에이전트 코드에 HTTP 서버 구성 코드가 <strong>전혀 없다</strong>는 점입니다. Kestrel 설정, 라우트 매핑, 미들웨어 파이프라인 — 일반적인 ASP.NET Core 앱이라면 반드시 있어야 할 이 코드들이 보이지 않습니다. 이것이 앞서 설명한 "어댑터가 사전 구성된 Kestrel을 제공한다"는 것의 실체입니다. 개발자는 에이전트의 이름, 지시문, 사용할 모델만 정의합니다.</p>
<h3>MCP 도구 선언</h3>
<pre><code class="language-csharp">var mcpTool = new MCPToolDefinition(
    serverLabel: "microsoft_learn",
    serverUrl: "https://learn.microsoft.com/api/mcp");
mcpTool.AllowedTools.Add("microsoft_docs_search");
</code></pre>
<p><code>MCPToolDefinition</code>은 세 가지를 선언합니다. <code>serverLabel</code>은 이 MCP 서버의 고유 식별자이고, <code>serverUrl</code>은 원격 MCP 서버의 엔드포인트이며, <code>AllowedTools</code>는 해당 서버가 노출하는 도구 중 이 에이전트가 사용할 수 있는 도구의 허용 목록입니다.</p>
<p>여기서 중요한 것은, MCP 서버와의 실제 통신을 <strong>에이전트 코드가 직접 수행하지 않는다</strong>는 점입니다. 자체 컨테이너 방식이었다면 MCP 클라이언트를 초기화하고, 도구 목록을 열거하고, 호출 결과를 파싱하는 코드를 직접 작성해야 합니다. Hosted Agent에서는 도구 정의만 선언하면, Agent Service Runtime이 MCP 서버와의 통신을 플랫폼 수준에서 관리합니다. 이것이 "계약 기반 투명성"의 구체적 예시입니다 — 플랫폼이 도구 호출을 중개하기 때문에, 어떤 도구가 언제 호출되었는지를 자동으로 추적할 수 있습니다.</p>
<h3>Persistent Agent 생성</h3>
<pre><code class="language-csharp">var persistentAgentsClient = new PersistentAgentsClient(endpoint, new DefaultAzureCredential());

var agentMetadata = await persistentAgentsClient.Administration.CreateAgentAsync(
    model: model,
    name: AgentName,
    instructions: AgentInstructions,
    tools: [mcpTool]);
</code></pre>
<p><code>PersistentAgentsClient</code>는 Foundry 서비스에 에이전트를 <strong>서버 사이드로 등록</strong>합니다. 이 호출 이후, 에이전트는 Foundry 포털에서 확인할 수 있는 관리 대상이 됩니다. <code>DefaultAzureCredential</code>은 개발 환경에서는 Azure CLI 인증을, 배포 환경에서는 Managed Identity를 자동으로 선택합니다 — 앞서 논의한 아이덴티티 전환 구조의 클라이언트 측 구현입니다.</p>
<h3>도구 승인 정책과 실행</h3>
<pre><code class="language-csharp">var runOptions = new ChatClientAgentRunOptions()
{
    ChatOptions = new()
    {
        RawRepresentationFactory = (_) =&gt; new ThreadAndRunOptions()
        {
            ToolResources = new MCPToolResource(serverLabel: "microsoft_learn")
            {
                RequireApproval = new MCPApproval("never"),
            }.ToToolResources()
        }
    }
};
</code></pre>
<p><code>RequireApproval</code>은 MCP 도구 호출에 대한 승인 정책입니다. <code>"never"</code>는 자동 실행, <code>"always"</code>는 매 호출마다 사용자 승인을 요구합니다. 이것은 자체 컨테이너에서는 직접 구현해야 할 Human-in-the-Loop 패턴을 플랫폼이 표준화한 것입니다. 엔터프라이즈 환경에서 "이 에이전트가 외부 도구를 호출할 때 반드시 사람의 승인을 거쳐야 한다"는 정책을 코드 한 줄로 적용할 수 있습니다.</p>
<pre><code class="language-csharp">AIAgent agent = await persistentAgentsClient.GetAIAgentAsync(agentMetadata.Value.Id);
AgentSession session = await agent.CreateSessionAsync();

var response = await agent.RunAsync(
    "Please summarize the Azure AI Agent documentation related to MCP Tool calling?",
    session,
    runOptions);

Console.WriteLine(response);
</code></pre>
<p><code>agent.RunAsync()</code>가 호출되면, 요청은 Foundry의 Agent Service Runtime으로 전달되고, Runtime이 MCP 서버에 도구 호출을 중개하고, LLM에 컨텍스트를 전달하며, 최종 응답을 스트리밍 이벤트로 반환합니다. 개발자 코드에서는 이 과정이 단일 <code>await</code> 호출로 추상화됩니다.</p>
<pre><code class="language-csharp">await persistentAgentsClient.Administration.DeleteAgentAsync(agent.Id);
</code></pre>
<p>마지막의 정리 코드는, 에이전트가 Foundry의 관리 대상 리소스임을 보여줍니다. 자체 컨테이너라면 "컨테이너를 중지한다"이지만, Hosted Agent에서는 "에이전트를 삭제한다"입니다. 관리 단위가 인프라가 아니라 에이전트 자체입니다.</p>
<h3>이 코드가 말해주는 것</h3>
<p>전체 코드에서 HTTP, 스트리밍, 프로토콜, 인증, 상태 관리에 대한 코드는 <strong>한 줄도 없습니다.</strong> 개발자가 작성한 것은 "어떤 모델을 쓸 것인가, 어떤 도구를 쓸 것인가, 어떤 지시문을 줄 것인가, 승인 정책은 무엇인가"뿐입니다. 나머지는 전부 플랫폼이 처리합니다.</p>
<p>이것이 <code>RoleEntryPoint</code>에서 <code>OnStart()</code>와 <code>Run()</code>만 구현하면 나머지를 Fabric Controller가 처리했던 것과 같은 패턴입니다. 15년의 시차를 두고, 동일한 설계 철학이 AI 에이전트 도메인에서 반복되고 있습니다.</p>
<hr />
<h2>현실 점검: 아직 청사진이다</h2>
<p>솔직하게 말해야 할 것이 있습니다.</p>
<p>2026년 3월 현재, Hosted Agent는 퍼블릭 프리뷰입니다. 그리고 Hosted Agent 이전에, no-code 에이전트에서 MCP 서버를 연결해 두 턴 이상 대화를 시도하면 에이전트가 크래시되는 수준입니다. 대화 상태에 도구 호출 이력이 누적되면서 직렬화/역직렬화 과정에서 문제가 생기거나, MCP 세션의 수명 관리가 대화 턴 경계에서 제대로 처리되지 않는 것으로 보입니다.</p>
<p>MCP 서버 통합의 제약 사항조차 아직 규정되지 않은 상태입니다. 어떤 transport를 지원해야 하는지(SSE인지, Streamable HTTP인지), 어떤 MCP 프로토콜 버전을 요구하는지, 도구 스키마에 제약이 있는지 같은 기본적인 사양이 공개 문서에 없습니다. MCP 프로토콜 자체도 진화 중이고, Foundry가 이 중 어떤 버전과 transport를 공식 지원할 것인지 확정되지 않았습니다.</p>
<p>프리뷰 단계의 명시적 제약도 있습니다. Azure 구독당 Hosted Agent를 포함한 Foundry 리소스 100개, 리소스당 최대 200개의 Hosted Agent, replica는 최소 2개, 최대 5개까지. 프라이빗 네트워킹도 아직 지원되지 않습니다. 빌링은 2026년 4월 1일 이후 시작 예정입니다.</p>
<p>이 모든 것을 종합하면, 현 시점에서 Hosted Agent까지 도입하는 것은 시기상조입니다. PoC를 진행한다면 자체 컨테이너에서 LLM API를 직접 호출하는 방식이 더 예측 가능합니다. 플랫폼 투명성을 포기하는 대신, 크래시 원인을 직접 제어할 수 있기 때문입니다.</p>
<hr />
<h2>그럼에도 지금 알아야 하는 이유</h2>
<p>Hosted Agent의 아키텍처를 지금 이해해두는 것은, GA 이후의 마이그레이션 경로를 확보하기 위해서입니다.</p>
<p>자체 컨테이너로 PoC를 진행하더라도, 에이전트의 비즈니스 로직을 <code>CreateResponse</code> → <code>Response | Stream[ResponseStreamEvent]</code> 계약에 가깝게 설계해두면, 나중에 어댑터로 감싸는 것은 비교적 단순한 작업이 됩니다. .NET에서는 <code>IAgentInvocation.InvokeAsync(CreateResponseRequest, AgentInvocationContext, CancellationToken)</code> 시그니처를 염두에 두고 로직을 구성하면 됩니다.</p>
<p>그리고 이 아키텍처가 안정화되었을 때 가장 큰 혜택을 받는 것은, 복잡한 에이전트 로직을 코드로 정밀하게 제어하면서도 엔터프라이즈 거버넌스 요구사항을 충족해야 하는 조직입니다. 바로 지금 "선언적 에이전트로는 부족하고, 자체 컨테이너로는 감당이 안 되는" 사이에 끼어 있는 팀들입니다.</p>
<p>Microsoft는 Cloud Services에서 App Service로, App Service에서 Azure Functions로, Functions에서 Container Apps로 이어지는 관리형 컴퓨트의 추상화 수준을 꾸준히 높여왔습니다. Hosted Agent는 그 계보의 최신 지점에서, AI 에이전트라는 특정 워크로드에 맞춘 도메인 특화 PaaS를 시도하고 있습니다. <code>RoleEntryPoint</code>에서 <code>FoundryCBAgent</code>까지, 15년에 걸친 "플랫폼이 호스트 프로세스를 제공하고 개발자는 비즈니스 로직에 집중한다"는 약속이 AI 시대에도 유효한지 검증하는 실험이 지금 진행 중입니다.</p>
]]></content:encoded></item><item><title><![CDATA[.NET의 새로운 장르: NuGet-Free Single File C# 코딩의 시대]]></title><description><![CDATA[.NET 10의 file-based app과 Runtime Async가 만나면, NuGet 없이 BCL만으로 빠르고 타입 안전한 단일 파일 C# 코딩이 가능해집니다.]]></description><link>https://devwrite.ai/nuget-free-single-file-csharp</link><guid isPermaLink="true">https://devwrite.ai/nuget-free-single-file-csharp</guid><category><![CDATA[dotnet]]></category><category><![CDATA[C#]]></category><dc:creator><![CDATA[Jung-hyun, Nam]]></dc:creator><pubDate>Sun, 15 Mar 2026 15:00:00 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/gql/60adcb82557cc70e51211e5c/af69ea0a-73d6-4a44-9c94-c86656e80bd1.webp" length="0" type="image/jpeg"/><content:encoded><![CDATA[<blockquote>
<p>C#이 스크립트 언어처럼 가벼워지는 것이 아니라, 스크립트 언어가 부러워할 만큼 빨라지는 것이다.</p>
</blockquote>
<h2>들어가며</h2>
<p>.NET 10에서 도입된 <code>dotnet run file.cs</code> — 이른바 <strong>file-based app</strong> — 은 <code>.csproj</code> 파일 없이 단일 <code>.cs</code> 파일만으로 C# 코드를 실행할 수 있게 해주는 기능입니다. 하지만 현재 이 기능의 실행 속도는 첫 실행 기준 Windows에서 약 1.5초, WSL2에서 약 0.8초 수준입니다. Python의 <code>python script.py</code>가 50ms 내외인 것과 비교하면 아직 "스크립팅"이라 부르기 민망한 수준이죠.</p>
<p>그런데 지금 .NET 생태계에서 동시에 진행 중인 두 가지 큰 변화가 이 그림을 근본적으로 바꿀 수 있습니다:</p>
<ol>
<li><strong><code>dotnet run file.cs</code>의 빌드 최적화</strong> — MSBuild를 우회하여 Roslyn을 직접 호출하는 전략</li>
<li><strong>Runtime Async (async2)</strong> — async/await를 런타임 수준에서 처리하여 상태 머신 오버헤드를 제거</li>
</ol>
<p>이 두 가지가 만나면, <strong>NuGet 패키지 없이 BCL만으로 작성하는 단일 파일 C# 프로그램</strong> 이 하나의 독립적인 코딩 장르로 자리잡을 수 있습니다. 이 글에서는 그 기술적 기반과 미래상을 그려봅니다.</p>
<hr />
<h2>File-Based App의 현재: MSBuild라는 병목</h2>
<h3>본질: <code>.csproj</code> + <code>.cs</code> = 하나의 <code>.cs</code></h3>
<p>File-based app은 C# 스크립트(<code>.csx</code>)와 근본적으로 다릅니다. <code>.csx</code>는 별도의 스크립트 호스트가 런타임에 해석하지만, file-based app은 <strong>컴파일 타임에 가상 <code>.csproj</code>로 변환</strong> 되어 정규 빌드 파이프라인을 거칩니다. 결과물은 일반 프로젝트와 동일한 managed DLL입니다.</p>
<pre><code class="language-cs">// 이 디렉티브들이 곧 .csproj의 내용
#:package System.CommandLine@2.0.0

// 여기서부터가 실제 코드
Console.WriteLine("Hello, file-based app!");
</code></pre>
<h3>문제: MSBuild의 무게</h3>
<p><code>dotnet run hello.cs</code>를 실행하면 내부적으로 벌어지는 일:</p>
<table>
<thead>
<tr>
<th>단계</th>
<th>소요 시간(대략)</th>
<th>설명</th>
</tr>
</thead>
<tbody><tr>
<td>CLI 로드</td>
<td>~200ms</td>
<td>.NET 런타임 JIT, CLI 명령 디스패치</td>
</tr>
<tr>
<td>MSBuild 엔진 로드</td>
<td>~200ms</td>
<td>빌드 엔진 초기화</td>
</tr>
<tr>
<td>SDK targets 평가</td>
<td>~300ms</td>
<td>수백 개의 <code>.props</code>/<code>.targets</code> 파일 순차 평가</td>
</tr>
<tr>
<td>NuGet restore</td>
<td>~100ms+</td>
<td>패키지 의존성 해결 (캐시된 경우)</td>
</tr>
<tr>
<td>Roslyn 컴파일</td>
<td>~200ms</td>
<td>실제 C# → IL 변환</td>
</tr>
<tr>
<td>실행</td>
<td>~50ms</td>
<td>결과 DLL 실행</td>
</tr>
</tbody></table>
<p><strong>총 ~1.5초</strong> 중 실제 "컴파일 + 실행"은 ~250ms에 불과합니다. 나머지는 전부 MSBuild 관련 오버헤드입니다.</p>
<hr />
<h2>MSBuild를 우회하는 전략: <code>BuildLevel.Csc</code></h2>
<p>dotnet/sdk 팀은 이 병목을 인식하고, <strong>MSBuild를 아예 건너뛸 수 있는 경우를 식별하여 Roslyn 컴파일러를 직접 호출</strong> 하는 최적화 경로를 구현했습니다.</p>
<h3>세 단계의 빌드 레벨</h3>
<pre><code class="language-text">dotnet run hello.cs
       │
       ▼
  입력 변경 감지
       │
  ┌────┼────────────┐
  ▼    ▼            ▼
None  Csc          All
  │    │            │
  ▼    ▼            ▼
스킵  csc만 호출   MSBuild 풀 빌드
~200ms ~400-630ms  ~1.5s
</code></pre>
<ul>
<li><strong><code>BuildLevel.None</code></strong>: 아무것도 변하지 않았으므로 이전 빌드 결과를 그대로 실행</li>
<li><strong><code>BuildLevel.Csc</code></strong>: <code>.cs</code> 코드만 바뀌었으므로 Roslyn 컴파일러 서버에 직접 요청 — <strong>MSBuild 완전 우회</strong></li>
<li><strong><code>BuildLevel.All</code></strong>: 패키지나 SDK 설정이 바뀌었으므로 MSBuild 풀 빌드 실행</li>
</ul>
<h3><code>BuildLevel.Csc</code>의 조건</h3>
<p>이 빠른 경로를 타려면:</p>
<ul>
<li>✅ <code>#:package</code> 디렉티브가 없거나 변경 없음</li>
<li>✅ <code>#:sdk</code> 디렉티브가 없거나 변경 없음</li>
<li>✅ <code>Directory.Build.props</code> 등 implicit build file 없음</li>
<li>✅ <code>-c Release</code> 같은 글로벌 프로퍼티 커스터마이징 없음</li>
<li>✅ 이전 빌드의 캐시된 컴파일러 인자(<code>.rsp</code>)가 존재</li>
</ul>
<p>이 모든 조건을 충족하면, SDK는 가상 프로젝트 파일을 만들지도, MSBuild를 로드하지도 않고, 캐시된 <code>.rsp</code> 파일을 들고 <strong>Roslyn 컴파일러 서버에 직접 named pipe로 요청</strong> 을 보냅니다.</p>
<pre><code class="language-cs">// CSharpCompilerCommand.cs에서 실제로 일어나는 일
var buildRequest = BuildServerConnection.CreateBuildRequest(
    requestId: EntryPointFileFullPath,
    language: RequestLanguage.CSharpCompile,
    arguments: ["/noconfig", "/nologo", $"@{rspPath}"],
    workingDirectory: BaseDirectory,
    tempDirectory: Path.GetTempPath(),
    ...);

var pipeName = BuildServerConnection.GetPipeName(clientDirectory: ClientDirectory);
var responseTask = BuildServerConnection.RunServerBuildRequestAsync(buildRequest, pipeName, ...);
</code></pre>
<h3>이것은 미니 빌드 시스템이다</h3>
<p><code>CSharpCompilerCommand</code>는 이미 MSBuild가 하던 일의 일부를 C# 하드코딩으로 재구현합니다:</p>
<ul>
<li>AssemblyAttributes.cs 생성</li>
<li>GlobalUsings.g.cs 생성</li>
<li>AssemblyInfo.cs 생성</li>
<li>EditorConfig 생성</li>
<li>AppHost 바이너리 패치</li>
<li>RuntimeConfig.json 생성</li>
<li>컴파일러 응답 파일(.rsp) 생성</li>
</ul>
<p>이것은 "MSBuild가 한 번 해준 결과를 캐시해서 재사용한다"는 전략이지, MSBuild를 대체하는 것이 아닙니다. 첫 실행은 반드시 MSBuild를 거치고, 구조적 변경이 있으면 다시 MSBuild로 돌아갑니다.</p>
<h3>설계의 핵심 긴장</h3>
<p>SDK 팀은 이 우회 범위를 의도적으로 좁게 유지하고 있습니다:</p>
<pre><code class="language-cs">// Release 빌드만 붙여도 MSBuild로 돌아감
// Note that Release builds won't go through this optimized code path because
// `-c Release` translates to global property `Configuration=Release`
// and customizing global properties triggers a full MSBuild run.
</code></pre>
<p>왜? 우회 범위를 넓히면 넓힐수록 <strong>file-based app만을 위한 별도 빌드 시스템</strong> 을 만드는 격이 되고, MSBuild와 행동이 달라질 가능성이 커지기 때문입니다. File-based app의 핵심 원칙 — "프로젝트로 전환(grow-up)했을 때 동일하게 동작해야 한다" — 이 깨질 수 있습니다.</p>
<hr />
<h2>Runtime Async: async/await의 근본적 재설계</h2>
<h3>현재의 async/await: 컴파일러가 만드는 상태 머신</h3>
<p>현재 C#의 <code>async/await</code>는 <strong>컴파일러(Roslyn)</strong> 가 처리합니다. <code>async</code> 메서드를 작성하면 컴파일러가 이것을 상태 머신 구조체로 변환하고, <code>IAsyncStateMachine.MoveNext()</code>를 생성합니다.</p>
<pre><code class="language-cs">// 여러분이 작성하는 코드
async Task&lt;int&gt; FetchDataAsync()
{
    var data = await httpClient.GetStringAsync(url);
    return data.Length;
}

// 컴파일러가 실제로 만드는 코드 (단순화)
struct &lt;FetchDataAsync&gt;d__0 : IAsyncStateMachine
{
    public int &lt;&gt;1__state;
    public AsyncTaskMethodBuilder&lt;int&gt; &lt;&gt;t__builder;
    public TaskAwaiter&lt;string&gt; &lt;&gt;u__1;

    public void MoveNext()
    {
        switch (&lt;&gt;1__state)
        {
            case 0: goto Label_Await;
            // ...
        }
        // 실제 로직...
    }
}
</code></pre>
<p>이 방식의 비용:</p>
<ul>
<li><strong>상태 머신 구조체 할당</strong> (hot path에서도)</li>
<li><strong><code>MoveNext()</code> 호출 오버헤드</strong></li>
<li><strong>ExecutionContext 캡처/복원</strong></li>
<li><strong>IL 코드 크기 증가</strong> (상태 머신 보일러플레이트)</li>
</ul>
<h3>Runtime Async: 런타임이 직접 처리</h3>
<p>.NET 10에서 실험적으로 도입되고 .NET 11에서 본격 활성화될 <strong>Runtime Async</strong> 는 이 전체 구조를 뒤집습니다. 컴파일러가 상태 머신을 만드는 대신, <strong>JIT 컴파일러와 VM이 직접 async 메서드의 중단/재개를 처리</strong> 합니다.</p>
<p>ECMA-335 명세에 새로운 메서드 속성이 추가됩니다:</p>
<pre><code class="language-text">MethodImplOptions.Async = 0x2000
</code></pre>
<p>그리고 <code>await</code>는 더 이상 컴파일러 마법이 아니라, 런타임이 인식하는 <strong>suspension point</strong> 가 됩니다:</p>
<pre><code class="language-cs">// 런타임이 인식하는 await 패턴
namespace System.Runtime.CompilerServices
{
    public static class AsyncHelpers
    {
        [MethodImpl(MethodImplOptions.Async)]
        public static T Await&lt;T&gt;(Task&lt;T&gt; task);

        [MethodImpl(MethodImplOptions.Async)]
        public static void Await(ValueTask task);
        // ...
    }
}
</code></pre>
<h3>핵심 메커니즘: Method Variant Pairs</h3>
<p>Runtime Async의 구현에서 가장 중요한 개념은 <strong>variant pairs</strong> 입니다. <code>Task</code>를 반환하는 모든 메서드에 대해 런타임이 자동으로 두 개의 진입점을 생성합니다:</p>
<ul>
<li><strong>Task-returning variant</strong>: 기존과 동일한 <code>Task&lt;T&gt;</code> 반환 시그니처</li>
<li><strong>Async variant</strong>: <code>T</code>를 직접 반환하되, 중단이 필요한 경우 Continuation 객체를 통해 처리하는 새로운 호출 규약</li>
</ul>
<p>async → async 호출 체인에서 중단이 발생하지 않으면(hot path), <strong>Task 객체를 아예 할당하지 않고 값을 직접 반환</strong> 합니다. 이것이 극적인 성능 개선의 핵심입니다.</p>
<h3>실측 벤치마크에서의 의미</h3>
<pre><code class="language-text">현재 (async1): async 메서드 호출 → 상태 머신 할당 → Task 할당 → await
Runtime Async:  async 메서드 호출 → (동기 완료 시) 값 직접 반환, Task 할당 없음
</code></pre>
<p>.NET 팀의 실험 결과에 따르면, Runtime Async는 <strong>기존 compiler-async와 최소 동등하거나 더 나은 성능</strong> 을 보여주었습니다. 특히:</p>
<ul>
<li><strong>동기 완료(suspension 없음) 경로</strong>: 상태 머신과 Task 할당이 완전히 제거되어 일반 메서드 호출과 거의 동일한 비용</li>
<li><strong>IL 코드 크기</strong>: 상태 머신 보일러플레이트가 사라져 크게 감소</li>
<li><strong>완전한 호환성</strong>: 기존 async1과 drop-in replacement 가능</li>
</ul>
<hr />
<h2>두 변화의 합류: NuGet-Free Single File App의 부상</h2>
<h3>성능 스펙트럼</h3>
<p>두 최적화가 모두 적용된 후의 예상 성능:</p>
<table>
<thead>
<tr>
<th>시나리오</th>
<th>현재</th>
<th>BuildLevel.Csc</th>
<th>+ Runtime Async</th>
</tr>
</thead>
<tbody><tr>
<td>첫 실행 (<code>dotnet run hello.cs</code>)</td>
<td>~1.5s</td>
<td>~1.5s (첫 실행은 동일)</td>
<td>~1.5s</td>
</tr>
<tr>
<td>반복 실행 (코드 변경)</td>
<td>~1.5s</td>
<td><strong>~400-630ms</strong></td>
<td><strong>~400-630ms</strong></td>
</tr>
<tr>
<td>반복 실행 (변경 없음)</td>
<td>~1.5s</td>
<td><strong>~200ms</strong></td>
<td><strong>~200ms</strong></td>
</tr>
<tr>
<td>async 호출 체인 성능</td>
<td>기준</td>
<td>기준</td>
<td><strong>대폭 개선</strong></td>
</tr>
</tbody></table>
<p><code>BuildLevel.Csc</code>는 빌드 시간을, Runtime Async는 실행 시간 중 async 관련 오버헤드를 줄입니다. 두 개선은 <strong>직교(orthogonal)</strong> 하여, 합산 효과를 냅니다.</p>
<h3>NuGet-Free의 조건이 곧 최적 경로의 조건</h3>
<p><code>BuildLevel.Csc</code>의 혜택을 최대한 받으려면:</p>
<ul>
<li><code>#:package</code> 없음 → NuGet restore 불필요</li>
<li><code>#:sdk</code> 변경 없음 → SDK targets 재평가 불필요</li>
<li>implicit build file 없음 → MSBuild 프로퍼티 재평가 불필요</li>
</ul>
<p>이 조건을 만족하는 코드는 정확히 <strong>NuGet 패키지에 의존하지 않는 코드</strong> 입니다. 그리고 .NET BCL이 이미 제공하는 것만으로도 놀랍도록 많은 일을 할 수 있습니다:</p>
<pre><code class="language-cs">// ✅ 전부 BCL만으로 가능한 것들

using System.Net.Http;                      // HTTP 클라이언트
using System.Text.Json;                     // JSON 직렬화/역직렬화
using System.Text.RegularExpressions;       // 정규식
using System.IO.Compression;                // ZIP, GZip
using System.Security.Cryptography;         // 해시, 암호화
using System.Threading.Channels;            // 생산자-소비자 패턴
using System.Collections.Concurrent;        // 동시성 컬렉션
using System.Xml.Linq;                      // XML 처리
using System.Diagnostics;                   // 프로세스 관리
using System.Net;                           // DNS, IP, 소켓
</code></pre>
<h3>실용적인 사용 시나리오</h3>
<h4><strong>1. CLI 유틸리티</strong></h4>
<pre><code class="language-cs">#!/usr/bin/env dotnet run
// file: cleanup.cs

var targetDir = args.Length &gt; 0 ? args[0] : ".";
var cutoff = DateTime.Now.AddDays(-30);

foreach (var file in Directory.EnumerateFiles(targetDir, "*.log", SearchOption.AllDirectories))
{
    if (File.GetLastWriteTime(file) &lt; cutoff)
    {
        File.Delete(file);
        Console.WriteLine($"Deleted: {file}");
    }
}
</code></pre>
<h4><strong>2. 간이 HTTP 서버 / API 테스트</strong></h4>
<pre><code class="language-cs">// file: api-check.cs

using var client = new HttpClient();
var endpoints = new[] {
    "https://api.example.com/health",
    "https://api.example.com/status",
};

await Parallel.ForEachAsync(endpoints, async (url, ct) =&gt;
{
    try
    {
        var sw = Stopwatch.StartNew();
        var response = await client.GetAsync(url, ct);
        Console.WriteLine($"{url} → {response.StatusCode} ({sw.ElapsedMilliseconds}ms)");
    }
    catch (Exception ex)
    {
        Console.WriteLine($"{url} → FAILED: {ex.Message}");
    }
});
</code></pre>
<p>Runtime Async가 적용되면, 이 <code>Parallel.ForEachAsync</code> + <code>await</code> 체인에서 동기 완료되는 호출은 상태 머신 할당 없이 처리됩니다.</p>
<h4><strong>3. JSON 데이터 변환 파이프라인</strong></h4>
<pre><code class="language-cs">// file: transform.cs

using System.Text.Json;

var input = args.Length &gt; 0 ? File.ReadAllText(args[0]) : Console.In.ReadToEnd();
var doc = JsonDocument.Parse(input);

var result = doc.RootElement.EnumerateArray()
    .Where(e =&gt; e.GetProperty("status").GetString() == "active")
    .Select(e =&gt; new {
        Id = e.GetProperty("id").GetInt32(),
        Name = e.GetProperty("name").GetString(),
    });

Console.WriteLine(JsonSerializer.Serialize(result, new JsonSerializerOptions { WriteIndented = true }));
</code></pre>
<h4><strong>4. 시스템 관리 자동화</strong></h4>
<pre><code class="language-cs">// file: sysinfo.cs

using System.Runtime.InteropServices;

Console.WriteLine($"OS: {RuntimeInformation.OSDescription}");
Console.WriteLine($"Architecture: {RuntimeInformation.OSArchitecture}");
Console.WriteLine($"Framework: {RuntimeInformation.FrameworkDescription}");
Console.WriteLine($"Processors: {Environment.ProcessorCount}");
Console.WriteLine($"Memory: {GC.GetGCMemoryInfo().TotalAvailableMemoryBytes / 1024 / 1024:N0} MB");
Console.WriteLine($"Host: {Environment.MachineName}");
Console.WriteLine($"User: {Environment.UserName}");
</code></pre>
<h3>NuGet을 넘는 순간</h3>
<p>NuGet 없이 BCL만으로는 커버되지 않는 영역이 있습니다:</p>
<table>
<thead>
<tr>
<th>필요한 기능</th>
<th>상태</th>
</tr>
</thead>
<tbody><tr>
<td>데이터베이스 (Npgsql, Dapper)</td>
<td>❌ <code>#:package</code> 필요 → <code>BuildLevel.All</code></td>
</tr>
<tr>
<td>클라우드 SDK (Azure, AWS)</td>
<td>❌ <code>#:package</code> 필요</td>
</tr>
<tr>
<td>웹 프레임워크 (ASP.NET Core)</td>
<td>❌ <code>#:sdk Microsoft.NET.Sdk.Web</code> 필요</td>
</tr>
<tr>
<td>고급 CLI 파싱</td>
<td>❌ <code>#:package System.CommandLine</code> 필요</td>
</tr>
<tr>
<td>테스트 프레임워크</td>
<td>❌ <code>#:package</code> 필요</td>
</tr>
</tbody></table>
<p>이 경계를 넘으면 <code>BuildLevel.Csc</code>의 혜택이 사라지고, ~1.5초의 MSBuild 풀 빌드로 돌아갑니다. 이것이 자연스럽게 <strong>"NuGet-free single file"과 "프로젝트 기반 앱" 사이의 경계선</strong> 을 그어줍니다.</p>
<hr />
<h2>Runtime Async가 File-Based App에 가져올 미래</h2>
<h3>코드 크기 감소</h3>
<p>현재 <code>async</code> 메서드는 컴파일러가 상태 머신으로 변환하면서 IL 크기가 크게 증가합니다. Runtime Async는 이 변환을 JIT가 담당하므로, <strong>IL 수준의 코드 크기가 줄어듭니다</strong>. File-based app에서 이것은:</p>
<ul>
<li>더 빠른 컴파일 (처리할 IL이 줄어듦)</li>
<li>더 작은 출력 바이너리</li>
<li><code>dotnet publish file.cs</code>로 만드는 Native AOT 바이너리 크기 감소</li>
</ul>
<h3>Hot Path 최적화</h3>
<p>Runtime Async의 variant pair 메커니즘은 async 메서드 체인에서 <strong>동기 완료 경로를 극적으로 최적화</strong> 합니다. NuGet-free single file app에서 흔한 패턴:</p>
<pre><code class="language-cs">// 대부분의 HTTP 요청은 "이미 완료된" 결과를 반환
async Task&lt;string&gt; GetCachedDataAsync(string key)
{
    if (cache.TryGetValue(key, out var value))
        return value;  // ← 동기 경로: Task 할당 없음!

    var data = await FetchFromSourceAsync(key);
    cache[key] = data;
    return data;
}
</code></pre>
<p>현재는 이 메서드가 호출될 때마다 상태 머신 구조체가 생성됩니다. Runtime Async에서는 캐시 히트 시 <strong>일반 메서드 호출과 동일한 비용</strong> 으로 처리됩니다.</p>
<h3><code>dotnet publish file.cs</code> + Native AOT</h3>
<p>File-based app을 <code>dotnet publish</code>하면 Native AOT로 컴파일하여 <strong>의존성 없는 단일 네이티브 바이너리</strong> 를 생성할 수 있습니다. Runtime Async와 결합하면:</p>
<pre><code class="language-bash">$ dotnet publish hello.cs
# → hello (Linux) / hello.exe (Windows)
# 단일 네이티브 바이너리, Go의 go build와 동일한 경험
</code></pre>
<p>이것은 Go나 Rust가 제공하는 "컴파일 → 단일 바이너리" 경험과 사실상 동일합니다. 하지만 C#의 풍부한 BCL과 async/await의 인체공학적 우위가 더해집니다.</p>
<hr />
<h2>비교: 다른 언어 생태계와의 위치</h2>
<table>
<thead>
<tr>
<th></th>
<th>Python</th>
<th>Go</th>
<th>C# (NuGet-free file-based)</th>
</tr>
</thead>
<tbody><tr>
<td>단일 파일 실행</td>
<td>✅ <code>python script.py</code></td>
<td>❌ (패키지 필요)</td>
<td>✅ <code>dotnet run script.cs</code></td>
</tr>
<tr>
<td>반복 실행 속도</td>
<td>~50ms</td>
<td>N/A (컴파일 필요)</td>
<td>~200-600ms</td>
</tr>
<tr>
<td>타입 안전성</td>
<td>❌ 동적 타입</td>
<td>✅ 정적 타입</td>
<td>✅ 정적 타입</td>
</tr>
<tr>
<td>비동기 지원</td>
<td><code>asyncio</code> (제한적)</td>
<td>goroutine</td>
<td><code>async/await</code> (runtime-native)</td>
</tr>
<tr>
<td>단일 바이너리 배포</td>
<td>❌ (PyInstaller 등 필요)</td>
<td>✅ <code>go build</code></td>
<td>✅ <code>dotnet publish</code> + AOT</td>
</tr>
<tr>
<td>표준 라이브러리 풍부함</td>
<td>★★★★☆</td>
<td>★★★★★</td>
<td>★★★★★</td>
</tr>
<tr>
<td>생태계 패키지 접근</td>
<td>pip</td>
<td>go mod</td>
<td>#:package (NuGet)</td>
</tr>
</tbody></table>
<p>Python보다 첫 실행이 느리지만, 타입 안전성과 성능(특히 async 시나리오)에서 압도적 우위. Go와 유사한 단일 바이너리 배포가 가능하면서, 더 풍부한 async/await 지원.</p>
<hr />
<h2>남은 과제와 한계</h2>
<h3>MSBuild라는 천장</h3>
<p>모든 최적화에도 불구하고, file-based app은 근본적으로 MSBuild(SDK) 환경 위에 세워져 있습니다. MSBuild는 .NET 생태계의 정체성이나 다름없어서:</p>
<ul>
<li>NuGet 패키지 시스템이 MSBuild 아이템으로 설계됨</li>
<li>SDK(<code>Microsoft.NET.Sdk</code>)가 MSBuild targets의 묶음임</li>
<li>IDE 통합(VS, Rider, VS Code)이 MSBuild 프로젝트 평가에 의존</li>
</ul>
<p>이것을 우회하는 범위를 확대하면 할수록, 사실상 <strong>MSBuild의 열화 복제본</strong> 을 만드는 격이 됩니다. SDK 팀은 이 함정을 인식하고, "확실히 안전한 범위 안에서만 우회하고, 조금이라도 불확실하면 MSBuild로 돌아간다"는 보수적 전략을 취하고 있습니다.</p>
<h3>Rust로 재작성해도 달라지지 않는 문제</h3>
<p>Python/Node.js 생태계에서 Rust 기반 도구(uv, Bun 등)가 극적인 성능 개선을 보여준 것은 사실이지만, .NET의 빌드 성능 문제는 성격이 다릅니다. pip이나 npm이 느렸던 것은 "느린 런타임 위의 단순 I/O 작업"이었기 때문이고, MSBuild가 느린 것은 "하는 일 자체가 많기" 때문입니다. 빌드 엔진을 Rust로 재작성해도, 수백 개 targets 파일을 순차 평가하는 그 작업량은 변하지 않습니다.</p>
<p>그래서 SDK 팀의 전략 — 느린 경로를 빠르게 만드는 대신, <strong>느린 경로를 아예 안 타게 하는 것</strong> — 이 이 문제에 대한 가장 현실적인 해법입니다.</p>
<h3>Runtime Async의 성숙도</h3>
<p>Runtime Async는 아직 활발히 개발 중이며, ReadyToRun 이미지에 async2 메서드를 컴파일하는 것은 아직 지원되지 않습니다. SynchronizationContext 처리, Reflection과의 호환성 등 해결해야 할 엣지 케이스가 남아 있습니다.</p>
<hr />
<h2>결론: 새로운 장르의 탄생</h2>
<p>.NET 생태계에 <strong>"프로젝트 기반의 정식 앱"과 "파일 하나짜리 가벼운 스크립트" 사이의 명확한 경계선</strong> 이 성능 특성에 의해 자연스럽게 그어지고 있습니다. 그 경계선이 바로 <strong>NuGet 의존성의 유무</strong> 입니다.</p>
<p>NuGet 없이 BCL만으로 작성하는 코드는:</p>
<ul>
<li>✅ <code>BuildLevel.Csc</code> 경로를 타서 빠르게 빌드</li>
<li>✅ Runtime Async로 async 코드가 더 빠르게 실행</li>
<li>✅ Native AOT로 단일 바이너리 배포 가능</li>
<li>✅ 프로젝트 파일 없이 <code>.cs</code> 하나로 완결</li>
</ul>
<p>이것은 Python 스크립팅의 편의성, Go의 배포 단순성, 그리고 C#만의 타입 안전한 async/await를 결합한 <strong>새로운 코딩 장르</strong> 입니다. <code>.csproj</code>가 사라진 것이 아니라, <code>.csproj</code>가 필요하지 않은 영역이 명확하게 정의되고, 그 영역에서 최적의 개발 경험이 제공되는 것입니다.</p>
<pre><code class="language-cs">#!/usr/bin/env dotnet run

// 이것이 NuGet-free single file C#의 미래입니다.
// 프로젝트 파일 없음. 패키지 의존성 없음.
// BCL만으로 충분한, 빠르고 타입 안전한 스크립팅.

var response = await new HttpClient().GetStringAsync("https://api.github.com/zen");
Console.WriteLine(response);
</code></pre>
<hr />
<p><em>이 글에서 다룬 기술들의 현재 상태:</em></p>
<ul>
<li><em><code>dotnet run file.cs</code>: .NET 10에서 도입, 성능 최적화 진행 중 (<a href="https://github.com/dotnet/sdk/issues/48011">dotnet/sdk#48011</a>)</em></li>
<li><em>Runtime Async: .NET 10에서 실험적 도입, .NET 11에서 활성화 예정 (<a href="https://github.com/dotnet/runtime/issues/94620">dotnet/runtime#94620</a>)</em></li>
<li><em><code>BuildLevel.Csc</code> 경로: dotnet/sdk의 <code>CSharpCompilerCommand</code>로 구현됨</em></li>
</ul>
]]></content:encoded></item><item><title><![CDATA[AI가 본 적 없는 .NET UI 프레임워크로 IDE를 만들 때, 에이전트는 어떻게 API를 파악하는가]]></title><description><![CDATA[AI 학습 데이터에 없는 신생 .NET UI 프레임워크로 IDE를 만들 때, HandMirror MCP로 어셈블리를 직접 검사해 첫 빌드 오류를 3개로 줄인 경험을 공유합니다.]]></description><link>https://devwrite.ai/why-i-use-handmirror-mcp</link><guid isPermaLink="true">https://devwrite.ai/why-i-use-handmirror-mcp</guid><category><![CDATA[dotnet]]></category><category><![CDATA[mcp]]></category><category><![CDATA[AI]]></category><category><![CDATA[Nuget]]></category><category><![CDATA[ide]]></category><dc:creator><![CDATA[Jung-hyun, Nam]]></dc:creator><pubDate>Sat, 07 Feb 2026 15:00:00 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/gql/60adcb82557cc70e51211e5c/954f919f-c6d7-42f2-a88e-728d41561b53.webp" length="0" type="image/jpeg"/><content:encoded><![CDATA[<blockquote>
<p>2026-02-08 — LibraStudio 개발기 #1</p>
</blockquote>
<hr />
<h2>배경</h2>
<h3>왜 또 다른 .NET IDE인가</h3>
<p>.NET 생태계에서 IDE 선택지는 사실 넓지 않습니다. Visual Studio는 강력하지만 Windows 전용이고, 커뮤니티 에디션조차 상업적 사용에 제약이 따릅니다. VS Code + C# Dev Kit 조합도 훌륭하지만, 핵심인 C# Dev Kit이 프로프라이어터리 라이선스라는 점은 변하지 않습니다. 결국 중요한 부분에서 벤더 락인이 발생하고, 그 위에 쌓은 도구 체인과 워크플로 전체가 특정 벤더의 의사 결정에 종속됩니다.</p>
<p>과거에는 SharpDevelop이 Windows에서, MonoDevelop(Xamarin Studio)이 크로스 플랫폼에서 그 자리를 채워줬습니다. 하지만 SharpDevelop은 2017년에 개발이 중단됐고, MonoDevelop은 Xamarin에 합병된 뒤 사실상 단독 IDE로서의 생명을 다했습니다. 그 이후로 최신 .NET(Core 이후) 개발 환경을 제대로 지원하는 <strong>오픈소스이면서 리버럴 라이선스인 크로스 플랫폼 IDE</strong> 는 등장하지 않았습니다.</p>
<p>이 점이 늘 아쉬웠습니다. 그래서 LibraStudio를 시작했습니다. Electron이나 VS Code 기반이 아닌, 순수 .NET 네이티브 IDE를 목표로 합니다. 혼자서 Visual Studio 수준의 IDE를 만들겠다는 것은 당연히 아닙니다. 하지만 2026년에는 AI 기반 코드 에디터의 힘을 빌릴 수 있습니다. AI 에이전트에게 프레임워크 API를 탐색하게 하고, 보일러플레이트를 생성하게 하고, 반복적인 구현을 위임하면 — 한 사람이 감당할 수 있는 범위가 과거와는 완전히 다릅니다.</p>
<p>UI 프레임워크로는 <a href="https://github.com/aprillz/MewUI">Aprillz.MewUI</a>를 사용합니다. NativeAOT 친화적이고, XAML 없이 C# 코드만으로 UI를 구성하는 가벼운 프레임워크입니다. 이 프레임워크는 저와 같이 한국의 대표 .NET 개발자 커뮤니티인 닷넷데브 (.NET Dev, <a href="https://forum.dotnetdev.kr/">https://forum.dotnetdev.kr/</a>)에서 활동하는 송영재님의 오픈 소스 프로젝트입니다.</p>
<h3>AI가 모르는 신생 프레임워크라는 난관</h3>
<p>MewUI는 완전히 새로운 컨셉의 신생 UI 프레임워크입니다. XAML 기반의 WPF나 AvaloniaUI와 달리, 순수 C# fluent API로 UI를 구성하는 독자적인 설계를 가지고 있습니다. 당연히 공식 문서가 풍부하지 않고, Stack Overflow에 관련 질문이 쌓여 있지도 않습니다.</p>
<p>여기에 .NET이라는 플랫폼 자체의 문제도 겹칩니다. 대형 언어 모델의 학습 데이터에서 .NET/C#은 JavaScript나 Python에 비해 상대적으로 학습 빈도가 낮습니다. 메이저 프레임워크인 WPF나 WinForms조차 가끔 부정확한 코드를 생성하는데, 학습 데이터에 거의 포함되어 있지 않을 MewUI의 API를 정확히 맞출 가능성은 극히 낮습니다.</p>
<p>이런 상황에서 AI 코딩 에이전트에게 "최소한의 탭 기반 텍스트 에디터를 만들어줘"라고 요청하면 어떤 일이 벌어질까요?</p>
<hr />
<h2>일반적인 접근: 추측과 반복</h2>
<p>보통의 AI 코딩 에이전트 워크플로는 이렇습니다:</p>
<ol>
<li>학습 데이터에서 비슷한 API를 기억해 코드를 작성합니다</li>
<li>빌드합니다</li>
<li>오류가 나면 오류 메시지를 보고 수정합니다</li>
<li>2–3을 반복합니다</li>
</ol>
<p>이 방식은 학습 데이터에 풍부하게 포함된 메이저 프레임워크(WPF, React, SwiftUI 등)에서는 잘 동작합니다. 하지만 MewUI처럼 완전히 새로운 컨셉의 신생 프레임워크 — 게다가 상대적으로 학습 빈도가 낮은 .NET 기반 — 에서는 <strong>추측의 정확도가 극히 낮습니다</strong>. 메서드 이름, 파라미터 순서, 오버로드 존재 여부, 이벤트 시그니처 — 전부 빗나갈 수 있습니다.</p>
<hr />
<h2>다른 접근: 어셈블리를 직접 들여다보기</h2>
<p>이번 작업에서는 제가 직접 만든 <a href="https://github.com/rkttu/HandMirrorMcp">HandMirror MCP</a>를 사용했습니다. HandMirror는 NuGet 패키지의 <strong>컴파일된 어셈블리를 직접 검사</strong> 하는 MCP(Model Context Protocol) 서버입니다.</p>
<p>웹 문서를 검색하는 대신, 실제 <code>.dll</code>을 분석해서 다음 정보를 돌려줍니다. 여기서 주목할 점은 HandMirror가 일반적인 .NET 리플렉션(<code>System.Reflection</code>)이 아닌 <a href="https://github.com/jbevain/cecil">Mono.Cecil</a>을 사용한다는 것입니다. Cecil은 .NET 어셈블리의 메타데이터를 런타임 로딩 없이 직접 읽기 때문에, 검사 대상 어셈블리의 .NET 런타임 버전에 영향을 받지 않습니다. .NET Framework 4.x용 라이브러리든 .NET 10 대상이든 동일하게 분석할 수 있습니다:</p>
<ul>
<li>모든 네임스페이스와 타입 목록</li>
<li>각 타입의 생성자, 프로퍼티, 메서드, 이벤트 시그니처</li>
<li>Extension method가 어떤 네임스페이스에 있는지</li>
<li>상속 계층 구조</li>
</ul>
<h3>실제로 얻은 정보</h3>
<p><code>Aprillz.MewUI v0.9.1</code>을 검사한 결과:</p>
<ul>
<li><strong>178개 퍼블릭 타입</strong>, 14개 네임스페이스</li>
<li><code>MultiLineTextBox</code>가 <code>TextBase</code>를 상속하고, <code>Text</code>, <code>Placeholder</code>, <code>AcceptTab</code>, <code>Wrap</code>, <code>IsReadOnly</code> 등의 프로퍼티를 가진다는 것</li>
<li><code>TabControl.SelectionChanged</code>가 <code>Action&lt;int&gt;</code>라는 것 (문서가 없었다면 <code>Action&lt;TabItem&gt;</code>으로 추측했을 것이다 — 실제로 그랬다)</li>
<li><code>FileDialog.OpenFile()</code>이 <code>OpenFileDialogOptions</code>를 받고, <code>Title</code>, <code>Filter</code>, <code>Owner</code> 등의 프로퍼티를 가진다는 것</li>
<li><code>Menu.Item()</code>과 <code>ContextMenu.Item()</code>의 오버로드가 다르다는 것 — <code>Menu.Item</code>은 shortcut 문자열 파라미터가 없다</li>
<li><code>ObservableValue&lt;T&gt;</code>가 <code>Subscribe()</code>, <code>NotifyChanged()</code>, <code>Set()</code> 메서드를 가진다는 것</li>
</ul>
<p>이 정보만으로 에디터의 핵심 코드를 거의 정확하게 작성할 수 있었습니다.</p>
<hr />
<h2>결과: 첫 빌드에서 3개 오류</h2>
<p>전체 코드를 작성한 뒤 첫 빌드에서 발생한 오류는 딱 3개였습니다:</p>
<table>
<thead>
<tr>
<th>오류</th>
<th>원인</th>
</tr>
</thead>
<tbody><tr>
<td><code>Menu.Item("text", "shortcut", action)</code> — 오버로드 없음</td>
<td><code>ContextMenu.Item</code>에만 있는 shortcut 파라미터를 <code>Menu.Item</code>에도 사용</td>
</tr>
<tr>
<td><code>BorderThickness(0, 1, 0, 0)</code> — 4-파라미터 오버로드 없음</td>
<td>실제로는 <code>BorderThickness(double)</code> 단일 파라미터만 존재</td>
</tr>
<tr>
<td><code>SelectionChanged</code> 타입 불일치</td>
<td>HandMirror가 <code>Action&lt;int&gt;</code>라고 알려줬지만 코드에서 실수로 <code>Action&lt;TabItem&gt;</code> 사용</td>
</tr>
</tbody></table>
<p>세 번째는 순전히 <strong>읽은 정보를 코드에 잘못 반영한 실수</strong> 였습니다. HandMirror가 제공한 정보 자체는 정확했습니다.</p>
<p>3개 오류를 수정한 뒤 빌드 성공, 앱이 정상 실행됐습니다.</p>
<hr />
<h2>HandMirror 없이 했다면?</h2>
<p>비교를 위해, HandMirror 없이 같은 작업을 했을 때의 시나리오를 추정해 보겠습니다:</p>
<ol>
<li><code>MultiLineTextBox</code>라는 컨트롤이 존재한다는 것은 AGENTS.md에 명시되어 있으니 알 수 있다</li>
<li>하지만 fluent API의 정확한 메서드명은? <code>BindText</code>인지 <code>SetText</code>인지 <code>TextBinding</code>인지?</li>
<li><code>FileDialog</code> API가 있는지, 있다면 어떤 형태인지?</li>
<li><code>TabControl</code>의 이벤트 시그니처는?</li>
<li><code>ObservableValue&lt;T&gt;</code>의 구독 메커니즘은?</li>
</ol>
<p>이 모든 항목에서 <strong>추측 → 빌드 → 오류 → 수정</strong> 의 반복이 필요했을 것입니다. 178개 타입에 걸친 API 표면을 시행착오로 탐색하는 것은 비효율적입니다.</p>
<hr />
<h2>마무리</h2>
<h3>1. "AI가 학습한 적 없는 프레임워크"는 AI 에이전트의 약점이자, 도구로 극복 가능한 약점입니다</h3>
<p>대형 언어 모델은 학습 데이터에 있는 것을 잘 기억합니다. 학습 빈도가 높은 JavaScript/Python 생태계의 프레임워크라면 꽤 정확한 코드를 생성합니다. 하지만 .NET처럼 상대적으로 학습 빈도가 낮은 플랫폼의, 그것도 완전히 새로운 신생 프레임워크라면? 추측할 수밖에 없고, 추측은 높은 확률로 틀립니다. 하지만 <strong>실제 바이너리를 검사하는 도구</strong> 가 있으면 이 약점은 상쇄됩니다.</p>
<h3>2. 정확한 정보를 얻었더라도 실수는 발생합니다</h3>
<p>HandMirror가 <code>SelectionChanged</code>의 타입이 <code>Action&lt;int&gt;</code>임을 정확히 알려줬지만, 코드 작성 과정에서 <code>Action&lt;TabItem&gt;</code>으로 잘못 타이핑했습니다. 도구가 주는 정보의 정확성과, 그 정보를 코드에 반영하는 정확성은 별개입니다.</p>
<h3>3. MCP 생태계의 힘</h3>
<p>HandMirror는 MCP(Model Context Protocol) 서버로 구현되어 있습니다. 이 프로토콜 덕분에 AI 에이전트가 <strong>학습 시점에 존재하지 않던 지식</strong> 을 런타임에 동적으로 획득할 수 있습니다. 이것은 단순한 도구가 아니라 AI 에이전트의 능력 경계를 확장하는 인프라입니다.</p>
<p>현재 HandMirror는 .NET 어셈블리에 특화되어 있지만, 향후에는 필요에 따라 확장도 검토 중입니다. 예를 들어 <a href="https://github.com/ikvmnet/ikvm">IKVM</a>을 활용한 Java <code>.class</code>/<code>.jar</code> 파일 검사, 네이티브 라이브러리의 심볼 테이블 분석 등 — .NET 생태계 밖의 API 표면까지 AI 에이전트가 탐색할 수 있게 되면, 다국어 런타임 위에서 동작하는 프로젝트에서도 동일한 방식으로 정확한 코드를 생성할 수 있을 것입니다.</p>
<h3>4. AI 에이전트와 함께라면 1인 개발의 한계가 달라집니다</h3>
<p>SharpDevelop이나 MonoDevelop 같은 프로젝트는 수십 명의 기여자가 수년에 걸쳐 만들었습니다. 2026년에는 AI 에이전트가 API 탐색, 보일러플레이트 생성, 반복 구현을 담당해 줍니다. 물론 아키텍처 결정과 품질 판단은 여전히 사람의 몫이지만, 코드를 물리적으로 타이핑하는 병목은 크게 줄어들었습니다. 오픈소스 IDE라는 꿈이 한 사람의 사이드 프로젝트로도 시작할 수 있게 된 것입니다.</p>
<hr />
<h2>HandMirror MCP 시작하기</h2>
<p>HandMirror MCP는 <a href="https://www.nuget.org/packages/HandMirrorMcp">NuGet</a>에 게시되어 있으며, <a href="https://github.com/rkttu/HandMirrorMcp">GitHub</a>에서 소스 코드를 확인할 수 있습니다. .NET 8.0 SDK 이상이 필요합니다.</p>
<h3>설치 및 설정</h3>
<p>NuGet에 게시되어 있으므로, 소스 코드 빌드 없이 <code>dnx</code> 명령어로 바로 실행할 수 있습니다.</p>
<p><strong>VS Code (GitHub Copilot)</strong> — 워크스페이스의 <code>.vscode/mcp.json</code>에 추가:</p>
<pre><code class="language-json">{
  "servers": {
    "HandMirrorMcp": {
      "type": "stdio",
      "command": "dnx",
      "args": ["HandMirrorMcp", "--yes"]
    }
  }
}
</code></pre>
<p><strong>Claude Desktop</strong> — 설정 파일(<code>%APPDATA%\Claude\claude_desktop_config.json</code>)에 추가:</p>
<pre><code class="language-json">{
  "mcpServers": {
    "handmirror": {
      "command": "dnx",
      "args": ["HandMirrorMcp", "--yes"]
    }
  }
}
</code></pre>
<p>소스에서 직접 빌드하려면:</p>
<pre><code class="language-bash">git clone https://github.com/rkttu/HandMirrorMcp.git
cd HandMirrorMcp
dotnet build
dotnet run --project HandMirrorMcp
</code></pre>
<h3>주요 사용법</h3>
<p>MCP 클라이언트에 연결되면, 자연어로 요청하는 것만으로 .NET 어셈블리를 분석할 수 있습니다:</p>
<ul>
<li><strong>패키지 검사</strong>: "Aprillz.MewUI 패키지의 네임스페이스와 타입을 보여줘"</li>
<li><strong>타입 상세 조회</strong>: "MultiLineTextBox 클래스의 프로퍼티와 메서드를 알려줘"</li>
<li><strong>빌드 오류 해결</strong>: "CS0246 오류가 나는데, 이 타입을 제공하는 NuGet 패키지를 찾아줘"</li>
<li><strong>취약점 확인</strong>: "System.Text.Json 6.0.0에 알려진 보안 취약점이 있는지 확인해줘"</li>
<li><strong>프로젝트 분석</strong>: "내 .csproj 파일을 분석해서 문제점을 찾아줘"</li>
</ul>
<h3>Microsoft Learn MCP와 함께 사용하기</h3>
<p>HandMirror가 어셈블리의 실제 API 시그니처를 제공한다면, <a href="https://learn.microsoft.com/ko-kr/training/support/mcp">Microsoft Learn MCP Server</a>는 Microsoft 공식 문서를 AI 에이전트에게 직접 제공합니다. 문서 검색, 전체 문서 가져오기, 코드 샘플 검색이 가능하며, 원격 MCP 서버로 인증 없이 무료로 사용할 수 있습니다.</p>
<p>두 도구를 함께 사용하면 .NET 개발에서 AI 에이전트가 보이는 주요 취약점이 상당 부분 개선됩니다:</p>
<ul>
<li><strong>HandMirror</strong>: 실제 컴파일된 어셈블리에서 정확한 타입, 메서드 시그니처, 네임스페이스를 파악</li>
<li><strong>Microsoft Learn MCP</strong>: 공식 문서에서 사용 패턴, 모범 사례, 트러블슈팅 가이드를 획득</li>
</ul>
<p>API의 “어떻게 생겼는가”(HandMirror)와 “어떻게 써야 하는가”(Microsoft Learn MCP)를 동시에 제공받으면, 학습 데이터의 한계로 인한 추측을 최소화할 수 있습니다.</p>
<hr />
<h2>만든 것</h2>
<p>HandMirrorMcp의 어시스트를 받아 MewUI 기반의 최소한의 텍스트 에디터를 만들어낼 수 있었고, 아래 그림과 같은 뼈대를 갖추게 되었습니다.</p>
<p><img src="https://cdn.hashnode.com/uploads/gql/60adcb82557cc70e51211e5c/a2cba69f-cc7d-4956-8b2e-ca243a9012a7.png" alt="LibraStudio WIP - 텍스트 에디터" /></p>
<p>LibraStudio는 Apache License 2.0 하에 개발 중입니다. © 2026 rkttu</p>
<pre><code class="language-text">src/LibraStudio.Common/         # 파일 I/O 유틸리티
src/LibraStudio.Editor/         # 에디터 탭 모델 + 탭 매니저
src/LibraStudio.Shell/          # 메뉴바, 상태바, 키보드 단축키 통합
</code></pre>
<p>기능:</p>
<ul>
<li><code>MultiLineTextBox</code> 기반 탭 에디터 (Consolas, 모노스페이스)</li>
<li>파일 메뉴: New / Open / Save / Save As / Close Tab / Exit</li>
<li>키보드 단축키: <code>Ctrl+N</code>, <code>Ctrl+O</code>, <code>Ctrl+S</code>, <code>Ctrl+Shift+S</code>, <code>Ctrl+W</code></li>
<li>OS 네이티브 파일 대화상자 (Win32)</li>
<li>변경 감지 (dirty 상태) → 탭 헤더에 <code>•</code> 표시</li>
<li>탭 닫을 때 저장 여부 확인 대화상자</li>
<li>상태 바에 현재 파일 경로 표시</li>
</ul>
<p>아직 구문 강조도 없고, 줄 번호도 없고, 찾기/바꾸기도 없습니다. 하지만 <strong>파일을 열고, 편집하고, 저장할 수 있는</strong> 최소한의 텍스트 에디터로서 동작합니다.</p>
<hr />
<h2>기술 스택</h2>
<table>
<thead>
<tr>
<th>항목</th>
<th>값</th>
</tr>
</thead>
<tbody><tr>
<td>언어</td>
<td>C# 13 / .NET 10</td>
</tr>
<tr>
<td>UI</td>
<td>Aprillz.MewUI 0.9.1</td>
</tr>
<tr>
<td>그래픽</td>
<td>Direct2D (Windows)</td>
</tr>
<tr>
<td>테마</td>
<td>Dark + Blue accent</td>
</tr>
<tr>
<td>빌드</td>
<td>NativeAOT 대상 (<code>PublishAot=true</code>)</td>
</tr>
<tr>
<td>AI 도구</td>
<td>GitHub Copilot (Claude) + HandMirror MCP</td>
</tr>
</tbody></table>
]]></content:encoded></item><item><title><![CDATA[AI 시대의 오픈소스 기여: HwpLibSharp 포팅 프로젝트에서 배운 것들]]></title><description><![CDATA[Java hwplib을 .NET으로 포팅하면서 AI 코딩 어시스턴트를 활용하고, 원본과 공생하는 'Living Port' 방식의 오픈소스 기여 경험을 공유합니다.]]></description><link>https://devwrite.ai/hwplibsharp-upstream-management</link><guid isPermaLink="true">https://devwrite.ai/hwplibsharp-upstream-management</guid><category><![CDATA[dotnet]]></category><category><![CDATA[C#]]></category><category><![CDATA[Java]]></category><category><![CDATA[AI]]></category><dc:creator><![CDATA[Jung-hyun, Nam]]></dc:creator><pubDate>Fri, 06 Feb 2026 15:00:00 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/gql/60adcb82557cc70e51211e5c/1eac1dcc-7c3d-47a6-8209-25187a40c32c.jpg" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>Microsoft MVP로 활동한 지 어느덧 17년이 되었습니다. 그동안 .NET 커뮤니티에서 가장 많이 받은 질문 중 하나가 "C#으로 HWP 파일을 어떻게 다루나요?"였습니다. 한글과컴퓨터의 공식 라이브러리는 Windows와 COM 기반이어서, 크로스 플랫폼 .NET 환경에서는 사실상 해법이 없었습니다.</p>
<p>그러다 <a href="https://github.com/neolord0">@neolord0</a>님의 <code>hwplib</code>을 발견했습니다. Java로 작성된, 순수하게 HWP 파일 포맷을 파싱하는 오픈소스 라이브러리였습니다. "이걸 .NET으로 옮기면 커뮤니티에 도움이 되겠다"는 생각이 바로 들었지만, 쉬운 일은 아니었습니다. 코드베이스가 방대한 데다 지금도 계속 업데이트되고 있었으니까요.</p>
<p>그러던 중 2026년, 저는 AI 코딩 어시스턴트와 함께 이 작업을 시작했습니다.</p>
<h2>일회성 포팅이 아닌 '동기화'</h2>
<p>얼핏 생각하면 HWP 파일은 자주 변하는 포맷은 아니기에 한 번만 포팅하고 나면 더 이상 손댈 일이 없지 않는가 하는 예상을 하기 쉽습니다. 그러나 모든 기술은 계속 변화하며, 원본 프로젝트가 여전히 활발하게 관리되고 있는 것은 물론, 닷넷 기술 자체도 변화하기에 일회성 작업으로는 부족하다는 것을요.</p>
<p>전통적인 포크(fork)는 시간이 지나면 원본과 점점 멀어집니다. 결국 "우리 버전"과 "원본 버전"이 각자의 길을 가게 되죠. 당연한 수순이지만, 그럼에도 저는 다른 접근을 택했습니다. 단순한 포크가 아니라, <strong>원본과 함께 살아 숨 쉬는 "이식된 구현체(Ported Implementation)"</strong> 라는 정체성을 명확히 하기로 마음먹었습니다.</p>
<pre><code class="language-text">원본 프로젝트: hwplib (Java)
       ↓ 주기적 동기화
포팅 프로젝트: HwpLibSharp (C#)
       ↓ .NET 특화 개선
생태계 확장
</code></pre>
<p>그래서 README에도 이렇게 적어두었습니다.</p>
<blockquote>
<p>"본 프로젝트의 의사결정 및 판단 우선권은 원본 프로젝트의 작성자인 @neolord0 님의 의사를 우선으로 합니다."</p>
</blockquote>
<p>예의를 차리기 위해 쓴 문장이 아닙니다. 두 프로젝트가 장기적으로 공존하려면, 누가 방향을 결정하는지 처음부터 명확해야 한다고 판단했기 때문입니다.</p>
<h2>AI와 함께한 포팅 작업</h2>
<p>솔직히 말해, AI 코딩 어시스턴트 없이 이 프로젝트를 진행했다면 초기 포팅에만 6개월 이상이 걸렸을 겁니다. 업스트림 동기화는 아예 엄두도 못 냈을 것이고, 결국 방치된 "또 다른 레거시"가 되었겠죠.</p>
<p>그러나 AI와 함께 일하면서 전혀 다른 방식이 가능해졌습니다.</p>
<h3>AI가 잘한 것</h3>
<p>문법 변환은 거의 완벽했습니다. Java의 getter/setter를 C# 프로퍼티로 바꾸고, 명명 규칙을 C# 컨벤션에 맞추고, null 체크를 Nullable 참조 형식으로 전환하는 작업은 대부분 자동화할 수 있었습니다.</p>
<p>라이브러리 대응도 AI의 도움이 컸습니다. Apache POI를 OpenMcdf로 교체할 때, "Java에서 이 라이브러리가 하는 역할을 .NET에서는 뭐로 대체할 수 있는가"를 빠르게 찾아주었습니다. 원본 프로젝트가 업데이트될 때마다 변경 사항을 추적하고 C# 버전에 반영하는 반복 작업에서도 휴먼 에러를 크게 줄여주었고요.</p>
<h3>Upstream 변경 사항 자동 추적</h3>
<p>이 과정에서 특히 효과적이었던 것은, AI 에이전트를 활용한 <strong>upstream 변경 사항 자동 추적</strong> 방식이었습니다. 원본 hwplib 프로젝트에 새 커밋이 들어올 때마다, AI 에이전트가 변경된 Java 소스 파일과 대응하는 C# 소스 파일을 비교 분석하여 구현 상의 차이점을 찾아냅니다.</p>
<p>이 동기화를 체계적으로 관리하기 위해, 포팅된 모든 C# 소스 파일 첫 줄에 원본 Java 파일과의 대응 관계를 명시하는 힌트 헤더를 남겨두었습니다.</p>
<pre><code class="language-csharp">// =====================================================================
// Java Original: kr/dogfoot/hwplib/util/compressors/Compressor.java
// Repository: https://github.com/neolord0/hwplib
// =====================================================================
</code></pre>
<p>이 헤더가 있으면 AI 에이전트가 "이 C# 파일의 원본은 Java 쪽 어느 파일이다"를 즉시 파악할 수 있습니다. upstream에서 <code>Compressor.java</code>가 변경되면, AI가 대응되는 C# 파일을 찾아 diff를 분석하고, 누락된 변경 사항이나 구현 차이를 리포트해 줍니다. 사람이 수백 개의 파일을 하나하나 대조할 필요 없이, AI가 "이 부분이 원본과 달라졌으니 확인이 필요하다"고 알려주는 방식입니다.</p>
<p><img src="https://cdn.hashnode.com/uploads/gql/60adcb82557cc70e51211e5c/02467cb3-c16f-4e30-9c36-2a9ec2afe81c.png" alt="AI 에이전트가 upstream 변경 사항을 추적하고 C# 파일과 비교 분석하는 과정" /></p>
<p>실제로 이 방식을 도입한 후, upstream 동기화에 걸리는 시간이 기존 대비 80% 이상 단축되었습니다. 이전에는 변경 로그를 읽고 관련 파일을 하나씩 찾아가며 수동으로 반영했다면, 이제는 AI가 변경 목록과 영향 범위를 자동으로 정리해 주니까요.</p>
<h3>AI가 못한 것</h3>
<p>반면, HWP 파일의 Section-Paragraph-Control 구조, 각 컨트롤의 의미, 한글 문서만의 특성 같은 도메인 지식은 온전히 제 몫이었습니다. AI가 그럴듯하게 제안한 코드가 실제로 맞는지 검증하는 건 결국 사람이 해야 하는 일이니까요.</p>
<p>전략적 결정도 마찬가지였습니다. Native AOT를 지원할 것인가, Blazor WebAssembly에서 어떻게 동작하게 할 것인가, 어느 .NET 버전까지 지원할 것인가. 이런 판단에는 .NET 생태계 전반에 대한 이해와 실제 사용자 환경에 대한 감각이 필요합니다. 라이선스 문구, 원작자와의 관계 설정, 한국 개발자 커뮤니티의 맥락을 반영하는 작업도 AI가 초안을 잡아주면 제가 다듬는 방식으로 진행했습니다.</p>
<h2>.NET 생태계에 맞게 재설계하기</h2>
<p>단순히 코드를 옮기는 것에서 그치지 않았습니다. .NET 개발자들이 자연스럽게 쓸 수 있도록 API를 원본 프로젝트의 철학과 의도를 해치지 않는 선에서 다듬는 작업도 필요했습니다.</p>
<pre><code class="language-csharp">// Blazor WebAssembly 지원 (파일 시스템 없이 스트림으로)
var hwpFile = HWPReader.FromStream(memoryStream);

// Native AOT 호환, URL에서 비동기 로딩
var hwpFile = await HWPReader.FromUrlAsync(url);
</code></pre>
<p>이런 기능들은 원본 Java 버전에는 없습니다. 하지만 .NET 개발자라면 당연히 기대하는 것들이죠. 덕분에 Azure Functions에서 HWP를 처리하거나, Blazor로 브라우저에서 HWP를 렌더링하는 것도 가능해졌습니다.</p>
<p>재미있는 일도 있었습니다. Java 개발자들이 HwpLibSharp의 README를 보고 아이디어를 가져가서, 원본 프로젝트의 문서화에 기여하기도 했습니다. .NET 버전의 사용 예제가 Java 사용자들에게도 도움이 된 셈입니다.</p>
<p>특히 RAG(Retrieval-Augmented Generation) 용도로 HWP에서 텍스트를 추출하는 예제는 양쪽 커뮤니티에서 활발하게 논의되었습니다. AI가 HWP 문서를 이해하려면 어떤 형태의 텍스트를 뽑아야 하는가, 이 질문은 프로그래밍 언어 경계를 넘어서는 것이니까요.</p>
<h2>코드를 옮기는 사람에서 큐레이터로</h2>
<p>이 프로젝트를 진행하면서 제 역할 자체가 변화했음을 느꼈습니다. 처음에는 코드를 번역하는 사람이었지만, 이제는 <strong>두 생태계를 연결하는 큐레이터</strong> 에 가깝습니다. 원본 프로젝트의 변경 사항을 모니터링하고, .NET 커뮤니티의 요구를 수집하며, 두 세계의 관행과 철학을 조율하고, 지속 가능한 동기화 프로세스를 설계하는 일입니다.</p>
<p>현재 HwpLibSharp는 .NET Framework 4.7.2부터 .NET 8까지 지원하며, 실제 정부·공공기관 프로젝트에서도 사용되고 있습니다. 하지만 단순한 지원 범위보다 더 의미 있는 것은, 이전에는 불가능했던 시나리오들이 열렸다는 점입니다.</p>
<ul>
<li>Azure Functions에서 서버리스로 HWP 처리</li>
<li>Blazor WASM으로 브라우저 내 HWP 렌더링</li>
<li>.NET MAUI 모바일 앱에서 HWP 읽기</li>
<li>AI/LLM의 RAG 파이프라인에 HWP 문서 통합</li>
</ul>
<h2>이 프로젝트에서 배운 것들</h2>
<p><strong>AI는 경험의 배율기다.</strong> 17년간 쌓아온 .NET 경험이 AI를 통해 몇 배의 생산성으로 나타났습니다. 그 경험이 없었다면 AI에게 올바른 방향을 제시할 수도 없었을 겁니다. AI는 경험을 대체하는 게 아니라 증폭시킵니다.</p>
<p><strong>자동화의 경계를 알아야 한다.</strong> 문법 변환, 패턴 적용, 반복 테스트는 자동화하되, 전략 결정이나 도메인 검증, 커뮤니티와의 관계는 사람이 직접 해야 합니다. 이 경계를 혼동하면 빠르게 잘못된 방향으로 갈 수 있습니다.</p>
<p><strong>포크(Fork)가 아닌 "Living Port"라는 개념.</strong> 원본과 경쟁하지 않고, 공생하면서 각자의 생태계에 가치를 더하는 구조입니다. 오픈소스 기여의 새로운 형태가 될 수 있다고 생각합니다.</p>
<p><strong>기여는 코드 이상이다.</strong> README 한 줄, 예제 하나가 누군가의 삽질 3일을 절약해 줍니다. 한국처럼 고유한 문서 포맷을 다루는 환경에서는 그 효과가 더 큽니다.</p>
<h2>마치며</h2>
<p>.NET을 좋아해서 커뮤니티를 만들었고, 17년간 유지해왔습니다. 그 과정에서 쌓인 경험과 네트워크가 이제 AI라는 도구를 만나 새로운 형태의 가치를 만들어내고 있습니다.</p>
<p>HwpLibSharp 프로젝트는 기술 전문성, 커뮤니티 기여, AI 시대의 개발 방법론 실험이 한데 섞인 작업이었습니다. AI가 시간을 벌어주었고, 그 시간으로 더 많은 사람들에게 도움이 될 수 있었습니다. 어쩌면 이것이 지금 시대의 오픈소스 기여 방식일지도 모르겠습니다.</p>
<hr />
<p><strong>프로젝트 링크:</strong></p>
<ul>
<li>GitHub: <a href="https://github.com/rkttu/libhwpsharp">rkttu/HwpLibSharp</a></li>
<li>NuGet: <a href="https://www.nuget.org/packages/HwpLibSharp/">HwpLibSharp</a></li>
<li>원본 프로젝트: <a href="https://github.com/neolord0/hwplib">neolord0/hwplib</a></li>
</ul>
<p>프로젝트에 대한 피드백이나 기여는 언제든 환영합니다. <a href="https://github.com/rkttu/libhwpsharp/issues">GitHub Issue</a>로 편하게 남겨주세요.</p>
]]></content:encoded></item><item><title><![CDATA[AI 코딩 도구, '뒤처진다'는 불안에 휘둘리지 않는 법]]></title><description><![CDATA[AI 코딩 도구의 hype에 휘둘리지 말고, 병렬 에이전트보다 HITL이 유지되는 동기 세션을 깊이 활용하는 것이 실질적인 생산성 향상 전략입니다.]]></description><link>https://devwrite.ai/ai-coding-tools-fomo</link><guid isPermaLink="true">https://devwrite.ai/ai-coding-tools-fomo</guid><category><![CDATA[AI]]></category><dc:creator><![CDATA[Jung-hyun, Nam]]></dc:creator><pubDate>Mon, 26 Jan 2026 15:00:00 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/gql/60adcb82557cc70e51211e5c/5f0cb660-3245-43a4-b978-d67d12c7234b.webp" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>요즘 AI 코딩 도구 업계의 소식을 접하다 보면, 새로운 도구가 등장할 때마다 "이것이 미래다", "안 쓰면 뒤처진다"는 메시지가 과도하다 싶을 정도로 강조되는 것을 볼 수 있습니다. 백그라운드 에이전트, 병렬 AI 세션, 자율 코딩—매주 새로운 개념이 등장하고, 그것을 도입하지 않으면 마치 시대에 뒤처지는 것처럼 느껴지게 만듭니다.</p>
<p>하지만 이런 메시지를 곧이곧대로 받아들이는 것이 정말 건전한 접근일까요? 저는 그렇지 않다고 생각합니다.</p>
<h2>Hype는 어떻게 만들어지는가</h2>
<p>AI 코딩 도구 업계의 hype에는 구조적인 이유가 있습니다. AI 기술로 수익을 창출해야 하는 기업들의 경영자는 투자자와 주주를 만족시켜야 하는 위치에 있습니다. 그래서 그들의 메시지에는 이중 청중 문제가 존재합니다. 개발자에게는 "생산성 향상"을 약속하면서, 동시에 투자자에게는 "시장 지배력"과 "필수불가결한 도구"라는 서사를 제공해야 합니다.</p>
<p>이 과정에서 "절반만 맞는 말"들이 쏟아집니다. "AI가 코딩을 혁신한다"는 틀리지 않지만, "지금 당장 이 도구를 쓰지 않으면 도태된다"는 비약이 함께 패키징됩니다. 완전한 거짓은 쉽게 반박당하지만, 과장된 진실은 검증하기 어렵기 때문입니다.</p>
<p>이런 메시지는 AI 기업에서 시작해 일부 앞서가고자 하는 기업의 경영자들과 기술 리더들, 그리고 인플루언서들을 거쳐 실무 개발자들에게 도달합니다. 문제는 중간 전파자들이 자신의 이해관계 때문에 메시지를 걸러내기보다 더 강하게 증폭시키는 경향이 있다는 것입니다. "최신 기술을 도입하고 있다"는 이미지 자체가 그들의 시장 포지셔닝이자 영업 도구가 되기 때문입니다.</p>
<h2>백그라운드 에이전트의 약속과 현실</h2>
<p>최근 강조되는 트렌드 중 하나가 "백그라운드 에이전트"입니다. VS Code의 Agent HQ, Google Antigravity의 Manager View 같은 기능들이 대표적입니다. 이 도구들의 핵심 약속은 작업을 위임하면 AI가 별도의 환경에서 자율적으로 실행하고, 개발자는 다른 일을 할 수 있다는 것입니다. 여러 에이전트를 병렬로 돌리면 생산성이 몇 배로 향상된다는 주장도 함께합니다.</p>
<p>그러나 이 약속에는 근본적인 문제가 있습니다. 백그라운드 에이전트는 본질적으로 Human-In-The-Loop(HITL)를 의도적으로 제거하는 방향으로 설계되어 있습니다. "비동기 작업", "자율 실행", "위임 후 검토"라는 개념 자체가 중간 개입 지점을 없애는 것을 전제로 합니다.</p>
<p>실제로 사고는 이미 발생하고 있습니다. Google의 Antigravity 에이전트가 하드 드라이브 파티션 전체를 삭제한 사건이 보고된 바 있습니다. 기존 채팅창에서 작업할 때는 각 단계마다 결과를 확인하고 중간에 개입할 수 있지만, 백그라운드 에이전트는 잘못된 방향으로 진행해도 완료될 때까지 인지하기 어렵습니다.</p>
<h2>면책 조항과 마케팅의 모순</h2>
<p>흥미로운 점은 모든 AI 서비스 업체들이 "AI는 실수 가능성이 있으니 꼭 확인해달라"는 면책 조항을 명시하고 있다는 것입니다. 그런데 동시에 마케팅에서는 "자율적으로 일하는 에이전트"를 강조합니다. 이 두 메시지를 동시에 진지하게 받아들이면, 병렬 에이전트의 효용은 상당히 제한적일 수밖에 없습니다.</p>
<p>"여러 에이전트를 병렬로 돌려야 진짜 생산성"이라는 주장은 "AI 출력은 반드시 검토하라"는 경고와 정면으로 충돌합니다. 한 세션의 출력도 검증이 필요한데, 그것을 다섯 개 동시에 돌리면 검증 부담이 다섯 배가 되는 것이지 생산성이 다섯 배가 되는 것이 아닙니다. 병목이 생성에서 검증으로 이동할 뿐, 전체 처리량이 선형으로 증가하지 않습니다.</p>
<p>역설적이게도, 사람 다섯 명을 병렬로 투입해도 관리와 검토 없이는 품질이 보장되지 않습니다. 조율 비용이 증가하고, 일관성이 깨지고, 결과물의 품질 편차가 커집니다. 이것은 소프트웨어 공학에서 수십 년간 반복 검증된 사실입니다. AI 에이전트라고 이 원리에서 자유로울 이유가 없습니다.</p>
<h2>기술 리더가 갖춰야 할 태도</h2>
<p>CTO나 기술 의사결정권자의 입장에서 보면, 이 상황에서 가장 중요한 덕목은 "냉정한 거리두기와 판단"입니다. 문제는 이것을 실천하기가 구조적으로 어렵다는 점입니다. 냉정한 판단을 내리면 "혁신에 소극적이다", "트렌드를 모른다"는 평가를 받을 위험이 있고, 그 판단이 옳았다는 것은 수년 후에야 검증됩니다.</p>
<p>거시적으로 보면, 기술에 대한 깊은 이해(anchor)가 없는 상태에서 의사결정을 해야 하는 경영자들은 외부 시그널에 의존할 수밖에 없습니다. 그런데 그 시그널의 대부분이 이해관계가 얽힌 소스에서 오기 때문에, 쉽게 불안해하고 쉽게 조급해하는 취약한 상태에 놓이게 됩니다.</p>
<p>하나의 실용적인 대안은 Lab 전략입니다. 실험의 범위와 비용을 통제하면서도 조직이 새로운 기술을 학습하고 평가할 수 있는 공간을 확보하는 것입니다. 실패 비용이 낮은 영역(내부 도구, 프로토타입)에서는 공격적인 도구 선택을 허용하고, 핵심 비즈니스 영역에는 검증된 도구를 유지합니다. 이렇게 하면 "우리도 AI 도구를 적극 활용하고 있다"는 서사를 유지하면서도 실제 비즈니스 리스크는 관리할 수 있습니다.</p>
<h2>도구(Harness)의 중요성: 말과 마구의 비유</h2>
<p>최근 Anthropic의 연구원 Boris Cherny가 흥미로운 비유를 제시했습니다. "Claude는 말(horse)이고, Claude Code는 harness(마구)다. 말을 타려면 안장이 필요하고, 그 안장이 말을 탈 때 큰 차이를 만든다"는 것입니다. 그의 설명에 따르면, AI 코딩이 오랫동안 제대로 작동하지 않았던 이유는 모델이 충분히 좋지 않았던 것도 있지만, 모델 위의 scaffolding(도구)이 충분히 좋지 않았던 것도 큰 이유였습니다.</p>
<p>이 비유에서 중요한 점은 인간 프로그래머가 여전히 루프 안에 있다는 것입니다. 마구를 사용해 말을 원하는 방향으로 이끄는 것처럼, 개발자는 도구를 통해 AI를 제어합니다. 그리고 그 도구의 품질이 결과물의 품질을 크게 좌우합니다.</p>
<h2>전통적 IDE 인프라의 재발견: Visual Studio 2026 사례</h2>
<p><a href="https://www.youtube.com/watch?v=oTEU-FLCDuk">https://www.youtube.com/watch?v=oTEU-FLCDuk</a></p>
<p>이 맥락에서 Visual Studio 2026의 디버거 에이전트는 주목할 만합니다. 이 기능은 단위 테스트가 실패했을 때 다음과 같은 과정을 자율적으로 수행합니다. 워크스페이스에서 컨텍스트(테스트 코드, 관련 소스, 최근 수정사항)를 수집하고, 실패 원인에 대한 가설을 형성하고, 분석에 기반해 코드를 수정하고, 디버거에서 테스트를 실행하여 검증하고, 문제가 지속되면 디버거 인사이트를 활용해 가설을 정제하며 테스트가 통과할 때까지 반복합니다.</p>
<p>여기서 핵심은 이 모든 것이 수십 년간 축적된 IDE 인프라 위에서 작동한다는 점입니다. 브레이크포인트 조작, 변수 상태 실시간 추적, 콜스택 분석, 심볼 해석, 프로파일링—이런 기능들은 터미널 기반의 경량 에이전트가 쉽게 구현할 수 없는 영역입니다. AI가 "가설을 세우고 검증한다"는 것은 이런 인프라가 뒷받침될 때 비로소 의미 있는 자동화가 됩니다.</p>
<p>.NET 개발자의 관점에서 보면, 트렌드를 따라 터미널 기반 도구로 전환하는 것이 반드시 생산성 향상을 의미하지 않습니다. 오히려 완성도 높은 전통적 IDE가 AI와 결합될 때 더 강력한 시너지가 발생할 수 있습니다. 새로운 것이 항상 더 나은 것은 아닙니다.</p>
<h2>동기 세션 고도화라는 현실적 대안</h2>
<p>백그라운드 에이전트나 HITL 없이 실행되는 모드에 대한 확신이나 신뢰가 없다면, 굳이 무리해서 사용할 이유가 없습니다. 오히려 현재와 같이 HITL이 유지되는 동기 세션 기반 워크플로우를 더 깊이 살펴보면서 고도화하는 것이 안전성과 효율성을 동시에 챙기는 전략입니다.</p>
<p>프롬프트 패턴의 체계화, 컨텍스트 제공 방식의 최적화, IDE 통합 기능의 깊은 활용, 작업 단위의 적절한 분할 같은 영역에서의 숙련도가 높아지면, 새로운 도구가 등장하더라도 그 가치를 냉정하게 평가할 수 있는 기준이 생깁니다.</p>
<h2>결론: 도구의 신규성보다 도구 사용의 깊이</h2>
<p>"확인해달라"는 경고가 형식적인 면책이 아니라 실질적인 운용 지침이라면, 현재 AI 도구의 적정 사용 방식은 HITL이 유지되는 단일 또는 소수 세션의 깊은 활용입니다. 병렬 자율 에이전트는 AI의 신뢰성이 지금보다 훨씬 높아진 이후에야 의미 있는 선택지가 될 것입니다.</p>
<p>도구의 신규성보다 도구 사용의 깊이가 실무 생산성에 더 큰 영향을 미칩니다. 그리고 이것이 hype에 휘둘리지 않는 실질적인 경쟁력이 됩니다. 새로운 도구가 등장할 때마다 "이것이 해결하는 실제 문제가 무엇인가"를 먼저 질문하는 습관을 들이시기 바랍니다.</p>
<p>도구는 수단이지 정체성이 아닙니다.</p>
]]></content:encoded></item><item><title><![CDATA[Java hwplib을 .NET으로 이식하기: AI와 함께한 오픈소스 포팅 여정]]></title><description><![CDATA[Java로 작성된 hwplib을 AI 코딩 어시스턴트와 Visual Studio 2026의 에이전트 기반 디버거를 활용하여 3주 만에 .NET으로 완전히 포팅한 경험을 공유합니다.]]></description><link>https://devwrite.ai/hwplibsharp-dev-journey</link><guid isPermaLink="true">https://devwrite.ai/hwplibsharp-dev-journey</guid><category><![CDATA[dotnet]]></category><category><![CDATA[C#]]></category><category><![CDATA[Java]]></category><category><![CDATA[AI]]></category><dc:creator><![CDATA[Jung-hyun, Nam]]></dc:creator><pubDate>Wed, 07 Jan 2026 15:00:00 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/gql/60adcb82557cc70e51211e5c/679e7a42-a9e4-42be-a85d-338050c18b49.jpg" length="0" type="image/jpeg"/><content:encoded><![CDATA[<h2>시작은 단순한 호기심에서</h2>
<p>"한글 파일을 .NET에서 직접 다룰 수 있으면 좋겠는데..."</p>
<p>이런 생각을 한 .NET 개발자가 저만은 아닐 것입니다. HWP 파일은 한국에서 공공기관을 중심으로 여전히 널리 사용되는 문서 형식이지만, .NET 생태계에서는 이를 제대로 다룰 수 있는 오픈소스 라이브러리가 마땅치 않았습니다.</p>
<p>.NET에서는 그동안 HWP 파일을 다루기 위해서, Windows OS 한정으로 아래아한글을 설치하면 같이 따라오는 HWP ActiveX 컨트롤의 COM 타입 라이브러리를 불러와서 제어하는 것 정도만 겨우 다루어지고 있었을 뿐이었지만, 안타깝게도 이 마저도 지원이 중단되면서 지금은 길이 막힌 상태죠!</p>
<p>그러던 중 Java로 작성된 <a href="https://github.com/neolord0/hwplib">hwplib</a>을 발견했습니다. neolord0님께서 꾸준히 유지보수해 온 이 라이브러리는 HWP 파일의 읽기/쓰기를 완성도 있게 지원하고 있었습니다.</p>
<p>예전 같았으면 이런 라이브러리를 포팅하는 것은 정말 투철한 사명감과 목적 의식이 있는게 아니라면 좀처럼 엄두를 낼 수 있는 작업이 아니었습니다. 하지만, 수준높은 AI 모델이 많이 나왔고 지금이라면 새로운 도전을 해 볼 수 있을거란 호기심이 있었습니다.</p>
<p>그렇게 시작된 3주간의 여정을 공유합니다.</p>
<h2>숫자로 보는 프로젝트</h2>
<p>본격적인 이야기에 앞서, Java 버전의 프로젝트의 규모를 숫자로 먼저 정리해 보겠습니다.</p>
<table>
<thead>
<tr>
<th>항목</th>
<th>내용</th>
</tr>
</thead>
<tbody><tr>
<td>원본 프로젝트</td>
<td><a href="https://github.com/neolord0/hwplib">neolord0/hwplib</a> (Java)</td>
</tr>
<tr>
<td>포팅 프로젝트</td>
<td><a href="https://github.com/rkttu/libhwpsharp">rkttu/libhwpsharp</a> (C#)</td>
</tr>
<tr>
<td>타겟 프레임워크</td>
<td>.NET Standard 2.0, .NET Framework 4.7.2, .NET 8</td>
</tr>
<tr>
<td>총 커밋 수</td>
<td>54개</td>
</tr>
<tr>
<td>개발 기간</td>
<td>2025-12-16 ~ 2026-01-08 (약 3주)</td>
</tr>
<tr>
<td>최초 포팅 코드</td>
<td>641개 파일, 50,010 라인</td>
</tr>
</tbody></table>
<p>641개 파일, 5만 줄. 솔직히 처음 이 숫자를 봤을 때는 "이게 가능할까?"라는 의문이 들었습니다.</p>
<h2>첫날: AI와 함께한 대규모 코드 변환</h2>
<h3>5만 줄을 하루 만에?</h3>
<p>2025년 12월 16일, 프로젝트를 시작했습니다. 일반적인 상황이라면 5만 줄의 Java 코드를 C#으로 변환하는 데 몇 달은 걸렸을 것입니다. 하지만 AI 코딩 어시스턴트가 게임 체인저였습니다.</p>
<p>AI에게 Java 파일들을 넘기고 C#으로 변환해달라고 요청했습니다. 물론 기계적인 변환만으로는 부족했습니다. Java와 C#은 비슷해 보이지만 미묘한 차이가 많기 때문입니다.</p>
<pre><code class="language-java">// Java
public byte getValue() { return value; }
public void setValue(byte value) { this.value = value; }
</code></pre>
<pre><code class="language-csharp">// C#
public byte Value { get; set; }
</code></pre>
<p>이런 패턴 변환은 AI가 잘 처리해줬습니다. 하지만 진짜 문제는 따로 있었습니다.</p>
<h2>최대 난관: Apache POI에서 OpenMcdf로</h2>
<h3>OLE2 복합 문서의 늪</h3>
<p>HWP 파일은 Microsoft의 OLE2 복합 문서 형식(Compound File Binary Format)을 기반으로 합니다. 쉽게 말해, 하나의 파일 안에 여러 개의 "스트림"이 폴더 구조처럼 저장되어 있는 형식입니다.</p>
<p>Java에서는 Apache POI 라이브러리가 이 형식을 다루지만, .NET에는 직접적인 대응물이 없습니다. 대신 OpenMcdf라는 라이브러리를 사용해야 했는데, 안타깝게도 Apache POI와는 API가 완전히 다릅니다.</p>
<pre><code class="language-java">// Java (Apache POI)
DirectoryEntry root = poiFs.getRoot();
DocumentInputStream stream = root.createDocumentInputStream("Section0");
</code></pre>
<pre><code class="language-csharp">// C# (OpenMcdf)
CFStorage root = compoundFile.RootStorage;
CFStream stream = root.GetStream("Section0");
byte[] data = stream.GetData();
</code></pre>
<p>개념은 비슷하지만 세부 구현이 완전히 달랐습니다. 이런 차이점을 이해하고 분석하면서 다듬는 과정을 과연 AI가 잘 해낼 수 있을지 솔직히 불안한 점이 있었습니다.</p>
<p>HWP 파일 내부의 데이터는 zlib으로 압축되어 있습니다. Java와 C#의 압축 해제 라이브러리가 미묘하게 다르게 동작해서, 같은 데이터를 넣어도 결과가 달랐습니다.</p>
<p>몇 시간 동안 바이트 단위로 비교하며 디버깅한 끝에, 문제의 원인을 찾았습니다. zlib 헤더 처리 방식이 달랐던 것입니다. 다행히 neolord0 님께서 꼼꼼하게 만들어주신 유닛 테스트 덕분에 이런 문제를 발견할 수 있었는데, 여기서 저는 Visual Studio 2026의 "에이전트 기반 디버거"의 힘을 느낄 수 있었습니다.</p>
<p>Visual Studio 2026은 많이들 알고 계시듯 그 어떤 버전보다도 AI 에이전트의 강력함을 누릴 수 있게 리팩토링된 제품입니다. 흔히 VS Code처럼 에이전트를 이용해서 코드를 "자동 작성"하는 것에 집중하기 마련인데, 이번 포팅 프로젝트에서 유닛 테스트를 디버그 모드로 진행하면서 "실패"하는 상황이 발생하면, 디버거를 열어둔 채로 "무엇이 문제인지" 즉시 파악하고, 스스로 중단점을 잡고 추적해가며 변수, 호출 스택을 내부 MCP 서버를 통해 수집해가며 대응하는 모습은 무척 흥미로웠습니다.</p>
<p>물론 모든 문제를 이렇게 풀 수 있었던 것은 아니었지만, 이런 도구의 지원이 없었다면 끝을 볼 수 없었을 수도 있는 일이었습니다.</p>
<h2>테스트 100% 달성의 희열</h2>
<h3>빨간불에서 초록불로</h3>
<p>원본 hwplib 프로젝트에는 neolord0 님께서 만들어둔 테스트 케이스들이 있었습니다. 저에게는 이 테스트들이 등대 같은 존재였습니다. "일단 이것만 다 통과하면 된다"는 명확한 목표가 있으니까요.</p>
<p>처음 테스트를 돌렸을 때는 참담했습니다. 47개 중 3개만 통과. 빨간 X 표시가 화면을 가득 채웠죠. 하지만 포기할 수 없었습니다. 하나씩 실패 원인을 추적하고, 코드를 수정하고, 다시 테스트를 돌렸습니다.</p>
<p>Section 파싱을 고치니 5개가 더 통과했습니다. 컨트롤 파싱을 수정하니 10개가 초록불로 바뀌었습니다. 테이블 처리, GSO(그래픽) 객체... 마치 퍼즐 조각을 맞추듯 하나씩 해결해 나갔습니다.</p>
<p>그리고 드디어, 그 순간이 왔습니다.</p>
<pre><code class="language-text">Tests Passed: 47/47
</code></pre>
<p>모니터를 뚫어져라 쳐다봤습니다. 진짜 47/47인지 몇 번이고 확인했습니다. 커피 한 잔 마시고 다시 돌려봤습니다. 여전히 47/47. 이제야 숨을 쉴 수 있었습니다.</p>
<p>이 순간을 위해 달려왔구나 싶었습니다.</p>
<h2>더 많은 사용자를 위한 여정</h2>
<h3>"macOS에서는 안 되나요?"</h3>
<p>테스트를 통과하고 기뻐하는 것도 잠시, 현실이 찾아왔습니다. 첫 번째 질문은 예상대로였습니다.</p>
<blockquote>
<p>"혹시 Mac에서도 쓸 수 있나요?"</p>
</blockquote>
<p>아차 싶었습니다. 저는 처음에 이미지 처리에 <code>System.Drawing</code>을 사용했는데, 이건 Windows 전용이나 다름없습니다. .NET Core 이후로 크로스 플랫폼이 대세가 되었는데, Windows에서만 돌아가는 라이브러리라니... 의미가 반감되는 느낌이었죠.</p>
<p>고민 끝에 <strong>SkiaSharp</strong> 으로 전환하기로 했습니다. Google의 Skia 그래픽 엔진을 .NET으로 래핑한 라이브러리인데, Windows, macOS, Linux 모두에서 동일하게 동작합니다. 이미지 관련 코드를 전부 뜯어고치는 건 귀찮았지만, 더 많은 개발자가 쓸 수 있다면 그만한 가치가 있었습니다.</p>
<h3>"저희는 아직 .NET Framework 4.7.2인데요..."</h3>
<p>두 번째 도전은 조금 더 고통스러웠습니다. 현실 세계의 기업 환경은 생각보다 보수적입니다. .NET 8이 아무리 좋아도, 레거시 시스템과의 호환성 때문에 .NET Framework를 벗어나지 못하는 곳이 많습니다.</p>
<p>문제는... 제가 신나서 C# 12의 최신 문법을 마음껏 사용했다는 것입니다.</p>
<pre><code class="language-csharp">// C# 12 - 파일 범위 네임스페이스 (한 줄로 끝!)
namespace HwpLib.Reader;

public class HwpReader { }
</code></pre>
<p>이걸 .NET Framework에서 쓰려면 구식 문법으로 바꿔야 합니다.</p>
<pre><code class="language-csharp">// C# 8 호환 - 전통적인 네임스페이스 (중괄호 필수)
namespace HwpLib.Reader
{
    public class HwpReader { }
}
</code></pre>
<p>"에이, 그냥 중괄호 추가하면 되는 거 아니야?" 라고 생각할 수 있습니다. 맞습니다. 근데 그게 <strong>582개 파일</strong> 입니다.</p>
<p>결과적으로 51,480줄 추가, 49,701줄 삭제라는 어마어마한 diff가 발생했습니다. GitHub에서 해당 커밋을 열면 브라우저가 잠시 멈출 정도였죠. C# 언어 버전도 12.0에서 8.0까지 단계적으로 내려야 했습니다. <code>required</code> 키워드, <code>init</code> 접근자, 파일 범위 네임스페이스... 편하게 쓰던 기능들을 하나씩 포기하며 과거로 돌아가는 기분이었습니다.</p>
<p>그래도 이 고통 덕분에 이제 .NET Framework 4.7.2부터 .NET 8까지, 거의 모든 .NET 환경에서 libhwpsharp를 사용할 수 있게 되었습니다.</p>
<h2>AI와의 협업에서 배운 것</h2>
<p>3주간의 프로젝트를 마치고 나니, AI와 어떻게 협업해야 하는지에 대한 나름의 노하우가 생겼습니다.</p>
<h3>AI가 빛나는 순간들</h3>
<p>가장 인상적이었던 건 반복 작업에서의 효율성이었습니다. Java 파일 수백 개를 C#으로 변환하는 건 사람이 하면 며칠이 걸리는 단순 노동입니다. 하지만 AI에게는 그냥 "이거 C#으로 바꿔줘"라고 하면 끝이었습니다.</p>
<p>XML 문서 주석을 추가하는 작업도 마찬가지였습니다. 111개 파일에 2,000줄 이상의 API 문서를 추가해야 했는데, AI에게 "이 클래스가 뭐하는 건지 주석으로 설명해줘"라고 하면 맥락을 파악해서 적절한 설명을 생성해줬습니다.</p>
<p>하지만 이번 프로젝트에서 진짜 게임 체인저는 <strong>Visual Studio 2026의 에이전트 기반 디버거</strong> 였습니다.</p>
<p>솔직히 말하면, AI 코딩 어시스턴트는 이제 어디서나 볼 수 있습니다. VS Code에도 있고, JetBrains IDE에도 있고, 심지어 웹 브라우저에서도 쓸 수 있죠. 코드 자동 완성이나 생성 기능은 이미 커모디티가 되었습니다. 그런데 Visual Studio 2026은 다른 곳에서 차별화를 만들었습니다.</p>
<p>유닛 테스트를 디버그 모드로 돌리다가 실패가 발생하면, 에이전트가 알아서 움직이기 시작합니다. "뭐가 문제지?"라고 물을 필요도 없습니다. 에이전트가 스스로 중단점을 설정하고, 변수 값을 추적하고, 호출 스택을 분석합니다. 내부 MCP 서버를 통해 디버거 상태를 실시간으로 수집하면서 문제의 근본 원인을 찾아나가는 모습은 마치 시니어 개발자가 옆에서 페어 디버깅을 해주는 것 같았습니다.</p>
<p>특히 zlib 압축 해제 문제를 추적할 때 이 기능이 빛났습니다. Java와 C#에서 같은 바이트 배열을 넣었는데 결과가 다르게 나오는 상황. 평소였다면 양쪽 코드에 일일이 중단점을 걸고, 바이트 단위로 비교하며 몇 시간을 써야 했을 겁니다. 하지만 에이전트 기반 디버거는 "이 두 결과가 왜 다른지 추적해줘"라는 요청 하나로 스스로 분석을 시작했고, 헤더 처리 방식의 차이를 짚어냈습니다.</p>
<p>이게 바로 Visual Studio 2026의 <strong>moat</strong> 라고 생각합니다. 코드 생성은 누구나 할 수 있지만, 디버거와 AI의 깊은 통합은 수십 년간 디버깅 도구를 만들어온 Microsoft만이 할 수 있는 영역입니다. 이 기능이 없었다면 이 프로젝트는 3주가 아니라 3달이 걸렸을지도 모릅니다.</p>
<h3>그래도 사람이 필요한 순간들</h3>
<p>하지만 모든 걸 AI에게 맡길 수는 없었습니다. "Apache POI 대신 뭘 써야 하지?"라는 질문에 AI는 여러 옵션을 제시해줬지만, 실제로 어떤 라이브러리가 프로젝트에 맞는지 판단하고 결정하는 건 제 몫이었습니다.</p>
<p>특히 디버깅은 아직 사람의 영역이라고 느꼈습니다. zlib 압축 해제 결과가 달라지는 문제를 추적할 때, AI에게 "왜 이게 다르게 나오지?"라고 물어봐도 명확한 답을 얻기 어려웠습니다. 결국 바이트 배열을 직접 덤프하고, Java와 C#의 동작을 비교하며 원인을 찾아야 했습니다.</p>
<h3>페어 프로그래밍의 새로운 정의</h3>
<p>결론적으로, AI는 최고의 주니어 개발자 같았습니다. 시키는 건 정말 잘합니다. 빠르고, 지치지 않고, 불평도 안 합니다. 하지만 "뭘 시킬지" 결정하는 건 여전히 시니어의 몫입니다.</p>
<p>그런데 Visual Studio 2026의 에이전트 기반 디버거는 이 공식을 살짝 바꿔놓았습니다. 코드 생성에서는 AI가 주니어 역할이 맞지만, 디버깅에서는 오히려 AI가 시니어처럼 행동했습니다. 제가 "이거 왜 안 되지?" 하고 막막해할 때, 에이전트가 먼저 가설을 세우고 검증하고, "여기가 문제인 것 같습니다"라고 짚어줬으니까요.</p>
<p>전통적인 페어 프로그래밍은 한 명이 코드를 치고, 다른 한 명이 옆에서 리뷰하는 방식이었습니다. 하지만 AI 시대의 페어 프로그래밍은 다릅니다. 코드 작성은 AI가 치고 사람이 리뷰하고, 디버깅은 AI가 분석하고 사람이 판단합니다. 역할이 상황에 따라 유연하게 바뀌는 거죠.</p>
<p>이 프로젝트를 통해 깨달은 건, AI 시대의 개발자는 코드를 직접 치는 시간보다 "어떤 코드를 쳐야 하는지" 판단하는 시간이 더 중요해졌다는 것입니다. 그리고 좋은 도구는 그 판단을 더 빠르고 정확하게 할 수 있도록 도와줍니다. Visual Studio 2026은 그런 도구였습니다.</p>
<h2>마무리하며</h2>
<p>3주간의 여정이 끝났습니다. 54개의 커밋, 641개의 파일, 5만 줄 이상의 코드.</p>
<p>지금 <a href="https://github.com/rkttu/libhwpsharp">libhwpsharp</a>는 NuGet에 배포되어 있고, 누구나 .NET 프로젝트에서 HWP 파일을 다룰 수 있습니다. 물론 아직 갈 길이 멉니다. 실제 필드에서 다양한 HWP 파일을 만나면 분명 예상치 못한 엣지 케이스들이 나올 것입니다.</p>
<p>그래도 첫 발을 뗐다는 것, 그리고 AI와 함께라면 혼자서는 엄두도 못 냈을 규모의 프로젝트도 도전해볼 수 있다는 것을 확인한 것만으로도 의미 있는 경험이었습니다.</p>
<p>혹시 HWP 파일을 .NET에서 다뤄야 하는 분이 계시다면, 한번 써보시고 피드백 부탁드립니다!</p>
<h2>앞으로의 계획</h2>
<p>libhwpsharp는 시작일 뿐입니다. neolord0 님께서는 hwplib 외에도 여러 유용한 프로젝트를 만들어 두셨는데, 이들도 .NET으로 가져올 계획입니다.</p>
<h3>hwpxlib 포팅</h3>
<p>첫 번째 목표는 <a href="https://github.com/neolord0/hwpxlib">hwpxlib</a>입니다. HWPX는 한글과컴퓨터가 새롭게 도입한 개방형 문서 포맷으로, 기존 HWP의 바이너리 형식 대신 XML 기반의 압축 파일 구조를 사용합니다. 정부 기관을 중심으로 HWPX 채택이 늘어나고 있어서, .NET에서도 이 포맷을 다룰 수 있어야 합니다.</p>
<p>다행히 HWPX는 XML 기반이라 HWP보다 포팅이 수월할 것으로 예상됩니다. OLE2 복합 문서의 늪에서 허우적거렸던 경험을 생각하면, ZIP + XML 조합은 거의 휴양지 수준이죠.</p>
<h3>HWP → HWPX 변환 도구</h3>
<p>두 번째 목표는 neolord0 님의 HWP to HWPX 변환 도구 포팅입니다. 레거시 HWP 파일을 새로운 HWPX 포맷으로 마이그레이션해야 하는 수요가 분명 있을 것입니다. 이 도구까지 포팅되면, .NET 생태계에서 한글 문서 처리의 전체 파이프라인이 완성됩니다.</p>
<p>이 두 프로젝트도 완성되면 블로그에서 공유하겠습니다. 기대해 주세요!</p>
<h2>기술적 세부사항</h2>
<p>마지막으로, 개발 과정에서 마주친 주요 기술적 도전들을 정리해 둡니다.</p>
<h3>Apache POI → OpenMcdf 전환</h3>
<table>
<thead>
<tr>
<th>구분</th>
<th>Java (POI)</th>
<th>C# (OpenMcdf)</th>
</tr>
</thead>
<tbody><tr>
<td>디렉터리 접근</td>
<td><code>DirectoryEntry</code></td>
<td><code>CFStorage</code></td>
</tr>
<tr>
<td>스트림 읽기</td>
<td><code>DocumentInputStream</code></td>
<td><code>CFStream</code></td>
</tr>
<tr>
<td>리소스 관리</td>
<td><code>close()</code></td>
<td><code>Dispose()</code> / <code>using</code></td>
</tr>
</tbody></table>
<h3>언어별 차이 극복</h3>
<table>
<thead>
<tr>
<th>Java</th>
<th>C#</th>
<th>처리 방법</th>
</tr>
</thead>
<tbody><tr>
<td><code>byte</code> (signed)</td>
<td><code>byte</code> (unsigned)</td>
<td><code>sbyte</code> 사용 또는 변환</td>
</tr>
<tr>
<td><code>getXxx()</code> / <code>setXxx()</code></td>
<td>Property</td>
<td>자동 변환</td>
</tr>
<tr>
<td><code>Iterator&lt;T&gt;</code></td>
<td><code>foreach</code></td>
<td>LINQ 활용</td>
</tr>
<tr>
<td>throws 선언</td>
<td>없음</td>
<td>try-catch 패턴</td>
</tr>
</tbody></table>
<h2>감사의 말</h2>
<p>이 프로젝트는 <a href="https://github.com/neolord0">neolord0</a> (박성균)님의 <a href="https://github.com/neolord0/hwplib">hwplib</a> 없이는 존재할 수 없었습니다.</p>
<p>HWP 파일 포맷은 공식 문서가 부족하고, 버전별로 미묘한 차이가 있어서 리버스 엔지니어링이 쉽지 않은 영역입니다. 그럼에도 불구하고 박성균 님께서는 수년간 hwplib을 꾸준히 개발하고 유지보수해 오셨습니다. 꼼꼼하게 작성된 유닛 테스트, 명확한 코드 구조, 그리고 Apache License 2.0으로 공개해주신 덕분에 이 포팅 프로젝트가 가능했습니다.</p>
<p>특히 47개의 테스트 케이스는 포팅 과정에서 등대와 같은 역할을 해주었습니다. "이것만 통과하면 된다"는 명확한 목표가 있었기에 3주라는 짧은 기간 안에 완성할 수 있었습니다.</p>
<p>오픈소스 생태계는 이렇게 서로의 어깨 위에 올라서며 성장합니다. 누군가의 묵묵한 헌신이 또 다른 누군가에게 새로운 가능성을 열어줍니다. 박성균 님께서 Java 생태계에 심어주신 씨앗이 이제 .NET 생태계에서도 싹을 틔우게 되었습니다.</p>
<p>진심으로 감사드립니다. 🙏</p>
<h2>링크</h2>
<ul>
<li><strong>GitHub</strong>: <a href="https://github.com/rkttu/hwplibsharp">rkttu/libhwpsharp</a></li>
<li><strong>NuGet</strong>: <a href="https://www.nuget.org/packages/HwpLibSharp/">HwpLibSharp</a></li>
<li><strong>원본 프로젝트</strong>: <a href="https://github.com/neolord0/hwplib">neolord0/hwplib</a></li>
</ul>
]]></content:encoded></item><item><title><![CDATA[테이블에서 카드로: 식탁보 카탈로그 UI의 현대화 여정]]></title><description><![CDATA[식탁보 카탈로그 페이지가 현대적인 카드 UI로 개편되고, 카테고리 필터 기능이 추가되었습니다. 또한 Generic Host 패턴 적용과 품질 관리 도구가 새롭게 도입되었습니다.]]></description><link>https://devwrite.ai/tablecloth-catalog-ui-refactoring</link><guid isPermaLink="true">https://devwrite.ai/tablecloth-catalog-ui-refactoring</guid><category><![CDATA[C#]]></category><category><![CDATA[xsl]]></category><dc:creator><![CDATA[Jung-hyun, Nam]]></dc:creator><pubDate>Sun, 07 Dec 2025 15:00:00 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/gql/60adcb82557cc70e51211e5c/3717c0bf-6ab7-49b3-8aa9-68fd13c6e0f0.jpg" length="0" type="image/jpeg"/><content:encoded><![CDATA[<h2>들어가며</h2>
<p>한국에서 인터넷 뱅킹을 이용해본 적이 있다면, 각종 보안 프로그램 설치 요구에 고개를 끄덕이게 될 것입니다. ActiveX는 사라졌지만 그 자리를 대신한 수많은 보안 플러그인들—AhnLab Safe Transaction, TouchEn nxKey, Veraport 등—은 여전히 우리의 PC에 설치를 요구합니다.</p>
<p><a href="https://yourtablecloth.app">식탁보(TableCloth)</a> 프로젝트는 이런 보안 프로그램들을 Windows Sandbox라는 격리된 환경에서 실행할 수 있게 해주는 오픈소스 도구입니다. 그리고 <a href="https://github.com/yourtablecloth/TableClothCatalog">식탁보 카탈로그</a>는 어떤 금융 사이트에서 어떤 보안 프로그램이 필요한지를 정리해둔 데이터베이스 역할을 합니다.</p>
<h2>이번 업데이트 한눈에 보기</h2>
<p>식탁보 카탈로그 프로젝트에 다섯 건의 커밋이 적용되었습니다. 이번 업데이트는 <strong>프론트엔드</strong>, <strong>백엔드</strong>, <strong>DevOps</strong> 세 영역에 걸친 종합적인 개선입니다.</p>
<table>
<thead>
<tr>
<th>영역</th>
<th>변경 사항</th>
<th>핵심 키워드</th>
</tr>
</thead>
<tbody><tr>
<td><strong>프론트엔드</strong></td>
<td>카탈로그 웹 페이지 전면 재설계</td>
<td>카드 UI, 카테고리 필터, 반응형 레이아웃</td>
</tr>
<tr>
<td><strong>백엔드</strong></td>
<td>빌드 도구 아키텍처 리팩토링</td>
<td>Generic Host, 의존성 주입, 구조화된 로깅</td>
</tr>
<tr>
<td><strong>DevOps</strong></td>
<td>품질 관리 자동화 도구 추가</td>
<td>이미지 검증, 미사용 리소스 정리, 파비콘 수집 개선</td>
</tr>
</tbody></table>
<p>각 영역별로 무엇이 바뀌었고, 왜 그런 결정을 내렸는지 자세히 살펴보겠습니다.</p>
<hr />
<h2>프론트엔드: 테이블에서 카드로</h2>
<h3>왜 UI를 바꿔야 했을까?</h3>
<p>기존 카탈로그 페이지는 전형적인 HTML 테이블 형태였습니다. 카테고리, 서비스 이름, 필요한 패키지 목록이 행과 열로 정렬된 구조였죠. 기능적으로는 문제가 없었지만, 몇 가지 한계가 있었습니다.</p>
<p>먼저, 100개가 넘는 서비스를 스크롤하며 찾아야 했습니다. 모바일 환경에서는 가로 스크롤이 발생해 사용성이 떨어졌고, 시각적 계층 구조가 없어 정보 파악이 어려웠습니다. 무엇보다 카테고리별 필터링이 불가능해서 원하는 서비스를 빠르게 찾기 어려웠습니다.</p>
<p>이런 문제를 해결하기 위해 카드 기반 UI로 전면 개편을 결정했습니다.</p>
<h3>XSL 트랜스폼으로 구현한 반응형 카드 UI</h3>
<p>식탁보 카탈로그의 재미있는 점은 데이터가 XML 형식으로 저장되고, 웹 페이지는 <strong>XSLT(XSL Transformations)</strong> 를 통해 렌더링된다는 것입니다. 별도의 서버 사이드 로직 없이 브라우저가 직접 XML을 HTML로 변환합니다.</p>
<h4>디자인 토큰 시스템 도입</h4>
<p>현대적인 CSS 설계의 핵심은 <strong>디자인 토큰</strong> 입니다. 색상, 간격, 그림자 등을 CSS 변수로 정의하면 일관성 있는 디자인을 유지하면서도 유지보수가 쉬워집니다.</p>
<pre><code class="language-css">:root {
    /* 색상 팔레트 */
    --primary-color: #2563eb;
    --primary-hover: #1d4ed8;
    --bg-color: #f8fafc;
    --card-bg: #ffffff;
    --text-primary: #1e293b;
    --text-secondary: #64748b;
    --border-color: #e2e8f0;
    
    /* 그림자 */
    --shadow: 0 1px 3px rgba(0,0,0,0.1), 0 1px 2px rgba(0,0,0,0.06);
    --shadow-lg: 0 10px 15px -3px rgba(0,0,0,0.1), 0 4px 6px -2px rgba(0,0,0,0.05);
    
    /* 레이아웃 */
    --radius: 12px;
}
</code></pre>
<p>이 색상 체계는 Tailwind CSS의 기본 팔레트에서 영감을 받았습니다. 슬레이트 계열의 텍스트 색상과 블루 계열의 강조색을 조합하면 깔끔하면서도 전문적인 인상을 줄 수 있습니다.</p>
<h3>CSS Grid로 구현한 반응형 레이아웃</h3>
<p>카드 레이아웃의 핵심은 CSS Grid의 <code>auto-fill</code>과 <code>minmax()</code> 조합입니다:</p>
<pre><code class="language-css">.services-grid {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(340px, 1fr));
    gap: 1.25rem;
}
</code></pre>
<p>이 한 줄의 CSS로 다음을 달성합니다. 화면 너비에 따라 열 개수가 자동으로 조절되고, 각 카드는 최소 340px를 유지하면서 가능한 공간에서 균등하게 분배됩니다. 카드 간 간격은 20px로 일관되게 유지됩니다.</p>
<p>340px라는 최소 너비는 모바일 환경(약 375px)에서도 단일 열로 깔끔하게 표시되도록 계산된 값입니다.</p>
<h3>마이크로 인터랙션으로 생동감 부여</h3>
<p>정적인 카드보다는 사용자 상호작용에 반응하는 카드가 더 매력적입니다:</p>
<pre><code class="language-css">.service-card {
    transition: transform 0.2s, box-shadow 0.2s;
}

.service-card:hover {
    transform: translateY(-4px);
    box-shadow: var(--shadow-lg);
}
</code></pre>
<p>마우스를 올리면 카드가 살짝 떠오르는 효과입니다. 0.2초의 트랜지션 시간은 부드러우면서도 지연 없이 반응하는 느낌을 줍니다. 4px의 상승 거리는 미묘하지만 확실히 인지되는 수준입니다.</p>
<h2>JavaScript 카테고리 필터 구현</h2>
<p>100개가 넘는 서비스 중에서 원하는 것을 찾으려면 필터링이 필수입니다. 간단한 바닐라 JavaScript로 구현했습니다:</p>
<pre><code class="language-javascript">function filterCards(category) {
    const cards = document.querySelectorAll('.service-card');
    const buttons = document.querySelectorAll('.filter-btn');
    
    // 버튼 상태 업데이트
    buttons.forEach(btn =&gt; btn.classList.remove('active'));
    event.target.classList.add('active');
    
    // 카드 필터링
    cards.forEach(card =&gt; {
        if (category === 'all' || card.dataset.category === category) {
            card.style.display = 'block';
        } else {
            card.style.display = 'none';
        }
    });
}
</code></pre>
<p>핵심은 각 카드에 <code>data-category</code> 속성을 부여하는 것입니다. XSL에서 이렇게 생성합니다:</p>
<pre><code class="language-xml">&lt;div class="service-card" data-category="{@Category}"&gt;
</code></pre>
<p>이 방식의 장점은 몇 가지가 있습니다. 클라이언트에서 즉시 필터링하므로 서버 요청이 필요 없고, 단순 토글 기능이므로 복잡한 URL 상태 관리도 필요 없습니다. 또한 JavaScript가 비활성화된 환경에서도 모든 카드가 그대로 표시되어 점진적 향상(Progressive Enhancement) 원칙을 따릅니다.</p>
<h3>카테고리별 시각적 구분</h3>
<p>각 카테고리마다 고유한 색상 뱃지를 부여했습니다:</p>
<pre><code class="language-css">.category-Banking { background: #dbeafe; color: #1e40af; }
.category-CreditCard { background: #fce7f3; color: #9d174d; }
.category-Government { background: #d1fae5; color: #065f46; }
.category-Financing { background: #fef3c7; color: #92400e; }
.category-Insurance { background: #e0e7ff; color: #3730a3; }
.category-Education { background: #f3e8ff; color: #6b21a8; }
.category-Security { background: #fee2e2; color: #991b1b; }
.category-Other { background: #f1f5f9; color: #475569; }
</code></pre>
<p>색상 선택에는 의미를 담았습니다. 은행(Banking)에는 신뢰와 안정을 상징하는 블루를, 카드(CreditCard)에는 결제와 연관된 핑크/마젠타를 적용했습니다. 공공기관(Government)에는 공공성을 나타내는 그린을, 금융(Financing)에는 돈을 연상시키는 앨버를 사용했습니다. 보험(Insurance)에는 보호를 의미하는 인디고를, 보안(Security)에는 주의와 경고를 나타내는 레드를 배정했습니다.</p>
<hr />
<h2>백엔드: Generic Host 패턴으로 리팩토링한 빌드 도구</h2>
<p>UI 개선과 함께 백엔드 도구인 <code>catalogutil.cs</code>도 대폭 리팩토링되었습니다. 핵심은 .NET의 <strong>Generic Host</strong> 패턴 적용입니다.</p>
<h3>Generic Host란?</h3>
<p>Generic Host는 .NET에서 애플리케이션의 수명 주기, 의존성 주입, 구성, 로깅 등을 관리하는 프레임워크입니다. 원래 ASP.NET Core 웹 애플리케이션에서 사용하던 패턴인데, .NET Core 3.0부터 콘솔 앱이나 백그라운드 서비스에서도 활용할 수 있게 되었습니다.</p>
<pre><code class="language-csharp">// Generic Host 설정
var builder = Host.CreateApplicationBuilder(args);

// 구성에서 타임아웃 값 읽기
const double DefaultTimeoutSeconds = 15d;
const double MinTimeoutSeconds = 5d;
var configuredTimeout = builder.Configuration.GetValue("TimeoutSeconds", DefaultTimeoutSeconds);
var timeoutSeconds = Math.Max(configuredTimeout, MinTimeoutSeconds);

// 서비스 등록 (의존성 주입)
builder.Services.AddSingleton&lt;CatalogLoader&gt;();
builder.Services.AddSingleton&lt;ImageConverter&gt;();
</code></pre>
<h3>왜 콘솔 앱에 Generic Host를?</h3>
<p>"단순한 빌드 스크립트에 이런 복잡한 패턴이 필요한가?"라고 물을 수 있습니다. 하지만 Generic Host가 제공하는 이점은 분명합니다:</p>
<h4><strong>의존성 주입(DI)</strong></h4>
<pre><code class="language-csharp">// 생성자 주입으로 의존성 명시
public class CatalogLoader
{
    private readonly HttpClient _httpClient;
    private readonly ILogger&lt;CatalogLoader&gt; _logger;
    
    public CatalogLoader(HttpClient httpClient, ILogger&lt;CatalogLoader&gt; logger)
    {
        _httpClient = httpClient;
        _logger = logger;
    }
}
</code></pre>
<p>DI를 사용하면 클래스 간 결합도가 낮아지고, 테스트가 쉬워지며, 의존성이 명시적으로 드러납니다.</p>
<h4><strong>구성 관리</strong></h4>
<pre><code class="language-csharp">// appsettings.json 또는 환경 변수에서 설정 읽기
var timeout = builder.Configuration.GetValue("TimeoutSeconds", 15d);
</code></pre>
<p>하드코딩된 값 대신 외부 구성을 사용하면 환경별로 다른 설정을 적용할 수 있습니다.</p>
<h4><strong>구조화된 로깅</strong></h4>
<pre><code class="language-csharp">_logger.LogInformation("Processing service: {ServiceName}", service.Name);
</code></pre>
<p>구조화된 로깅은 로그를 단순 문자열이 아닌 검색 가능한 데이터로 만들어줍니다.</p>
<hr />
<h2>DevOps: 품질 관리 자동화와 파비콘 수집 개선</h2>
<h3>파비콘 수집 기능 개선</h3>
<p>카탈로그의 각 서비스에 아이콘을 표시하려면 해당 웹사이트의 파비콘을 수집해야 합니다. 이번 업데이트에서 파비콘 수집 로직이 크게 개선되었습니다.</p>
<h3>웹 앱 매니페스트 지원</h3>
<p>현대 웹사이트들은 <code>manifest.json</code>(또는 <code>manifest.webmanifest</code>)을 통해 앱 아이콘을 정의합니다:</p>
<pre><code class="language-json">{
  "icons": [
    { "src": "/icons/icon-192.png", "sizes": "192x192" },
    { "src": "/icons/icon-512.png", "sizes": "512x512" }
  ]
}
</code></pre>
<p>새 버전에서는 HTML의 <code>&lt;link rel="manifest"&gt;</code> 태그를 파싱하여 매니페스트 파일을 찾고, 그 안의 아이콘 정보를 추출합니다.</p>
<h3>폴백 전략</h3>
<p>하나의 방법으로 파비콘을 찾지 못하면 다음 방법을 시도합니다:</p>
<ol>
<li><strong>웹 앱 매니페스트</strong>: <code>manifest.json</code>의 icons 배열</li>
<li><strong>Link 태그</strong>: <code>&lt;link rel="icon"&gt;</code> 또는 <code>&lt;link rel="shortcut icon"&gt;</code></li>
<li><strong>기본 위치</strong>: <code>/favicon.ico</code></li>
<li><strong>외부 서비스</strong>: Google Favicon 서비스 등 폴백</li>
</ol>
<p>이런 다중 폴백 전략으로 대부분의 웹사이트에서 아이콘을 성공적으로 가져올 수 있습니다.</p>
<h3>이미지 품질 관리 자동화</h3>
<p>오픈소스 프로젝트에서 데이터 품질 관리는 항상 도전 과제입니다. 이번에 추가된 품질 관리 도구는 여러 검증 작업을 자동으로 수행합니다.</p>
<p>먼저 이미지 무결성 검증 기능이 있습니다. 카탈로그에 등록된 모든 서비스의 아이콘 파일이 실제로 존재하는지 확인하고, 손상되었거나 로드할 수 없는 이미지를 탐지합니다. PNG 포맷의 유효성도 함께 검사합니다.</p>
<p>다음으로 미사용 리소스 정리 기능이 있습니다.</p>
<pre><code class="language-text">⚠️  Orphan image found: images/Banking/OldBank.png
    → This image is not referenced by any service in the catalog
</code></pre>
<p>서비스가 삭제되었지만 이미지는 남아있는 경우를 자동 탐지합니다.</p>
<hr />
<h2>마치며</h2>
<p>이번 업데이트는 단순한 "예쁜 UI" 변경이 아닙니다. 사용자가 원하는 서비스를 빠르게 찾을 수 있도록 UX를 개선하고, 개발자가 프로젝트를 유지보수하기 쉽도록 코드 품질을 높이며, 데이터 무결성을 자동으로 검증하는 시스템을 구축했습니다.</p>
<p>오픈소스 프로젝트의 가치는 코드 한 줄 한 줄에 담긴 세심한 고민에서 나옵니다. 식탁보 프로젝트에 관심이 있으시다면, 직접 카탈로그 페이지를 방문해보시거나 GitHub에서 코드를 살펴보세요.</p>
<h2>참고 링크</h2>
<ul>
<li><a href="https://github.com/yourtablecloth/TableClothCatalog">식탁보 카탈로그 GitHub</a></li>
<li><a href="https://yourtablecloth.app">식탁보 프로젝트 홈페이지</a></li>
<li><a href="https://yourtablecloth.app/TableClothCatalog/">식탁보 카탈로그 웹 페이지</a></li>
<li><a href="https://learn.microsoft.com/dotnet/core/extensions/generic-host">.NET Generic Host 공식 문서</a></li>
</ul>
]]></content:encoded></item><item><title><![CDATA[식탁보 프로젝트 카탈로그 빌더, .NET 10과 FBA로 현대화]]></title><description><![CDATA[식탁보 프로젝트의 카탈로그 빌더가 .NET 10으로 업그레이드되고 File-Based App(FBA) 방식으로 단순화되었습니다.]]></description><link>https://devwrite.ai/tablecloth-catalog-dotnet10-fba</link><guid isPermaLink="true">https://devwrite.ai/tablecloth-catalog-dotnet10-fba</guid><category><![CDATA[dotnet]]></category><category><![CDATA[C#]]></category><dc:creator><![CDATA[Jung-hyun, Nam]]></dc:creator><pubDate>Sat, 06 Dec 2025 00:00:00 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/gql/60adcb82557cc70e51211e5c/4aad4d4f-d31b-4bdb-af25-4fad27c014c9.jpg" length="0" type="image/jpeg"/><content:encoded><![CDATA[<h2>식탁보 프로젝트란?</h2>
<p><a href="https://github.com/yourtablecloth">식탁보(TableCloth)</a>는 한국의 인터넷 뱅킹 환경에서 필요한 보안 플러그인들을 Windows Sandbox 환경에서 안전하게 사용할 수 있도록 도와주는 오픈소스 프로젝트입니다. 다양한 금융 기관 웹사이트에서 요구하는 보안 프로그램들을 격리된 환경에서 실행하여 호스트 시스템의 안전을 보장합니다.</p>
<h2>카탈로그 리포지토리란?</h2>
<p><a href="https://github.com/yourtablecloth/TableClothCatalog">TableClothCatalog</a> 리포지토리는 식탁보 프로젝트에서 참조하는 금융 기관 사이트별 보안 프로그램 목록을 보관하는 저장소입니다. 각 은행, 증권사, 보험사 등의 웹사이트에서 요구하는 보안 플러그인 정보가 체계적으로 정리되어 있으며, 카탈로그 빌더 도구는 이 정보를 바탕으로 식탁보 앱에서 사용할 수 있는 형태로 가공합니다.</p>
<h2>최근 카탈로그 빌더 업데이트</h2>
<p>최근 이 리포지토리에 중요한 업데이트가 적용되었습니다. 이번 커밋에서는 카탈로그 빌더 도구가 .NET 10으로 업그레이드되고, 프로젝트 구조가 대폭 단순화되었습니다.</p>
<h3>주요 변경 사항</h3>
<h4>.NET 10 업그레이드</h4>
<pre><code class="language-yaml"># 기존
dotnet-version: 8.0.x

# 변경
dotnet-version: 10.0.x
</code></pre>
<p>빌드 파이프라인이 .NET 8에서 .NET 10으로 업그레이드되었습니다. 이를 통해 최신 런타임의 성능 향상과 새로운 언어 기능을 활용할 수 있게 되었습니다.</p>
<h4>File-Based App(FBA) 방식으로 전환</h4>
<p>가장 눈에 띄는 변화는 프로젝트 구조의 단순화입니다. 기존에는 별도의 <code>.csproj</code> 프로젝트 파일과 솔루션 파일(<code>.sln</code>)을 사용했지만, 이번 업데이트에서는 이 파일들이 삭제되고 단일 C# 스크립트 파일(<code>catalogutil.cs</code>)로 통합되었습니다.</p>
<pre><code class="language-csharp">#!/usr/bin/env dotnet
#:package IronSoftware.System.Drawing@2025.9.3
#:property PublishAot=false

using SixLabors.ImageSharp;
using SixLabors.ImageSharp.Formats.Png;
using System.Collections.Concurrent;
// ...
</code></pre>
<p>이것이 바로 .NET의 <strong>File-Based App(FBA)</strong> 방식입니다. FBA는 다음과 같은 장점을 제공합니다:</p>
<ul>
<li><strong>프로젝트 파일 불필요</strong>: <code>.csproj</code> 없이 단일 <code>.cs</code> 파일로 애플리케이션 실행 가능</li>
<li><strong>패키지 참조 인라인 선언</strong>: <code>#:package</code> 지시문으로 NuGet 패키지 직접 참조</li>
<li><strong>빌드 속성 인라인 설정</strong>: <code>#:property</code> 지시문으로 빌드 속성 설정</li>
<li><strong>셔뱅(Shebang) 지원</strong>: <code>#!/usr/bin/env dotnet</code>으로 Unix 스타일 실행 지원</li>
</ul>
<h4>Graceful Shutdown 지원</h4>
<p>새로운 버전에서는 프로세스 종료 시 더 안정적인 처리가 가능해졌습니다:</p>
<pre><code class="language-csharp">// Graceful shutdown 타임아웃
var gracefulShutdownTimeout = TimeSpan.FromSeconds(5);

Console.CancelKeyPress += (sender, e) =&gt;
{
    if (cts.IsCancellationRequested)
    {
        // 두 번째 Ctrl+C: 강제 종료
        Console.Out.WriteLine("Info: Force exit requested. Terminating immediately...");
        e.Cancel = false;
        return;
    }

    Console.Out.WriteLine($"Info: Cancellation requested. Shutting down gracefully (timeout: {gracefulShutdownTimeout.TotalSeconds}s)...");
    Console.Out.WriteLine("Info: Press Ctrl+C again to force exit.");
    e.Cancel = true; // 즉시 종료 방지
    cts.CancelAfter(gracefulShutdownTimeout);
    cts.Cancel();
};
</code></pre>
<p>주요 특징:</p>
<ul>
<li><strong>첫 번째 Ctrl+C</strong>: Graceful shutdown 시작 (5초 타임아웃)</li>
<li><strong>두 번째 Ctrl+C</strong>: 즉시 강제 종료</li>
<li><strong>SIGINT 표준 종료 코드(130)</strong> 반환</li>
</ul>
<h4>빌드 프로세스 단순화</h4>
<pre><code class="language-yaml"># 기존: 빌드 후 실행
- name: Build Catalog Builder Tool
  run: dotnet build src/TableCloth.CatalogBuilder/TableCloth.CatalogBuilder.csproj --configuration Release

- name: Run Catalog Builder Tool
  run: dotnet run --project src/TableCloth.CatalogBuilder/TableCloth.CatalogBuilder.csproj --configuration Release -- ./docs/ ./outputs/

# 변경: 직접 실행
- name: Run Catalog Builder Tool
  run: dotnet run --file src/catalogutil.cs -- ./docs/ ./outputs/
</code></pre>
<p>FBA 방식을 사용함으로써 별도의 빌드 단계가 필요 없어지고, <code>dotnet run --file</code> 명령어로 직접 스크립트를 실행할 수 있게 되었습니다.</p>
<h2>삭제된 파일들</h2>
<p>이번 업데이트에서 다음 파일들이 삭제되었습니다:</p>
<ul>
<li><code>src/TableCloth.CatalogBuilder/TableCloth.CatalogBuilder.csproj</code></li>
<li><code>src/TableClothCatalog.sln</code></li>
</ul>
<p>그리고 <code>src/TableCloth.CatalogBuilder/Program.cs</code>가 <code>src/catalogutil.cs</code>로 이름이 변경되고 내용이 개선되었습니다.</p>
<h2>정리</h2>
<p>이번 업데이트는 .NET 생태계의 최신 트렌드인 FBA 방식을 적극 활용하여 프로젝트 구조를 단순화한 좋은 사례입니다. 특히 작은 유틸리티 도구의 경우 별도의 프로젝트 파일 없이 단일 스크립트로 관리하는 것이 훨씬 효율적입니다.</p>
<p>식탁보 프로젝트에 관심이 있다면 <a href="https://github.com/yourtablecloth/TableCloth">GitHub 리포지토리</a>를 방문해 보세요!</p>
<h2>참고 링크</h2>
<ul>
<li><a href="https://github.com/yourtablecloth">식탁보 프로젝트 GitHub</a></li>
<li><a href="https://github.com/yourtablecloth/TableClothCatalog">TableClothCatalog 리포지토리</a></li>
<li><a href="https://github.com/yourtablecloth/TableClothCatalog/commit/8edbd2e9ca9bef3085932d39e88703391126f04d">해당 커밋</a></li>
</ul>
]]></content:encoded></item><item><title><![CDATA[AI '학습'이라는 용어에 속지 마세요]]></title><description><![CDATA[AI 모델의 '학습'은 빌드타임, '추론'은 런타임에 해당합니다. 서비스에 배포된 모델은 실시간으로 배우지 않으며, 개발자가 할 일은 좋은 데이터(RAG)와 프롬프트를 제공하는 것입니다.]]></description><link>https://devwrite.ai/ai-training-inference-explained</link><guid isPermaLink="true">https://devwrite.ai/ai-training-inference-explained</guid><category><![CDATA[AI]]></category><category><![CDATA[llm]]></category><dc:creator><![CDATA[Jung-hyun, Nam]]></dc:creator><pubDate>Fri, 05 Dec 2025 06:00:00 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/gql/60adcb82557cc70e51211e5c/99fdee8f-c73d-4368-b196-fe6d35a439b4.jpg" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>서비스 개발을 하는 동료들과 이야기를 나누다 보면, AI 도입에 대해 막연한 부담감을 느끼는 경우를 종종 봅니다. 그 부담감의 근원을 파고들면 대개 <strong>'학습(Training)'</strong> 이라는 용어가 주는 오해에서 비롯됩니다.</p>
<blockquote>
<p>"모델을 서비스에 붙이면, 유저 데이터를 먹고 실시간으로 학습해서 똑똑해지는 건가요?"
"그럼 그 학습 과정을 우리가 통제할 수 있나요? 이상한 걸 배우면 어떡하죠?"</p>
</blockquote>
<p>만약 이런 고민을 하고 계셨다면, 잠시 걱정을 내려놓으셔도 좋습니다. 오늘 그 오해를 개발자의 언어로 풀어드리겠습니다.</p>
<h2>'학습'은 빌드타임, '추론'은 런타임</h2>
<p>가장 먼저 바로잡아야 할 것은, <strong>우리가 서비스에 배포하는 AI 모델은 대부분 '얼어있는(Frozen)' 상태</strong> 라는 점입니다.</p>
<p>개발 용어로 비유하면 다음과 같습니다.</p>
<table>
<thead>
<tr>
<th>개념</th>
<th>AI 용어</th>
<th>개발 용어 비유</th>
<th>설명</th>
</tr>
</thead>
<tbody><tr>
<td>모델 만들기</td>
<td>학습(Training)</td>
<td>빌드타임(Build Time)</td>
<td>엄청난 리소스와 시간이 필요</td>
</tr>
<tr>
<td>모델 사용하기</td>
<td>추론(Inference)</td>
<td>런타임(Runtime)</td>
<td>요청을 받아 결과를 반환</td>
</tr>
</tbody></table>
<p>우리가 서비스를 운영할 때, 실행 중인 바이너리 코드가 스스로 자기 코드를 수정하며 진화하지 않습니다. AI도 마찬가지입니다.</p>
<p>모델은 배포되는 순간, 더 이상 '배우는 학생'이 아니라 <strong>'지시대로 일하는 노동자'</strong> 가 됩니다. 우리가 걱정해야 할 영역은 학습이 아니라, 이 노동자가 일을 잘하도록 환경을 만들어주는 것입니다.</p>
<h2>도서관 비유로 이해하는 AI 구조</h2>
<p>그렇다면 최신 정보는 어떻게 반영하고, AI는 어떤 역할을 하는 걸까요? 저는 이 구조를 <strong>'도서관'</strong> 에 비유하곤 합니다.</p>
<table>
<thead>
<tr>
<th>구성 요소</th>
<th>도서관 비유</th>
<th>설명</th>
</tr>
</thead>
<tbody><tr>
<td>AI 모델 (LLM)</td>
<td>사서</td>
<td>언어 능력과 추론 능력을 갖춘 존재</td>
</tr>
<tr>
<td>RAG / DB</td>
<td>서고</td>
<td>서비스 데이터와 최신 정보가 저장된 공간</td>
</tr>
<tr>
<td>프롬프트</td>
<td>업무 지시서</td>
<td>사서에게 일을 시킬 때 주는 가이드라인</td>
</tr>
</tbody></table>
<p>서비스 개발자인 우리가 매일 하는 일은 <strong>'도서관에 신간을 채워 넣는 일(DB 업데이트)'</strong> 입니다. 사서(AI)는 우리가 채워 넣은 책을 필요할 때 꺼내서(Retrieve), 내용을 읽고 조합해서 사용자에게 전달(Inference)할 뿐입니다.</p>
<p>여기서 많은 분이 두려워하는 <strong>'학습(Fine-tuning)'</strong> 은 <strong>'사서를 대학원에 보내 재교육시키는 일'</strong> 에 해당합니다. 사서가 기본적인 문해력이 부족하거나, 일반적인 상식으로는 이해할 수 없는 특수 도메인을 다뤄야 할 때만 필요한 엣지 케이스입니다.</p>
<p>대부분의 비즈니스 문제는 사서를 재교육(학습)시키는 것이 아니라, 다음 세 가지로 해결됩니다:</p>
<ol>
<li><strong>똑똑한 사서 채용</strong> - 좋은 기본 모델 선택</li>
<li><strong>좋은 업무 매뉴얼</strong> - 잘 설계된 프롬프트</li>
<li><strong>정리된 서고</strong> - 구조화된 RAG/DB</li>
</ol>
<h2>AI는 '의미 처리 가속기'다</h2>
<p>이렇게 구조를 파악하고 나면, AI는 더 이상 두려운 미지의 존재가 아닙니다. 그저 우리 시스템 아키텍처에 꽂아야 할 하나의 <strong>'부품'</strong> 일 뿐입니다.</p>
<p>컴퓨터의 역사는 '처리의 가속화'였습니다.</p>
<table>
<thead>
<tr>
<th>하드웨어</th>
<th>가속화 대상</th>
</tr>
</thead>
<tbody><tr>
<td>CPU</td>
<td>계산과 로직(if-else) 처리</td>
</tr>
<tr>
<td>GPU</td>
<td>그래픽과 픽셀 처리</td>
</tr>
<tr>
<td>AI (LLM)</td>
<td>의미(Semantics)와 맥락(Context) 처리</td>
</tr>
</tbody></table>
<p>우리는 그동안 <code>if (text.contains("사과"))</code> 같은 코드로 인간의 언어를 기계적으로 처리하느라 고생했습니다. 이제는 그 '의미 처리'를 전담해 주는 고성능 가속기(AI)가 생긴 것입니다.</p>
<h2>마치며</h2>
<p>AI 시대라고 해서 개발자가 AI 모델을 직접 만들거나 수식을 이해해야 한다는 강박을 가질 필요는 없습니다.</p>
<p>우리가 MySQL의 내부 엔진 소스코드를 몰라도 훌륭한 백엔드 서버를 구축할 수 있듯이, AI라는 <strong>'똑똑한 사서'</strong> 를 우리 서비스의 어느 데스크에 앉히고, 어떤 권한을 줄지 설계하는 <strong>아키텍처링 능력</strong> 은 여전히 유효하며 더 중요해졌습니다.</p>
<p>AI에 과도한 의미를 부여하지 마십시오. 그것은 스스로 생각하고 반란을 일으키는 인공지능이 아니라, 우리가 입력한 데이터를 확률적으로 가장 그럴듯하게 처리해서 반환하는 <strong>'함수(Function)'</strong> 이자 <strong>'도구(Tool)'</strong> 입니다.</p>
<p>도구는 두려워할 대상이 아니라, 손에 익혀서 잘 써먹어야 할 대상입니다.</p>
]]></content:encoded></item></channel></rss>