DEV Community: Juan Gómez

Stop Squinting at .NET Stack Traces: Debug Them With Claude Inside Visual Studio

Juan Gómez — Fri, 17 Jul 2026 13:35:22 +0000

Stop Squinting at .NET Stack Traces: Debug Them With Claude Inside Visual Studio

An unhandled exception fires, and Visual Studio drops forty lines of stack trace into your lap. Thirty-eight of them live in Microsoft.EntityFrameworkCore.* or System.Private.CoreLib, one is an async state-machine frame with a name like <<Main>$>b__0_0, and exactly one points at code you wrote. Your job is to find that one line, understand why it blew up, and fix the actual cause — not the symptom.

We've all pasted a trace into a search engine and gotten back a single Stack Overflow question from 2015, zero answers, one comment that just says "did you ever solve this?". There's a better way, and it now lives right inside Visual Studio: hand the trace to Claude, get back a ranked diagnosis tied to your line, and a fix you can actually reason about.

Why .NET Stack Traces Are Hard to Read

Stack traces aren't hard because they're long. They're hard because modern .NET code rarely runs in a straight line, and the trace reflects the machinery, not your intent.

Async unwinding. await compiles into a state machine. When an exception crosses an await, the frames you see are MoveNext() calls and ExecutionContext.Run, not the tidy call chain you wrote. The method name shows up as <SomethingAsync>d__4, and the line that logically threw might be three awaits up.
Inner exceptions. The message on top is often the least useful one. The real cause is nested — a DbUpdateException wrapping a SqliteException, or a TargetInvocationException wrapping the thing you actually care about. If you only read the first line, you're debugging the wrapper.
AggregateException. Anything involving Task.WhenAll or parallelism can bundle several failures into one. The outer message says "One or more errors occurred" — thanks, very helpful.
Inlined and framework frames. The JIT inlines small methods, so frames disappear. And the frames that remain are mostly library internals you can't change and don't need to read.

An LLM is genuinely good at this specific chore. It has seen these exception shapes thousands of times, it can tell the framework noise from the signal, and — this is the part that matters — when it runs inside your IDE, it can correlate the trace with the actual source file and line.

Two Ways to Put Claude Inside Visual Studio

You don't need to leave the IDE or paste anything into a browser. There are two solid paths, and they suit different moments.

1. Copilot Chat with a Claude model (in-IDE, conversational)

Visual Studio 2022 (17.14+) ships GitHub Copilot with a model picker. Click the Copilot badge, open the model dropdown in the chat prompt box, and pick a Claude model — Sonnet for fast everyday diagnosis, Opus when the bug is genuinely nasty. From then on, every Copilot Chat reply is generated by Claude.

Two things make this path shine for debugging:

When an unhandled exception pops the Exception Helper while debugging, there's an inline Ask Copilot link right on that dialog. With Claude selected as your model, that one-click analysis runs on Claude.
In the chat box you can pull real context in with # references — #Program.cs, #solution, or a highlighted selection — so Claude reads your actual code, not a paraphrase.

If you'd rather bring your own Anthropic key instead of using Copilot's models, the same picker has Manage Models → add Anthropic → paste your API key. Handy if you're already paying for API access.

2. Claude Code in the integrated terminal (agentic)

There's no official Claude Code extension for the full Visual Studio yet, but you don't need one — Claude Code runs in any terminal, including View → Terminal (Ctrl+) inside VS. Runclaude`, paste the trace, and because Claude Code can read the whole repository, it will open the offending file itself, trace the call path, and propose the fix as a diff you approve or reject.

The trade-off is simple: Copilot Chat is faster for a quick "what does this mean?", while Claude Code is better when the fix touches several files or you want it to reproduce and verify. Use whichever the bug deserves.

A Real Example: The EF Core Trace That Blames the Wrong Thing

Let's debug something concrete. Here's a .NET 10 minimal API endpoint that returns an order summary. It looks reasonable, and it compiles cleanly:

`csharp
// Program.cs — .NET 10 minimal API
using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext(o => o.UseSqlite("Data Source=shop.db"));

var app = builder.Build();

app.MapGet("/orders/{customerId:int}/summary", async (int customerId, ShopContext db) =>
{
// Fire both queries "in parallel" to be fast — right?
var ordersTask = db.Orders.Where(o => o.CustomerId == customerId).ToListAsync();
var totalTask = db.Orders.Where(o => o.CustomerId == customerId).SumAsync(o => o.Total);

await Task.WhenAll(ordersTask, totalTask);

return Results.Ok(new { Orders = ordersTask.Result, Total = totalTask.Result });

});

app.Run();
`

Hit the endpoint and it throws. Here's the trace Visual Studio shows (trimmed to the frames that appear):

text System.InvalidOperationException: A second operation was started on this context instance before a previous operation completed. This is usually caused by different threads concurrently using the same instance of DbContext. For more information on how to avoid threading issues with DbContext, see https://go.microsoft.com/fwlink/?linkid=2097913. at Microsoft.EntityFrameworkCore.Internal.ConcurrencyDetector.EnterCriticalSection() at Microsoft.EntityFrameworkCore.Query.Internal.QueryCompiler.ExecuteAsync[TResult](Expression query, CancellationToken ct) at Microsoft.EntityFrameworkCore.Query.Internal.EntityQueryProvider.ExecuteAsync[TResult](Expression expression, CancellationToken ct) at Microsoft.EntityFrameworkCore.EntityFrameworkQueryableExtensions.ToListAsync[TSource](IQueryable1 source, CancellationToken ct)
at Program.<>c.<

$>b__0_0(Int32 customerId, ShopContext db) in C:\src\Shop.Api\Program.cs:line 12
`

Four of those five frames are EF Core internals. The one that's yours — Program.cs:line 12 — is the ToListAsync() call, which makes it look like ToListAsync is the villain. It isn't.

Feeding it to Claude the right way

The quality of the answer depends entirely on what you paste. A one-line message gets you a one-line guess. Give Claude the whole picture:

`text
.NET 10, EF Core 10, SQLite. This endpoint throws on every request under normal load
(not just concurrency). Full exception and the endpoint code below — what's the root
cause, and what's the idiomatic fix?

[paste the FULL exception via ex.ToString() — message + all inner exceptions + trace]

[paste the MapGet handler]
`

Three things make that prompt good:

The full exception, not the headline. ex.ToString() includes every inner exception and the complete trace. In Copilot Chat, #Program.cs pulls the source in for you.
The first frame that's yours. Point Claude at Program.cs:line 12 and the code around it. The framework frames are context; your frame is the crime scene.
The conditions. "Every request" vs "only under load" vs "intermittent" changes the diagnosis completely. Say what you observed.

What Claude tells you

Instead of "line 12 failed", you get the actual mechanism: EF Core's DbContext is not thread-safe and does not allow two operations on the same instance at once. Task.WhenAll starts the second query before the first finishes, both on the same injected db, and EF's ConcurrencyDetector throws. The line number was a red herring — the bug is the pattern, not the call.

And it gives you both fixes, with the trade-off:

csharp // Fix A — simplest: run them sequentially. One context, one operation at a time. var orders = await db.Orders.Where(o => o.CustomerId == customerId).ToListAsync(); var total = await db.Orders.Where(o => o.CustomerId == customerId).SumAsync(o => o.Total); return Results.Ok(new { Orders = orders, Total = total });

`csharp
// Fix B — real parallelism: give each query its OWN context via a factory.
builder.Services.AddDbContextFactory(o => o.UseSqlite("Data Source=shop.db"));

app.MapGet("/orders/{customerId:int}/summary",
async (int customerId, IDbContextFactory factory) =>
{
await using var ordersDb = await factory.CreateDbContextAsync();
await using var totalDb = await factory.CreateDbContextAsync();

var ordersTask = ordersDb.Orders.Where(o => o.CustomerId == customerId).ToListAsync();
var totalTask  = totalDb.Orders.Where(o => o.CustomerId == customerId).SumAsync(o => o.Total);

await Task.WhenAll(ordersTask, totalTask);
return Results.Ok(new { Orders = await ordersTask, Total = await totalTask });

});
`

Fix A is what you want 90% of the time — two SQLite queries are fast, and the parallelism was never worth the bug. Fix B is the answer when the queries are genuinely slow and independent, because IDbContextFactory<T> hands you a fresh, short-lived context per operation. That distinction — not the line number — is the thing you were actually missing, and it's the kind of judgment a good explanation gives you and a search result doesn't.

A .NET async stack trace has two kinds of frames: the forty that belong to the runtime, and the one that's your fault. Claude's job is to skip the forty and explain the one.

Verify — Don't Trust Blindly

Claude is a very fast senior colleague who is occasionally, confidently wrong. Treat its diagnosis as a strong hypothesis, not a verdict:

Reproduce and confirm. Apply the fix, re-run, and check the exception is actually gone — ideally under the same conditions that triggered it. In Visual Studio, set a breakpoint on the fixed line and watch the state.
Ask why, not just what. "Explain why this fixes it" surfaces a wrong root cause fast. If the reasoning doesn't hold, the fix probably doesn't either.
Watch for plausible-but-wrong causes. For intermittent bugs especially, Claude may propose a cause that fits the trace but isn't yours. Make it rank candidates and tell you how to distinguish them.

The debugger still owns state. Claude owns meaning. When you need to know the actual value of a variable at the moment of the crash, that's a watch window and a breakpoint, not a chat prompt.

When to Reach for Claude — and When Not To

Reach for it when:

The exception type or message is unfamiliar, or the trace is mostly framework internals.
The real cause is buried in inner exceptions or an AggregateException.
You're staring at async frames and can't tell which of your lines is the origin.
You want the idiomatic fix and the trade-offs, not just a patch that makes the red go away.

Don't bother when:

You already know the cause — a NullReferenceException on a line you just wrote doesn't need an LLM.
You need the runtime value of something — use the debugger.
The trace contains secrets or customer data. Connection strings, tokens, and PII live in exception messages and payloads more often than you'd like. Scrub before you paste, especially with a cloud model.

The rule of thumb: if you'd otherwise open a browser to search the exception, ask Claude instead — it's in the IDE, it can read your code, and it won't send you to a dead 2015 forum thread.

Key Takeaways

The trace shows machinery, not intent — async state machines, inner exceptions, and framework frames bury the one line that's yours. Reading traces is pattern recognition, which is exactly where an LLM helps.
Claude lives in Visual Studio two ways — pick it in Copilot Chat's model picker for quick, conversational diagnosis; run Claude Code in the integrated terminal when the fix is agentic and spans files.
Context is the whole game — paste the full ex.ToString(), point at the first frame that's yours, and describe when it happens. A headline message gets a headline guess.
The line number is often a red herring — the EF Core example throws at ToListAsync, but the bug is sharing one DbContext across parallel queries. The value is the explanation, not the location.
Verify, then trust — reproduce the fix, ask why it works, and never paste secrets. The debugger owns state; Claude owns meaning.

Deja de Entrecerrar los Ojos con los Stack Traces de .NET: Depúralos con Claude en Visual Studio

Juan Gómez — Fri, 17 Jul 2026 13:23:04 +0000

Deja de Entrecerrar los Ojos con los Stack Traces de .NET: Depúralos con Claude en Visual Studio

Salta una excepción no controlada y Visual Studio te suelta cuarenta líneas de stack trace en el regazo. Treinta y ocho viven en Microsoft.EntityFrameworkCore.* o en System.Private.CoreLib, una es un frame de máquina de estados asíncrona con un nombre tipo <<Main>$>b__0_0, y exactamente una apunta a código que escribiste tú. Tu trabajo es encontrar esa línea, entender por qué explotó y arreglar la causa real — no el síntoma.

Todos hemos pegado un trace en el buscador y recibido a cambio una sola pregunta de Stack Overflow de 2015, cero respuestas, y un único comentario que dice "¿al final lo resolviste?". Hay una forma mejor, y ahora vive dentro de Visual Studio: le pasas el trace a Claude y recibes un diagnóstico ordenado por probabilidad, atado a tu línea, con un arreglo que de verdad puedes razonar.

Por Qué Cuesta Tanto Leer un Stack Trace de .NET

Los stack traces no son difíciles por ser largos. Son difíciles porque el código moderno de .NET casi nunca corre en línea recta, y el trace refleja la maquinaria, no tu intención.

Desenrollado asíncrono. Un await compila a una máquina de estados. Cuando una excepción cruza un await, los frames que ves son llamadas a MoveNext() y ExecutionContext.Run, no la cadena de llamadas ordenada que escribiste. El método aparece como <AlgoAsync>d__4, y la línea que lógicamente lanzó puede estar tres await más arriba.
Excepciones internas (inner exceptions). El mensaje de arriba suele ser el menos útil. La causa real está anidada — un DbUpdateException envolviendo un SqliteException, o un TargetInvocationException envolviendo lo que de verdad importa. Si solo lees la primera línea, estás depurando el envoltorio.
AggregateException. Cualquier cosa con Task.WhenAll o paralelismo puede empaquetar varios fallos en uno. El mensaje externo dice "Se produjeron uno o más errores" — gracias, utilísimo.
Frames inlineados y de framework. El JIT hace inline de métodos pequeños, así que hay frames que desaparecen. Y los que quedan son en su mayoría internos de librerías que no puedes cambiar ni necesitas leer.

Un LLM es genuinamente bueno para esta tarea concreta. Ha visto estas formas de excepción miles de veces, sabe separar el ruido del framework de la señal y — esto es lo clave — cuando corre dentro de tu IDE, puede correlacionar el trace con el archivo y la línea reales.

Dos Formas de Meter a Claude Dentro de Visual Studio

No necesitas salir del IDE ni pegar nada en un navegador. Hay dos caminos sólidos, y cada uno sirve para un momento distinto.

1. Copilot Chat con un modelo Claude (dentro del IDE, conversacional)

Visual Studio 2022 (17.14+) trae GitHub Copilot con un selector de modelo. Haz clic en el badge de Copilot, abre el desplegable de modelos en la caja del chat y elige un modelo Claude — Sonnet para el diagnóstico rápido del día a día, Opus cuando el bug es realmente feo. A partir de ahí, cada respuesta de Copilot Chat la genera Claude.

Dos cosas hacen que este camino brille para depurar:

Cuando una excepción no controlada abre el Asistente de excepciones durante el debug, hay un enlace Preguntar a Copilot justo en ese diálogo. Con Claude seleccionado como modelo, ese análisis de un clic corre sobre Claude.
En la caja del chat puedes traer contexto real con referencias # — #Program.cs, #solution, o una selección resaltada — para que Claude lea tu código de verdad, no una paráfrasis.

Si prefieres usar tu propia clave de Anthropic en vez de los modelos de Copilot, el mismo selector tiene Manage Models → agregar Anthropic → pegar tu API key. Cómodo si ya pagas por acceso a la API.

2. Claude Code en la terminal integrada (agéntico)

Todavía no hay una extensión oficial de Claude Code para el Visual Studio completo, pero no la necesitas — Claude Code corre en cualquier terminal, incluida Ver → Terminal (Ctrl+) dentro de VS. Ejecutaclaude`, pega el trace y, como Claude Code puede leer todo el repositorio, abrirá él mismo el archivo culpable, seguirá la ruta de llamadas y propondrá el arreglo como un diff que apruebas o rechazas.

El intercambio es simple: Copilot Chat es más rápido para un "¿qué significa esto?", mientras que Claude Code es mejor cuando el arreglo toca varios archivos o quieres que reproduzca y verifique. Usa el que el bug se merezca.

Un Ejemplo Real: El Trace de EF Core Que Culpa a Quien No Es

Depuremos algo concreto. Este es un endpoint de minimal API en .NET 10 que devuelve el resumen de pedidos de un cliente. Se ve razonable, y compila sin quejas:

`csharp
// Program.cs — minimal API en .NET 10
using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext(o => o.UseSqlite("Data Source=shop.db"));

var app = builder.Build();

app.MapGet("/orders/{customerId:int}/summary", async (int customerId, ShopContext db) =>
{
// Disparamos ambas consultas "en paralelo" para ir rápido — ¿verdad?
var ordersTask = db.Orders.Where(o => o.CustomerId == customerId).ToListAsync();
var totalTask = db.Orders.Where(o => o.CustomerId == customerId).SumAsync(o => o.Total);

await Task.WhenAll(ordersTask, totalTask);

return Results.Ok(new { Orders = ordersTask.Result, Total = totalTask.Result });

});

app.Run();
`

Llamas al endpoint y lanza. Este es el trace que muestra Visual Studio (recortado a los frames que aparecen):

$>b__0_0(Int32 customerId, ShopContext db) in C:\src\Shop.Api\Program.cs:line 12
`

Cuatro de esos cinco frames son internos de EF Core. El único que es tuyo — Program.cs:line 12 — es la llamada a ToListAsync(), lo que hace parecer que ToListAsync es el villano. No lo es.

Cómo pasárselo a Claude bien

La calidad de la respuesta depende por completo de lo que pegues. Un mensaje de una línea te da una conjetura de una línea. Dale a Claude el panorama completo:

`text
.NET 10, EF Core 10, SQLite. Este endpoint lanza en cada request con carga normal
(no solo con concurrencia). Abajo van la excepción completa y el código del endpoint —
¿cuál es la causa raíz y cuál es el arreglo idiomático?

[pega la excepción COMPLETA con ex.ToString() — mensaje + todas las inner exceptions + trace]

[pega el handler del MapGet]
`

Tres cosas hacen que ese prompt sea bueno:

La excepción completa, no el titular. ex.ToString() incluye cada inner exception y el trace entero. En Copilot Chat, #Program.cs te trae el código solo.
El primer frame que es tuyo. Apunta a Claude a Program.cs:line 12 y al código a su alrededor. Los frames de framework son contexto; tu frame es la escena del crimen.
Las condiciones. "En cada request" vs "solo bajo carga" vs "intermitente" cambia el diagnóstico por completo. Di lo que observaste.

Lo que Claude te responde

En vez de "la línea 12 falló", obtienes el mecanismo real: el DbContext de EF Core no es thread-safe y no permite dos operaciones sobre la misma instancia a la vez. Task.WhenAll arranca la segunda consulta antes de que termine la primera, ambas sobre el mismo db inyectado, y el ConcurrencyDetector de EF lanza. El número de línea era una pista falsa — el bug es el patrón, no la llamada.

Y te da los dos arreglos, con el intercambio incluido:

csharp // Arreglo A — el más simple: ejecútalas en secuencia. Un contexto, una operación a la vez. var orders = await db.Orders.Where(o => o.CustomerId == customerId).ToListAsync(); var total = await db.Orders.Where(o => o.CustomerId == customerId).SumAsync(o => o.Total); return Results.Ok(new { Orders = orders, Total = total });

`csharp
// Arreglo B — paralelismo real: dale a cada consulta su PROPIO contexto vía factory.
builder.Services.AddDbContextFactory(o => o.UseSqlite("Data Source=shop.db"));

var ordersTask = ordersDb.Orders.Where(o => o.CustomerId == customerId).ToListAsync();
var totalTask  = totalDb.Orders.Where(o => o.CustomerId == customerId).SumAsync(o => o.Total);

await Task.WhenAll(ordersTask, totalTask);
return Results.Ok(new { Orders = await ordersTask, Total = await totalTask });

});
`

El Arreglo A es lo que quieres el 90% de las veces — dos consultas a SQLite son rápidas, y el paralelismo nunca valió el bug. El Arreglo B es la respuesta cuando las consultas son genuinamente lentas e independientes, porque IDbContextFactory<T> te entrega un contexto fresco y de vida corta por operación. Esa distinción — no el número de línea — es lo que de verdad te faltaba, y es el tipo de criterio que te da una buena explicación y no un resultado de búsqueda.

Un stack trace asíncrono de .NET tiene dos tipos de frames: los cuarenta que le pertenecen al runtime, y el que es culpa tuya. El trabajo de Claude es saltarse los cuarenta y explicarte el uno.

Verifica — No Confíes a Ciegas

Claude es un colega senior muy rápido que de vez en cuando se equivoca con toda seguridad. Trata su diagnóstico como una hipótesis fuerte, no como un veredicto:

Reproduce y confirma. Aplica el arreglo, vuelve a correr y comprueba que la excepción de verdad desapareció — idealmente bajo las mismas condiciones que la dispararon. En Visual Studio, pon un breakpoint en la línea corregida y observa el estado.
Pregunta el por qué, no solo el qué. "Explica por qué esto lo arregla" saca a la luz una causa raíz equivocada rapidísimo. Si el razonamiento no se sostiene, el arreglo probablemente tampoco.
Ojo con las causas plausibles pero falsas. Sobre todo con bugs intermitentes, Claude puede proponer una causa que encaja con el trace pero que no es la tuya. Haz que ordene los candidatos y te diga cómo distinguirlos.

El debugger sigue siendo el dueño del estado. Claude es dueño del significado. Cuando necesitas saber el valor real de una variable en el momento del crash, eso es una ventana de inspección y un breakpoint, no un prompt de chat.

Cuándo Recurrir a Claude — y Cuándo No

Recurre a él cuando:

El tipo o el mensaje de la excepción te resulta desconocido, o el trace es casi todo internos de framework.
La causa real está enterrada en inner exceptions o en un AggregateException.
Estás mirando frames asíncronos y no logras saber cuál de tus líneas es el origen.
Quieres el arreglo idiomático y sus intercambios, no solo un parche que quite el rojo.

No te molestes cuando:

Ya sabes la causa — un NullReferenceException en una línea que acabas de escribir no necesita un LLM.
Necesitas el valor en runtime de algo — usa el debugger.
El trace contiene secretos o datos de clientes. Las cadenas de conexión, los tokens y los datos personales aparecen en mensajes de excepción y payloads más seguido de lo que te gustaría. Límpialos antes de pegar, especialmente con un modelo en la nube.

La regla de oro: si de otro modo abrirías el navegador para buscar la excepción, mejor pregúntale a Claude — está en el IDE, puede leer tu código, y no te mandará a un hilo de foro muerto de 2015.

Puntos Clave

El trace muestra maquinaria, no intención — máquinas de estados asíncronas, inner exceptions y frames de framework entierran la única línea que es tuya. Leer traces es reconocimiento de patrones, que es justo donde ayuda un LLM.
Claude vive en Visual Studio de dos formas — elígelo en el selector de modelo de Copilot Chat para diagnóstico rápido y conversacional; corre Claude Code en la terminal integrada cuando el arreglo es agéntico y abarca varios archivos.
El contexto lo es todo — pega el ex.ToString() completo, apunta al primer frame que es tuyo y describe cuándo pasa. Un mensaje titular recibe una conjetura titular.
El número de línea suele ser una pista falsa — el ejemplo de EF Core lanza en ToListAsync, pero el bug es compartir un DbContext entre consultas paralelas. El valor está en la explicación, no en la ubicación.
Verifica, luego confía — reproduce el arreglo, pregunta por qué funciona y nunca pegues secretos. El debugger es dueño del estado; Claude, del significado.

RAG local en .NET: Chatea con tu Documentación (sin nube, sin API keys)

Juan Gómez — Fri, 10 Jul 2026 20:47:29 +0000

RAG local en .NET: Chatea con tu Documentación (sin nube, sin API keys)

Pregúntale a un modelo de lenguaje sobre la documentación de tu producto y míralo improvisar. Nunca leyó tus docs internas de la API, así que rellena los huecos con respuestas seguras, plausibles y completamente inventadas. Eso es una alucinación, y no es que el modelo sea tonto: es que le pediste algo para lo que jamás le diste el material.

RAG lo arregla. En vez de rezar para que el modelo memorizara tus docs, le entregas las páginas relevantes en el momento de la pregunta — como dejar que un estudiante haga un examen a libro abierto. En este tutorial construimos un pequeño sistema RAG en .NET 10 que responde preguntas sobre la documentación de un producto, y lo hacemos 100% local: sin nube, sin API keys, sin factura a fin de mes.

¿Qué es RAG, sin humo?

RAG significa Retrieval-Augmented Generation (Generación Aumentada por Recuperación). Quítale las siglas y quedan tres ideas simples:

Retrieval (recuperar) — encontrar los pedazos de tus docs que se relacionan con la pregunta.
Augmented (aumentar) — pegar esos pedazos al prompt.
Generation (generar) — dejar que el modelo escriba la respuesta usándolos.

Eso es todo. Lo ingenioso está en el primer paso: ¿cómo encuentras los pedazos relevantes? No basta con buscar palabras iguales, porque alguien puede preguntar "¿cómo inicio sesión?" mientras tu doc dice "autenticación". Palabras distintas, mismo significado.

El truco son los embeddings. Un embedding es simplemente una lista de números (un vector) que captura el significado de un texto. Los textos que significan cosas parecidas obtienen números parecidos — así "iniciar sesión" y "autenticación" quedan cerca, aunque no compartan ni una letra. Encuentra los vectores más cercanos al vector de la pregunta y habrás encontrado los docs relevantes. No es magia, es geometría.

Los tres pasos de RAG

Este es el pipeline completo, de principio a fin:

Ingesta (una sola vez, al inicio): parte los docs en trozos pequeños, convierte cada trozo en un embedding y guárdalos.
Recuperación (por cada pregunta): convierte la pregunta en un embedding y busca los trozos cuyos embeddings estén más cerca.
Aumento y generación (por cada pregunta): mete esos trozos en el prompt y pide al modelo que responda usándolos.

Los pasos 2 y 3 corren cada vez que alguien pregunta algo. El paso 1 corre una vez y se reutiliza para siempre (o hasta que cambien tus docs).

Lo que vamos a construir + Setup

Armaremos una app de consola que ingiere la documentación de un producto y luego responde preguntas sobre ella desde la terminal. Tres herramientas hacen el trabajo pesado:

Ollama corre los modelos de IA en tu máquina — uno para crear embeddings, otro para escribir respuestas.
SQLite guarda todo en un único archivo.
sqlite-vec, una extensión de SQLite, hace por nosotros la búsqueda de "los vectores más cercanos".

Tu laptop está a punto de tener un segundo empleo como mini data center de IA. El único costo es un ventilador un poco más caliente.

# 1. Crea el proyecto
dotnet new console -n OrbitDocsRag
cd OrbitDocsRag
dotnet add package Microsoft.Data.Sqlite

# 2. Instala Ollama desde https://ollama.com y descarga los dos modelos
ollama pull nomic-embed-text   # convierte texto en vectores de 768 números
ollama pull llama3.2           # escribe la respuesta final

# 3. Coloca la librería nativa de sqlite-vec junto a tu app.
#    Descarga vec0.dll (Windows) / vec0.so (Linux) / vec0.dylib (macOS)
#    desde https://github.com/asg017/sqlite-vec/releases y ponla en la
#    carpeta del proyecto para que aterrice en bin/ al compilar.

Ollama expone una API REST sencilla en http://localhost:11434. Hablaremos con ella usando un HttpClient pelado — sin SDK — para que veas que no hay nada escondido detrás de un wrapper. De verdad son solo un par de POST por HTTP.

Paso 1 — Partir los docs en trozos (chunking)

No puedes convertir un manual de 50 páginas en un solo vector — sería un promedio borroso de todo, inútil para cualquier cosa. Así que partimos cada documento en ventanas pequeñas y solapadas. Los trozos pequeños dan coincidencias precisas; el solapamiento evita que una idea que cae justo en el borde quede cortada por la mitad.

sealed record DocChunk(string Source, string Text);

static class Chunker
{
    public static IEnumerable<DocChunk> Split(
        string source, string text, int maxWords = 120, int overlap = 20)
    {
        var words = text.Split((char[]?)null, StringSplitOptions.RemoveEmptyEntries);

        for (var start = 0; start < words.Length; start += maxWords - overlap)
        {
            var end = Math.Min(start + maxWords, words.Length);
            yield return new DocChunk(source, string.Join(' ', words[start..end]));
            if (end == words.Length) break;
        }
    }
}

Cada trozo recuerda su Source (el archivo del que vino) para poder citarlo después. Desliza una ventana de 120 palabras avanzando de 100 en 100, y obtienes trozos solapados que conservan su contexto.

Paso 2 — Convertir texto en vectores (embeddings)

Aquí Ollama se gana el sueldo. Hacemos POST de un texto a /api/embed y recibimos un arreglo de 768 floats — el embedding.

using System.Net.Http.Json;
using System.Text.Json;

sealed class OllamaClient
{
    private static readonly JsonSerializerOptions Json = new(JsonSerializerDefaults.Web);
    private readonly HttpClient _http = new() { BaseAddress = new Uri("http://localhost:11434") };

    public async Task<float[]> EmbedAsync(string text)
    {
        var request = new { model = "nomic-embed-text", input = text };
        var response = await _http.PostAsJsonAsync("/api/embed", request, Json);
        response.EnsureSuccessStatusCode();

        var body = await response.Content.ReadFromJsonAsync<EmbedResponse>(Json);
        return body!.Embeddings[0];
    }

    private sealed record EmbedResponse(float[][] Embeddings);
}

Esa es toda la parte de "IA" de los embeddings — una llamada HTTP. El modelo lee tu texto y devuelve su significado como 768 números. Dos trozos sobre autenticación regresarán con dos arreglos muy parecidos.

Paso 3 — Guardar los vectores en SQLite

Ahora guardamos cada trozo y su embedding. sqlite-vec nos da una tabla virtual especial que sabe buscar vectores de forma nativa. Le decimos que los vectores son 768 floats y que queremos distancia coseno (ya llegamos a eso). Las columnas +source y +chunk viajan como texto plano para poder recuperar el texto original tras una búsqueda.

using Microsoft.Data.Sqlite;
using System.Text.Json;

sealed class VectorStore(string path) : IDisposable
{
    private readonly SqliteConnection _connection = new($"Data Source={path}");

    public void Initialize()
    {
        _connection.Open();
        _connection.LoadExtension("vec0"); // carga la librería nativa de sqlite-vec

        using var command = _connection.CreateCommand();
        command.CommandText = """
            CREATE VIRTUAL TABLE IF NOT EXISTS vec_chunks USING vec0(
                embedding float[768] distance_metric=cosine,
                +source text,
                +chunk text
            );
            """;
        command.ExecuteNonQuery();
    }

    public void Add(DocChunk chunk, float[] embedding)
    {
        using var command = _connection.CreateCommand();
        command.CommandText = """
            INSERT INTO vec_chunks(embedding, source, chunk)
            VALUES ($embedding, $source, $chunk);
            """;
        command.Parameters.AddWithValue("$embedding", JsonSerializer.Serialize(embedding));
        command.Parameters.AddWithValue("$source", chunk.Source);
        command.Parameters.AddWithValue("$chunk", chunk.Text);
        command.ExecuteNonQuery();
    }

    public void Dispose() => _connection.Dispose();
}

Guardamos el embedding como un string JSON tipo [0.12, -0.04, ...] — sqlite-vec lo interpreta sin problema.

¿Cómo funciona eso de "el más cercano"?

sqlite-vec hace la búsqueda en código nativo rápido, pero no hay ningún misterio adentro. "¿Qué tan parecidos son dos vectores?" se responde con similitud coseno, que son un puñado de líneas de C# plano:

static double CosineSimilarity(float[] a, float[] b)
{
    double dot = 0, magA = 0, magB = 0;
    for (var i = 0; i < a.Length; i++)
    {
        dot  += a[i] * b[i];
        magA += a[i] * a[i];
        magB += b[i] * b[i];
    }
    return dot / (Math.Sqrt(magA) * Math.Sqrt(magB));
}

El resultado va de 1.0 (significado idéntico) hasta 0 (sin relación). sqlite-vec reporta la distancia — básicamente 1 - similitud — así que más pequeño es más cercano. Por eso cada consulta de abajo termina en ORDER BY distance. Eso es toda la "búsqueda vectorial" de la que todos hablan: un producto punto y una raíz cuadrada.

Paso 4 — Recuperar los trozos relevantes

Por cada pregunta, convertimos la pregunta en embedding exactamente igual, y luego le pedimos a sqlite-vec los k trozos más cercanos. La palabra clave MATCH es la señal de sqlite-vec para ejecutar una búsqueda por vecinos más cercanos.

sealed record SearchHit(string Source, string Chunk, double Distance);

// (agrega este método a VectorStore)
public List<SearchHit> Search(float[] queryEmbedding, int k)
{
    using var command = _connection.CreateCommand();
    command.CommandText = """
        SELECT source, chunk, distance
        FROM vec_chunks
        WHERE embedding MATCH $query
        ORDER BY distance
        LIMIT $k;
        """;
    command.Parameters.AddWithValue("$query", JsonSerializer.Serialize(queryEmbedding));
    command.Parameters.AddWithValue("$k", k);

    var hits = new List<SearchHit>();
    using var reader = command.ExecuteReader();
    while (reader.Read())
        hits.Add(new SearchHit(reader.GetString(0), reader.GetString(1), reader.GetDouble(2)));

    return hits;
}

Le das el vector de la pregunta y recibes los tres trozos con mayor probabilidad de contener la respuesta — ordenados del más cercano al más lejano.

Paso 5 — Armar el prompt y generar la respuesta

El último paso es la recompensa. Cosemos los trozos recuperados dentro de un prompt con una instrucción estricta: responde solo con este contexto. Luego lo enviamos al modelo de chat vía /api/chat.

// (agrega este método a OllamaClient)
public async Task<string> ChatAsync(string prompt)
{
    var request = new
    {
        model = "llama3.2",
        messages = new[] { new { role = "user", content = prompt } },
        stream = false
    };
    var response = await _http.PostAsJsonAsync("/api/chat", request, Json);
    response.EnsureSuccessStatusCode();

    var body = await response.Content.ReadFromJsonAsync<ChatResponse>(Json);
    return body!.Message.Content;
}

// records anidados dentro de OllamaClient
private sealed record ChatResponse(ChatMessage Message);
private sealed record ChatMessage(string Role, string Content);

Y el prompt que lo une todo:

var context = string.Join("\n\n", hits.Select(h => $"[{h.Source}] {h.Chunk}"));

var prompt = $"""
    Answer the question using ONLY the context below.
    If the answer is not in the context, say "I don't know based on the docs."

    Context:
    {context}

    Question: {question}
    """;

Esa única instrucción — solo con este contexto — es lo que mata las alucinaciones. Sin nada en qué apoyarse, el modelo no inventará una respuesta con seguridad; admitirá que no sabe. Es la diferencia entre un estudiante que estudió y uno que improvisa frente a la clase. Y como cada trozo lleva su etiqueta [source.md], puedes mostrarle al usuario exactamente de dónde salió la respuesta.

El ejemplo completo

Este es el Program.cs de nivel superior. Trae tres "docs" diminutas embebidas para que puedas correrlo sin ningún archivo, pero cambia SampleDocs.All por una carpeta de .md reales y no cambia nada más. Mantén los tipos OllamaClient, VectorStore, Chunker, DocChunk y SearchHit de los pasos anteriores en el mismo proyecto (debajo del código de nivel superior, o en sus propios archivos) y compila tal cual.

using System.Net.Http.Json;
using System.Text.Json;
using Microsoft.Data.Sqlite;

var ollama = new OllamaClient();
using var store = new VectorStore("orbit-docs.db");
store.Initialize();

// --- Paso 1 + 2 + 3: ingesta de los docs (trocear -> embeber -> guardar) ---
foreach (var (source, text) in SampleDocs.All)
    foreach (var chunk in Chunker.Split(source, text))
    {
        var embedding = await ollama.EmbedAsync(chunk.Text);
        store.Add(chunk, embedding);
    }

Console.Write("Pregunta sobre la API de Orbit: ");
var question = Console.ReadLine() is { Length: > 0 } input ? input : "¿Cómo me autentico?";

// --- Paso 4: recuperar ---
var questionEmbedding = await ollama.EmbedAsync(question);
var hits = store.Search(questionEmbedding, k: 3);

// --- Paso 5: aumentar + generar ---
var context = string.Join("\n\n", hits.Select(h => $"[{h.Source}] {h.Chunk}"));
var prompt = $"""
    Answer the question using ONLY the context below.
    If the answer is not in the context, say "I don't know based on the docs."

    Context:
    {context}

    Question: {question}
    """;

var answer = await ollama.ChatAsync(prompt);

Console.WriteLine($"\n{answer}\n");
Console.WriteLine($"Fuentes: {string.Join(", ", hits.Select(h => h.Source).Distinct())}");

static class SampleDocs
{
    public static readonly Dictionary<string, string> All = new()
    {
        ["auth.md"] = """
            Authentication. The Orbit API uses API keys. Send your key in the
            Authorization header as 'Bearer <key>'. Keys never expire but can be
            revoked from the dashboard. Rate limits are 100 requests per minute.
            """,
        ["webhooks.md"] = """
            Webhooks. Orbit pushes events to your endpoint. Register a webhook URL
            in the dashboard. Every payload is signed with HMAC-SHA256; verify the
            X-Orbit-Signature header before trusting the body. Failed deliveries
            retry 5 times with exponential backoff.
            """,
        ["errors.md"] = """
            Error codes. Orbit returns standard HTTP status codes. A 429 means you
            hit the rate limit, so back off and retry. A 401 means your API key is
            missing or invalid. A 422 means the request body failed validation.
            """
    };
}

Córrelo, pregunta "¿cómo inicio sesión?" y, aunque esas palabras exactas no aparecen en ningún lado de los docs, el embedding de tu pregunta aterriza junto al trozo de autenticación — y el modelo responde con las instrucciones de la API key, citando auth.md. Eso es RAG funcionando.

Cuándo usar RAG — y cuándo no

RAG es la herramienta correcta cuando tu conocimiento es grande, privado o cambiante:

Usa RAG para docs de empresa, manuales de producto, tickets de soporte, una base de conocimiento — cualquier cosa que el modelo base nunca vio y que se actualiza seguido. ¿Docs nuevos? Solo los embebes. Sin reentrenar.
Sáltate RAG y pega todo en el prompt cuando el conocimiento completo cabe cómodamente en la ventana de contexto. Si son dos párrafos, la recuperación es matar moscas a cañonazos.
Recurre a fine-tuning cuando necesitas cambiar el estilo, tono o formato del modelo — no sus hechos. El fine-tuning enseña comportamiento; RAG aporta conocimiento. Resuelven problemas distintos, y muchos sistemas reales usan ambos.

Algunas limitaciones honestas a tener en cuenta: tus respuestas son tan buenas como tus trozos, así que un mal chunking significa mala recuperación. Las tablas y los números se embeben mal (su significado vive en la estructura, no en la prosa). Y si la respuesta simplemente no está en los docs, un sistema RAG bien instruido debería decirlo — lo cual es una virtud, no un defecto.

La regla de oro: si tendrías que copiar y pegar un documento en el chat para obtener una buena respuesta, ese es trabajo para RAG.

Puntos clave

RAG son tres pasos, no magia — recuperar los trozos relevantes, aumentar el prompt, generar la respuesta. Todo lo demás es detalle.
Los embeddings convierten significado en geometría — un texto parecido se vuelve un vector parecido, así encuentras docs relevantes aunque las palabras no coincidan.
La "búsqueda vectorial" es solo similitud coseno — un producto punto y una raíz cuadrada; sqlite-vec solo lo hace rápido, no misterioso.
Anclar al contexto mata las alucinaciones — decirle al modelo que responda solo con el contexto recuperado convierte el disparate seguro en un honesto "no sé", y te deja citar fuentes.
No necesitas la nube — Ollama más SQLite corren un pipeline RAG completo en tu laptop, con cero API keys y cero costo por token.

Build a Local RAG in .NET: Chat With Your Docs (No Cloud, No API Keys)

Juan Gómez — Fri, 10 Jul 2026 20:47:26 +0000

Build a Local RAG in .NET: Chat With Your Docs (No Cloud, No API Keys)

Ask a language model about your product's documentation and watch it improvise. It has never read your internal API docs, so it fills the gaps with confident, plausible, completely made-up answers. That is hallucination, and it is not the model being dumb — it is the model being asked a question it was never given the material to answer.

RAG fixes this. Instead of hoping the model memorized your docs, you hand it the relevant pages at question time — like letting a student take an open-book exam. In this tutorial we build a small RAG system in .NET 10 that answers questions about a product's documentation, and we do it 100% locally: no cloud, no API keys, no invoice at the end of the month.

What Is RAG, Without the Hype?

RAG stands for Retrieval-Augmented Generation. Strip away the acronym and it is three plain-English words:

Retrieval — find the pieces of your docs that relate to the question.
Augmented — glue those pieces onto the prompt.
Generation — let the model write the answer using them.

That's it. The clever part is step one: how do you find the relevant pieces? You can't just search for matching keywords, because someone might ask "how do I log in?" while your docs say "authentication." Different words, same meaning.

The trick is embeddings. An embedding is just a list of numbers (a vector) that captures the meaning of a piece of text. Texts that mean similar things get similar numbers — so "log in" and "authentication" land close together, even though they share no letters. Find the closest vectors to the question's vector, and you've found the relevant docs. No magic, just geometry.

The Three Steps of RAG

Here is the entire pipeline, start to finish:

Ingest (done once, up front): chop the docs into small chunks, turn each chunk into an embedding, and store them.
Retrieve (done per question): turn the question into an embedding, then find the chunks whose embeddings are closest to it.
Augment & generate (done per question): drop those chunks into the prompt and ask the model to answer using them.

Steps 2 and 3 run every time someone asks something. Step 1 runs once and gets reused forever (or until your docs change).

What We're Building + Setup

We'll build a console app that ingests a product's docs and then answers questions about them from the terminal. Three tools do the heavy lifting:

Ollama runs the AI models on your machine — one to create embeddings, one to write answers.
SQLite stores everything in a single file.
sqlite-vec, a SQLite extension, does the "find the closest vectors" search for us.

Your laptop is about to moonlight as a tiny AI data center. The only cost is a slightly warmer fan.

# 1. Create the project
dotnet new console -n OrbitDocsRag
cd OrbitDocsRag
dotnet add package Microsoft.Data.Sqlite

# 2. Install Ollama from https://ollama.com, then pull the two models
ollama pull nomic-embed-text   # turns text into 768-number vectors
ollama pull llama3.2           # writes the final answer

# 3. Drop the sqlite-vec native library next to your app.
#    Grab vec0.dll (Windows) / vec0.so (Linux) / vec0.dylib (macOS)
#    from https://github.com/asg017/sqlite-vec/releases and place it
#    in the project folder so it lands in bin/ at build time.

Ollama exposes a plain REST API at http://localhost:11434. We'll talk to it with a bare HttpClient — no SDK — so you can see there is nothing hiding behind a wrapper. It really is just a couple of HTTP POSTs.

Step 1 — Chop the Docs Into Chunks

You can't embed a whole 50-page manual as one vector — it would be a blurry average of everything, useful for nothing. So we split each document into small, overlapping windows. Small chunks give precise matches; the overlap makes sure an idea that straddles a boundary isn't cut in half.

sealed record DocChunk(string Source, string Text);

static class Chunker
{
    public static IEnumerable<DocChunk> Split(
        string source, string text, int maxWords = 120, int overlap = 20)
    {
        var words = text.Split((char[]?)null, StringSplitOptions.RemoveEmptyEntries);

        for (var start = 0; start < words.Length; start += maxWords - overlap)
        {
            var end = Math.Min(start + maxWords, words.Length);
            yield return new DocChunk(source, string.Join(' ', words[start..end]));
            if (end == words.Length) break;
        }
    }
}

Each chunk remembers its Source (the file it came from) so we can cite it later. Slide a 120-word window forward 100 words at a time, and you get overlapping chunks that keep their context.

Step 2 — Turn Text Into Vectors (Embeddings)

This is where Ollama earns its keep. We POST a string to /api/embed and get back an array of 768 floats — the embedding.

using System.Net.Http.Json;
using System.Text.Json;

sealed class OllamaClient
{
    private static readonly JsonSerializerOptions Json = new(JsonSerializerDefaults.Web);
    private readonly HttpClient _http = new() { BaseAddress = new Uri("http://localhost:11434") };

    public async Task<float[]> EmbedAsync(string text)
    {
        var request = new { model = "nomic-embed-text", input = text };
        var response = await _http.PostAsJsonAsync("/api/embed", request, Json);
        response.EnsureSuccessStatusCode();

        var body = await response.Content.ReadFromJsonAsync<EmbedResponse>(Json);
        return body!.Embeddings[0];
    }

    private sealed record EmbedResponse(float[][] Embeddings);
}

That's the whole "AI" part of embeddings — one HTTP call. The model reads your text and returns its meaning as 768 numbers. Two chunks about authentication will come back with two very similar arrays.

Step 3 — Store the Vectors in SQLite

Now we save each chunk and its embedding. sqlite-vec gives us a special virtual table that can search vectors natively. We tell it the vectors are 768 floats and that we want cosine distance (more on that in a second). The +source and +chunk columns ride along as plain text so we can read the original text back after a search.

using Microsoft.Data.Sqlite;
using System.Text.Json;

sealed class VectorStore(string path) : IDisposable
{
    private readonly SqliteConnection _connection = new($"Data Source={path}");

    public void Initialize()
    {
        _connection.Open();
        _connection.LoadExtension("vec0"); // loads the sqlite-vec native library

        using var command = _connection.CreateCommand();
        command.CommandText = """
            CREATE VIRTUAL TABLE IF NOT EXISTS vec_chunks USING vec0(
                embedding float[768] distance_metric=cosine,
                +source text,
                +chunk text
            );
            """;
        command.ExecuteNonQuery();
    }

    public void Add(DocChunk chunk, float[] embedding)
    {
        using var command = _connection.CreateCommand();
        command.CommandText = """
            INSERT INTO vec_chunks(embedding, source, chunk)
            VALUES ($embedding, $source, $chunk);
            """;
        command.Parameters.AddWithValue("$embedding", JsonSerializer.Serialize(embedding));
        command.Parameters.AddWithValue("$source", chunk.Source);
        command.Parameters.AddWithValue("$chunk", chunk.Text);
        command.ExecuteNonQuery();
    }

    public void Dispose() => _connection.Dispose();
}

We store the embedding as a JSON string like [0.12, -0.04, ...] — sqlite-vec happily parses that.

How does "closest" actually work?

sqlite-vec does the search in fast native code, but there's no mystery inside. "How similar are two vectors?" is answered by cosine similarity, which is a handful of lines of plain C#:

static double CosineSimilarity(float[] a, float[] b)
{
    double dot = 0, magA = 0, magB = 0;
    for (var i = 0; i < a.Length; i++)
    {
        dot  += a[i] * b[i];
        magA += a[i] * a[i];
        magB += b[i] * b[i];
    }
    return dot / (Math.Sqrt(magA) * Math.Sqrt(magB));
}

The result runs from 1.0 (identical meaning) down to 0 (unrelated). sqlite-vec reports the distance — basically 1 - similarity — so smaller is closer. That's why every query below ends with ORDER BY distance. That's the whole "vector search" everyone talks about: a dot product and a square root.

Step 4 — Retrieve the Relevant Chunks

Per question, we embed the question the exact same way, then ask sqlite-vec for the k nearest chunks. The MATCH keyword is sqlite-vec's signal to run a nearest-neighbor search.

sealed record SearchHit(string Source, string Chunk, double Distance);

// (add this method to VectorStore)
public List<SearchHit> Search(float[] queryEmbedding, int k)
{
    using var command = _connection.CreateCommand();
    command.CommandText = """
        SELECT source, chunk, distance
        FROM vec_chunks
        WHERE embedding MATCH $query
        ORDER BY distance
        LIMIT $k;
        """;
    command.Parameters.AddWithValue("$query", JsonSerializer.Serialize(queryEmbedding));
    command.Parameters.AddWithValue("$k", k);

    var hits = new List<SearchHit>();
    using var reader = command.ExecuteReader();
    while (reader.Read())
        hits.Add(new SearchHit(reader.GetString(0), reader.GetString(1), reader.GetDouble(2)));

    return hits;
}

Give it the question's vector, get back the three chunks most likely to contain the answer — ranked from closest to furthest.

Step 5 — Build the Prompt and Generate the Answer

The final step is the payoff. We stitch the retrieved chunks into a prompt with one strict instruction: answer only from this context. Then we send it to the chat model via /api/chat.

// (add this method to OllamaClient)
public async Task<string> ChatAsync(string prompt)
{
    var request = new
    {
        model = "llama3.2",
        messages = new[] { new { role = "user", content = prompt } },
        stream = false
    };
    var response = await _http.PostAsJsonAsync("/api/chat", request, Json);
    response.EnsureSuccessStatusCode();

    var body = await response.Content.ReadFromJsonAsync<ChatResponse>(Json);
    return body!.Message.Content;
}

// nested records inside OllamaClient
private sealed record ChatResponse(ChatMessage Message);
private sealed record ChatMessage(string Role, string Content);

And the prompt that ties it all together:

var context = string.Join("\n\n", hits.Select(h => $"[{h.Source}] {h.Chunk}"));

var prompt = $"""
    Answer the question using ONLY the context below.
    If the answer is not in the context, say "I don't know based on the docs."

    Context:
    {context}

    Question: {question}
    """;

That one instruction — only from this context — is what kills hallucinations. With nothing to lean on, the model won't confidently invent an answer; it'll admit it doesn't know. It's the difference between a student who studied and one improvising in front of the class. And because each chunk carries its [source.md] tag, you can show the user exactly where the answer came from.

The Full Example

Here's the top-level Program.cs. It ships with three tiny "docs" inline so you can run it without any files, but swap SampleDocs.All for a folder of real .md files and nothing else changes. Keep the OllamaClient, VectorStore, Chunker, DocChunk, and SearchHit types from the steps above in the same project (below the top-level code, or in their own files) and it compiles as-is.

using System.Net.Http.Json;
using System.Text.Json;
using Microsoft.Data.Sqlite;

var ollama = new OllamaClient();
using var store = new VectorStore("orbit-docs.db");
store.Initialize();

// --- Step 1 + 2 + 3: ingest the docs (chunk -> embed -> store) ---
foreach (var (source, text) in SampleDocs.All)
    foreach (var chunk in Chunker.Split(source, text))
    {
        var embedding = await ollama.EmbedAsync(chunk.Text);
        store.Add(chunk, embedding);
    }

Console.Write("Ask about the Orbit API: ");
var question = Console.ReadLine() is { Length: > 0 } input ? input : "How do I authenticate?";

// --- Step 4: retrieve ---
var questionEmbedding = await ollama.EmbedAsync(question);
var hits = store.Search(questionEmbedding, k: 3);

// --- Step 5: augment + generate ---
var context = string.Join("\n\n", hits.Select(h => $"[{h.Source}] {h.Chunk}"));
var prompt = $"""
    Answer the question using ONLY the context below.
    If the answer is not in the context, say "I don't know based on the docs."

    Context:
    {context}

    Question: {question}
    """;

var answer = await ollama.ChatAsync(prompt);

Console.WriteLine($"\n{answer}\n");
Console.WriteLine($"Sources: {string.Join(", ", hits.Select(h => h.Source).Distinct())}");

static class SampleDocs
{
    public static readonly Dictionary<string, string> All = new()
    {
        ["auth.md"] = """
            Authentication. The Orbit API uses API keys. Send your key in the
            Authorization header as 'Bearer <key>'. Keys never expire but can be
            revoked from the dashboard. Rate limits are 100 requests per minute.
            """,
        ["webhooks.md"] = """
            Webhooks. Orbit pushes events to your endpoint. Register a webhook URL
            in the dashboard. Every payload is signed with HMAC-SHA256; verify the
            X-Orbit-Signature header before trusting the body. Failed deliveries
            retry 5 times with exponential backoff.
            """,
        ["errors.md"] = """
            Error codes. Orbit returns standard HTTP status codes. A 429 means you
            hit the rate limit, so back off and retry. A 401 means your API key is
            missing or invalid. A 422 means the request body failed validation.
            """
    };
}

Run it, ask "how do I log in?", and even though those exact words appear nowhere in the docs, the embedding for your question lands next to the authentication chunk — and the model answers with the API-key instructions, citing auth.md. That's RAG working.

When to Use RAG — and When Not To

RAG is the right tool when your knowledge is large, private, or changing:

Use RAG for company docs, product manuals, support tickets, a knowledge base — anything the base model never saw and that updates often. New docs? Just embed them. No retraining.
Skip RAG and just paste it into the prompt when the whole knowledge fits comfortably in the context window. If it's two paragraphs, retrieval is overkill.
Reach for fine-tuning instead when you need to change the model's style, tone, or format — not its facts. Fine-tuning teaches behavior; RAG supplies knowledge. They solve different problems, and plenty of real systems use both.

A few honest limitations to keep in mind: your answers are only as good as your chunks, so bad chunking means bad retrieval. Tables and numbers embed poorly (their meaning lives in structure, not prose). And if the answer simply isn't in the docs, a well-instructed RAG system should say so — which is a feature, not a bug.

The rule of thumb: if you'd have to copy-paste a document into the chat to get a good answer, that's a job for RAG.

Key Takeaways

RAG is three steps, not magic — retrieve relevant chunks, augment the prompt, generate the answer. Everything else is detail.
Embeddings turn meaning into geometry — similar text becomes similar vectors, so you can find relevant docs even when the words don't match.
"Vector search" is just cosine similarity — a dot product and a square root; sqlite-vec only makes it fast, not mysterious.
Grounding kills hallucinations — telling the model to answer only from the retrieved context turns confident nonsense into honest "I don't know," and lets you cite sources.
You don't need the cloud — Ollama plus SQLite runs a complete RAG pipeline on your laptop, with zero API keys and zero per-token cost.

Claude Code for .NET Developers: From Zero to Productive in VS Code and Visual Studio

Juan Gómez — Mon, 15 Jun 2026 22:57:25 +0000

Claude Code for .NET Developers: From Zero to Productive in VS Code and Visual Studio

Here is the pattern that plays out constantly with AI coding tools: you try one, it blows your mind. You use it for a week, and it starts feeling random. Sometimes it's brilliant; sometimes it confidently suggests code from three framework versions ago. You stop trusting it, and it fades into the "cool but not practical" category.

The problem is not the model. The problem is that you are using a powerful tool without understanding how it works. Claude Code is different from a chat window, and once you understand its mechanics — how it discovers context, how you shape its behavior, how you extend it with custom commands — it becomes genuinely reliable for .NET work.

This article covers everything: installation, VS Code integration, the honest story about Visual Studio 2022 and 2026, CLAUDE.md (the most important file you are not writing yet), context management, Skills, and MCP. Whether you are new to AI tooling or already use it daily, there is something here for you.

What Is Claude Code, Exactly?

Claude Code is not a chatbot that happens to know about code. It is a CLI-first, agentic coding assistant built by Anthropic. The key distinction: it operates on your actual repository. It can read files, run commands, edit code, and chain multiple steps together without you narrating every move.

The mental model that helps most: Claude Code is a skilled contractor who just walked into your codebase. Give them the right context, and they can work independently. Give them nothing, and they will ask questions — or worse, make assumptions.

There are two surfaces you will use:

The CLI (claude) — runs in any terminal, works with any editor
The VS Code extension (anthropic.claude-code) — embeds the CLI experience directly into VS Code, with file awareness, selection sharing, and inline diffs

Both use the same model and the same context system. The extension is additive convenience on top of the CLI, not a separate product.

Installation and Setup

Prerequisites

You need Node.js 22 LTS or later. Check with:

node --version

Install Claude Code globally:

npm install -g @anthropic-ai/claude-code

Authenticate:

claude

The first run opens a browser for OAuth with your Anthropic account. After that, your credentials are stored locally and the CLI works offline-first (the model calls still go to Anthropic's API, of course).

VS Code Integration

Install the extension from the marketplace. The ID is anthropic.claude-code. You need VS Code 1.98 or later.

Once installed, a Claude icon appears in the activity bar. Open it, sign in, and you have a chat panel that is deeply aware of your open files, your current selection, and your workspace structure. You can also invoke it inline with Ctrl+Shift+C (Windows/Linux) or Cmd+Shift+C (Mac) to open a quick input without leaving your editor flow.

The extension does something important automatically: when you highlight code and ask a question, it attaches that selection as context. You do not have to copy-paste. This alone saves significant friction on large codebases.

If you use JetBrains Rider, there is also full Claude Code integration available through the JetBrains Marketplace. The experience is comparable to VS Code. Rider users are covered — you can follow this entire article and apply it directly.

Visual Studio 2022 and 2026: The Honest Story

Visual Studio has been the king of .NET IDEs for decades — it just has not heard of Claude yet.

As of June 2026, there is no official Claude Code extension for Visual Studio 2022 or 2026. GitHub Copilot has deep VS integration; Claude Code does not. This is not a temporary oversight — the extension model for Visual Studio is substantially different from VS Code, and Anthropic has focused on the VS Code surface.

The workaround is simple and it works well: use the integrated terminal.

Open it with View > Terminal (or Ctrl+\`). Then run:

bash claude

Claude Code starts in your repo's root directory. It reads everything — your .cs files, your .csproj, your appsettings.json, your CLAUDE.md. The terminal-based experience is the same CLI you would use anywhere. You lose the inline diff rendering and selection-sharing that the VS Code extension provides, but the model's capabilities are identical.

Practical tip: keep Visual Studio open for debugging, the designer, and refactoring tooling (where it is unmatched), and open VS Code or a terminal alongside it for Claude interactions. Many .NET developers already do this. It is not a compromise — it is using each tool for what it is best at.

CLAUDE.md — The Brain of the Operation

This is the most important section in the article.

Every time Claude Code starts in a directory, it performs a filesystem walk. It moves upward from the current working directory, looking for CLAUDE.md files. It also lazily loads CLAUDE.md files found in subdirectories as it encounters them during work. The result is a layered context system: a root CLAUDE.md for the whole repo, and optionally per-project or per-module files for specific concerns.

CLAUDE.md is not magic. It is just a Markdown file. But it is the file Claude reads before doing anything else. Think of it as your onboarding document for a contractor who starts fresh every session.

What Claude Does NOT Know Without CLAUDE.md

Without any instruction file, Claude Code will:

Guess your build system from file structure
Assume generic conventions
Ask clarifying questions repeatedly
Make mistakes that a three-minute onboarding would prevent

With a good CLAUDE.md, Claude knows your exact dotnet commands, your test runner, your architecture decisions, your naming conventions, and any constraints specific to your project. It stops guessing and starts working.

Discovery in Visual Studio: A Common Gotcha

CLAUDE.md lives at the root of your repository — the same directory as your .sln file. Visual Studio's Solution Explorer shows files based on what is referenced in .csproj or .sln files. Since CLAUDE.md is not referenced by either, it will not appear in Solution Explorer.

This trips people up. They create the file, it does not show up in VS, they assume something is wrong. Nothing is wrong. Claude loads it perfectly. Open it directly in VS Code or a plain text editor to edit it.

To verify what Claude has loaded, run:

plaintext /memory

This lists all context files currently active in the session. If CLAUDE.md is loaded, it appears here. This is your ground truth.

A Practical CLAUDE.md for a .NET Project

Here is an example for a realistic ASP.NET Core project:

`markdown

OrderService

ASP.NET Core 10 minimal API backed by PostgreSQL via EF Core 10.
Authentication: JWT with ASP.NET Core Identity.
Deployed to Azure Container Apps via GitHub Actions.

Build

`bash dotnet build OrderService.sln `

Tests

`bash

Run all tests

dotnet test OrderService.sln

Run only unit tests

dotnet test tests/OrderService.UnitTests/

Run with coverage

dotnet test OrderService.sln --collect:"XPlat Code Coverage"
`

Architecture

src/OrderService.Api/ — minimal API endpoints, no business logic here
src/OrderService.Domain/ — domain models, value objects, interfaces
src/OrderService.Application/ — CQRS handlers (MediatR), validators (FluentValidation)
src/OrderService.Infrastructure/ — EF Core, repositories, external HTTP clients
tests/OrderService.UnitTests/ — xUnit, Moq, domain and application layer only
tests/OrderService.IntegrationTests/ — xUnit, Testcontainers, full API stack

Conventions

Use record types for immutable domain models and DTOs
Use C# 14 field keyword instead of explicit backing fields where applicable
All nullable reference types enabled; annotate accordingly
No var — use explicit types everywhere
Async all the way down; no .Result or .Wait()
Repository interfaces in Domain layer; implementations in Infrastructure
Endpoint classes in Features/ folders grouped by domain concept (vertical slice)

EF Core

Migrations in src/OrderService.Infrastructure/Migrations/
Add migration: dotnet ef migrations add <Name> --project src/OrderService.Infrastructure --startup-project src/OrderService.Api
Apply: dotnet ef database update --project src/OrderService.Infrastructure --startup-project src/OrderService.Api

Do Not

Do not add business logic to endpoint handlers
Do not use dynamic or object as return types
Do not skip FluentValidation for command/query inputs
Do not add new NuGet packages without noting them here `plaintext

This file takes about fifteen minutes to write and saves hours of back-and-forth over the lifetime of a project. The investment is obvious once you have it.

Generating a Starter CLAUDE.md

If you are not starting from scratch, Claude Code can inspect your repo and generate a first draft:

/initplaintext

This reads your solution structure, existing documentation, and common patterns, then writes a CLAUDE.md that reflects what it found. Treat the output as a starting point — review it, correct anything wrong, and add the domain knowledge Claude cannot infer (architecture decisions, team conventions, known pitfalls).

Giving Claude Context

Even with a great CLAUDE.md, you will often need to point Claude at specific files during a conversation. The @ mention syntax does this precisely.

File and Directory Mentions

@Program.cscsharp

Attaches the full content of Program.cs to the current message.

@src/OrderService.Application/plaintext

Attaches a directory listing. Claude will then read specific files from it as needed, rather than loading everything upfront.

@appsettings.json#1-20plaintext

Attaches only lines 1 through 20. Useful when you care about a specific section of a large config file and do not want to burn context on the rest.

VS Code Selection Sharing

When you use the VS Code extension, any code you highlight in the editor is automatically shared when you open the Claude panel. You do not need @ mentions for your active selection — it is already there. This makes "explain this method" or "what does this LINQ query do" workflows completely frictionless.

Managing Long Contexts

Long sessions accumulate context. After several hours of work, Claude's context window fills with earlier conversation turns that are no longer relevant. When responses start feeling less sharp, run:

/compactplaintext

This summarizes the conversation history into a compressed form, freeing up context space without losing the thread of what you have been working on. Think of it as telling the contractor to forget the small talk and remember only the decisions.

Skills — Custom Commands for Your Workflow

Skills are reusable, invocable commands that extend Claude Code's default behavior. They live as Markdown files and you invoke them with a / prefix, just like built-in commands. There are two scopes:

Personal skills — stored in ~/.claude/skills/<skill-name>/SKILL.md. Available in every project on your machine.
Project skills — stored in .claude/skills/<skill-name>/SKILL.md in your repo root. Checked into source control, shared with the team.

A skill file is a Markdown document that tells Claude what to do when invoked. It can include steps, decision logic, expected outputs, and even inline prompts.

Here are three practical examples for .NET development.

Skill: `/dotnet-test`

File: .claude/skills/dotnet-test/SKILL.md

`markdown

dotnet-test

Run the test suite for this project and summarize the results.

Steps

Run dotnet test using the command from CLAUDE.md (check the "Tests" section).
Parse the output for failed tests.
For each failure:
- Show the test name
- Show the failure message
- Show the stack trace trimmed to the first 5 lines
If all tests pass, confirm with a short success message.
If build errors prevent tests from running, show the build errors instead.

Output Format

Group failures by project. Keep the summary concise — one paragraph max,
followed by a numbered list of failures if any exist.
`

Invoke with /dotnet-test. Claude runs your test command, reads the output, and gives you a clean summary instead of a wall of terminal text.

Skill: `/csharp-review`

File: .claude/skills/csharp-review/SKILL.md

`markdown

csharp-review

Review the provided C# code for modern idiom usage and correctness.

What to Check

Records: Are mutable classes used where record or record struct would be more appropriate?
Init-only properties: Are setters used where init would suffice?
Pattern matching: Are if/switch chains that could use switch expressions or positional patterns?
Nullable annotations: Are reference types properly annotated? Any ! suppressors hiding problems?
Primary constructors: Could a class use C# 12+ primary constructor syntax?
field keyword: Are there explicit backing fields that C# 14's field keyword could eliminate?
Async: Any .Result, .Wait(), or async void outside of event handlers?
LINQ: Any imperative loops that would read more clearly as LINQ?

Output Format

List each finding as:

[Category] Description of the issue
Suggested rewrite (code block, 10 lines max)

End with a one-sentence overall assessment.
`

Invoke with /csharp-review while a file is open (or with @filename if using the CLI). You get actionable, .NET-specific feedback rather than generic suggestions.

Skill: `/ef-migrate`

File: .claude/skills/ef-migrate/SKILL.md

`markdown

ef-migrate

Guide through EF Core migration management for this project.

Steps

Run the dotnet ef migrations list command from CLAUDE.md to show existing migrations. Use the correct --project and --startup-project flags from CLAUDE.md.
Show the migration list, noting which have been applied (indicated by [applied]).
Ask the user: "Do you want to add a new migration, or apply pending ones?"
If adding a migration:
- Ask for the migration name (PascalCase, descriptive, e.g., AddOrderStatusIndex)
- Run dotnet ef migrations add <Name> with correct flags
- Show which files were created
- Ask if they want to review the generated migration before applying
If applying pending migrations:
- Confirm the number of pending migrations
- Run dotnet ef database update with correct flags
- Report success or errors

Safety Note

Always mention that migrations modify the database schema. Remind the user to review
generated migrations before applying to staging or production environments.
`

This skill turns what is normally a multi-step, flag-heavy CLI workflow into a guided conversation. It uses the migration commands already defined in your CLAUDE.md, so it adapts to each project automatically.

MCP — Connecting External Tools

Model Context Protocol (MCP) is a standard that lets Claude connect to external data sources and tools beyond your local filesystem. Where Skills extend what Claude does, MCP extends what Claude can see.

A few examples relevant to .NET teams:

GitHub MCP — Claude can read PR diffs, check CI status, and leave review comments directly, without you copy-pasting GitHub URLs into the chat
Azure DevOps MCP — Claude can read your current sprint, query work items, and understand the backlog when you ask it to help prioritize or plan
Database MCP — Claude can query your local or dev database schema to inform code generation, without you having to paste CREATE TABLE statements

MCP servers are configured in your Claude Code settings and are available across all sessions. For .NET teams working in Azure DevOps or GitHub, setting up the corresponding MCP server once pays dividends on every PR review and sprint planning task after that.

VS Code vs Visual Studio: An Honest Comparison

Both IDEs are legitimate for .NET work. Here is where each one stands with Claude Code:

Feature	VS Code + Claude Extension	Visual Studio 2022/2026 + Terminal
Claude Code integration	Native extension, inline diffs, selection sharing	Terminal only, CLI-based
Debugging experience	Good (but not VS-level)	Best in class for .NET
CLAUDE.md support	Full	Full (file not shown in Solution Explorer)
Skills / MCP	Full	Full (terminal invocation)
Designer tools (WinForms, WPF)	Limited	Full
Refactoring tools	Good	Excellent (ReSharper-level built-in)
Hot Reload / Edit and Continue	Good	Best in class
Extension ecosystem	Vast	.NET-focused, deep OS integration
Cost	Free	Community free; Pro/Enterprise paid

The pragmatic answer for most .NET developers: use both. VS Code for AI-assisted coding, exploration, and file editing; Visual Studio for debugging sessions, UI designers, and deep refactoring. They open the same project files and there is no conflict. Many developers keep both open simultaneously without issue.

If you have to pick one: pure backend services (ASP.NET Core APIs, worker services, console apps) work well with VS Code as your primary. Anything with Windows Forms, WPF, or complex debugger needs warrants Visual Studio as primary with Claude Code in the terminal.

Key Takeaways

CLAUDE.md is not optional — it is the difference between an AI that guesses and one that knows your codebase. Write it, commit it, keep it current. Run /init to generate a starting point from your existing repo.
Visual Studio is fully usable — the lack of a native extension is a real limitation, but View > Terminal and the claude CLI give you full Claude Code functionality. The file-awareness and Skills system work identically.
Context is everything — use @ mentions to target specific files, use line ranges to stay precise, and use /compact when sessions get long. Precision in context leads to precision in output.
Skills are multipliers — a fifteen-minute investment writing a project skill pays back immediately. Codify your team's review criteria, your test workflow, your migration process. Claude Code executes them consistently every time.
The model is not random — your context is — when Claude gives you a bad answer, the fix is almost always better context: a clearer CLAUDE.md, a more specific @ mention, or a well-written skill. Understanding the context system turns a frustrating tool into a reliable one.

The architecture is simple once you see it: CLAUDE.md tells Claude who you are and how your project works, @ mentions tell Claude what to look at right now, and Skills tell Claude how to handle your recurring tasks. Stack those three things on top of a capable model and the "random magic" feeling goes away entirely. What you get instead is a coding assistant that behaves like someone who has actually read the codebase.

Which, thanks to CLAUDE.md, it has.

Claude Code para desarrolladores .NET: De cero a productivo en VS Code y Visual Studio

Juan Gómez — Mon, 15 Jun 2026 22:57:12 +0000

Claude Code para desarrolladores .NET: De cero a productivo en VS Code y Visual Studio

Las herramientas de IA se sienten mágicas los primeros días. Le preguntas algo, te responde bien, y piensas: "esto va a cambiar todo". Luego pasan unas semanas, el contexto se confunde, las respuestas se vuelven genéricas, y empiezas a sentir que estás teniendo una conversación con alguien que tiene amnesia selectiva.

El problema no es la IA. El problema es que nadie te explicó cómo funciona realmente.

Este artículo desmitifica Claude Code para desarrolladores .NET. No es un tutorial de "mira qué cool es esto" — es una guía práctica de cómo funciona, por qué funciona así, y cómo sacarle el máximo provecho en proyectos C# reales, tanto en VS Code como en Visual Studio 2022/2026.

Qué es Claude Code (y qué no es)

Claude Code no es una ventana de chat glorificada. Es una CLI (interfaz de línea de comandos) que corre directamente en tu terminal y tiene acceso real a tu sistema de archivos, puede ejecutar comandos, leer y editar archivos, y mantener contexto sobre tu proyecto.

La diferencia con "preguntarle a Claude en el navegador" es enorme:

En el navegador, pegas código manualmente, pierdes contexto entre sesiones, y Claude no sabe nada de tu proyecto más allá de lo que tú le dices.
Con Claude Code, Claude vive en tu repositorio. Lee archivos, ejecuta dotnet build, corre tus tests, y entiende la arquitectura de tu solución.

Además de la CLI, existe una extensión para VS Code que integra Claude Code directamente en el editor — con contexto automático de lo que tienes abierto y seleccionado. Para Visual Studio, la historia es diferente (y la contaremos honestamente más adelante).

Instalación y setup

Prerrequisitos

Node.js 22 LTS o superior
Una cuenta en claude.ai con acceso a Claude Code

Instalar la CLI

npm install -g @anthropic-ai/claude-code

Verifica la instalación:

claude --version

Para iniciar una sesión interactiva en tu proyecto, navega al directorio raíz y ejecuta:

claude

VS Code — integración completa

Instala la extensión oficial desde el Marketplace:

Nombre: Claude Code
ID: anthropic.claude-code
Requiere VS Code 1.98 o superior

Una vez instalada, Claude Code aparece en la barra lateral. La integración es profunda: cuando tienes un archivo abierto o código seleccionado, Claude lo recibe automáticamente como contexto. No necesitas copiar y pegar nada.

JetBrains Rider también cuenta con integración completa a través de su plugin oficial — si tu equipo usa Rider, el workflow es muy similar al de VS Code.

Visual Studio 2022/2026 — la verdad sin rodeos

Visual Studio ha sido el rey del desarrollo .NET por décadas. Simplemente aún no se ha enterado de que existe Claude.

A junio de 2026, no existe una extensión oficial de Claude Code para Visual Studio. Punto. No hay workaround mágico que cambie eso.

Lo que sí funciona, y funciona bien, es usar la terminal integrada de Visual Studio:

Ve a Ver > Terminal (o Ctrl+\, Ctrl+`)
Navega al directorio raíz de tu solución (normalmente ya estás ahí)
Ejecuta claude

Claude lee tu repositorio exactamente igual que en VS Code. La diferencia es que no tienes el contexto visual automático — tendrás que mencionar archivos explícitamente con @ (lo veremos en detalle más adelante). Para muchas tareas de refactoring, generación de código y revisión de arquitectura, la terminal es más que suficiente.

Muchos desarrolladores .NET tienen ambos IDEs abiertos en paralelo: Visual Studio para debugging avanzado, diseñadores de formularios, y herramientas de profiling; VS Code para trabajar con Claude Code.

CLAUDE.md — el cerebro de la operación

Aquí está el insight más importante del artículo, así que léelo despacio.

Claude Code no funciona como un chatbot con memoria persistente. Cada vez que inicias una sesión, parte de cero. Entonces, ¿cómo "conoce" tu proyecto? A través de un archivo llamado CLAUDE.md.

Cómo Claude descubre CLAUDE.md

Cuando ejecutas claude desde un directorio, Claude realiza un recorrido del filesystem hacia arriba desde tu directorio de trabajo actual (CWD), buscando archivos CLAUDE.md. Además, carga CLAUDE.md de los subdirectorios de forma lazy a medida que accede a ellos.

Esto significa dos cosas importantes:

No está basado en archivos de proyecto — Claude no lee tu .csproj para descubrir CLAUDE.md. Lo descubre por ubicación en el filesystem. Si tu CLAUDE.md está en la raíz del repo y ejecutas claude desde ahí, se carga. Si lo ejecutas desde un subdirectorio, también lo cargará (porque sube hacia arriba).
En Visual Studio, CLAUDE.md no aparece en el Explorador de Soluciones — porque no está referenciado en ningún .csproj. Pero Claude sí lo carga. No necesitas agregarlo al proyecto. De hecho, es mejor que no lo hagas — es un archivo de contexto para la IA, no un recurso de tu aplicación.

Verificar qué está cargado

Puedes verificar en cualquier momento qué archivos CLAUDE.md tiene cargados Claude con el comando:

/memory

Esto muestra el contenido actual de memoria, incluyendo todos los CLAUDE.md activos en la sesión.

Generar un CLAUDE.md inicial

Si tu proyecto no tiene CLAUDE.md, Claude puede generarlo leyendo el repo:

/init

Esto analiza tu código, estructura de carpetas, y archivos de configuración, y produce un CLAUDE.md base que puedes refinar.

Ejemplo práctico: CLAUDE.md para un proyecto .NET

Aquí un ejemplo completo y realista para una API de e-commerce en .NET 10:

# ECommerceApi — Contexto para Claude Code

## Descripción del proyecto
API REST para gestión de catálogo y órdenes de compra.
Stack: .NET 10, C# 14, Entity Framework Core 9, PostgreSQL, MassTransit (RabbitMQ).
Arquitectura: Clean Architecture con CQRS via MediatR.

## Comandos esenciales

### Build y tests
dotnet build ECommerceApi.sln
dotnet test ECommerceApi.sln --logger "console;verbosity=normal"
dotnet test --filter "Category=Unit"
dotnet test --filter "Category=Integration"

### Migraciones EF Core
cd src/ECommerceApi.Infrastructure
dotnet ef migrations add <NombreMigracion> --startup-project ../ECommerceApi.Api
dotnet ef database update --startup-project ../ECommerceApi.Api

### Ejecución local
cd src/ECommerceApi.Api
dotnet run

## Estructura del proyecto
src/
  ECommerceApi.Api/           # Controllers, middleware, DI setup
  ECommerceApi.Application/   # Commands, queries, DTOs, validators
  ECommerceApi.Domain/        # Entities, value objects, domain events
  ECommerceApi.Infrastructure/ # EF Core, repositories, external services
tests/
  ECommerceApi.UnitTests/
  ECommerceApi.IntegrationTests/

## Convenciones de código
- Usa records para DTOs y value objects
- Usa init-only properties en domain entities cuando sea posible
- Pattern matching exhaustivo en switches sobre discriminated unions
- Nullable reference types habilitados — sin supresiones con !
- No uses var — tipado explícito siempre
- Nombres en inglés para código, comentarios pueden ser en español

## Decisiones de arquitectura importantes
- Los controllers SOLO llaman a MediatR.Send() — lógica cero en controllers
- Validaciones con FluentValidation en el pipeline de MediatR (no en controllers)
- Los domain events se despachan DESPUÉS de SaveChanges (outbox pattern)
- Los integration tests levantan PostgreSQL en Docker via Testcontainers

## Lo que NO hacer
- No agregar lógica de negocio en Infrastructure
- No inyectar DbContext directamente en Application — solo via repositorios
- No usar AutoMapper — mappings explícitos con métodos ToDto() / ToDomain()

Este archivo transforma a Claude de "asistente genérico de C#" a "colega que conoce tu proyecto". La diferencia en calidad de respuestas es notable.

Dando contexto a Claude

Tener un buen CLAUDE.md es el 50% del trabajo. El otro 50% es saber cómo dar contexto durante la sesión.

Menciones con @

La sintaxis @ te permite referenciar archivos y directorios específicos:

@Program.cs                    # Archivo completo
@src/Application/              # Directorio entero
@appsettings.json#1-20         # Líneas 1 a 20 del archivo
@src/Domain/Entities/Order.cs  # Archivo en ruta relativa

Ejemplos de uso en conversación:

Revisa @src/Application/Orders/Commands/CreateOrderCommand.cs
y dime si hay algo que mejorar con los nuevos features de C# 14.

Tengo un bug en @src/Infrastructure/Repositories/OrderRepository.cs#45-80.
El método GetPendingOrders() devuelve órdenes canceladas. ¿Ves el problema?

Contexto automático en VS Code

En VS Code con la extensión instalada, el archivo que tienes abierto en el editor activo se comparte automáticamente como contexto. Si seleccionas un bloque de código, solo ese bloque se incluye. Esto elimina mucho del trabajo manual de menciones @.

En Visual Studio (terminal), necesitas ser explícito con @ — lo cual en realidad te obliga a ser más preciso sobre qué quieres mostrarle a Claude, lo cual no es necesariamente malo.

Gestionar el contexto largo con /compact

Las sesiones largas tienen un límite de tokens. Cuando el contexto se alarga demasiado, Claude puede empezar a "olvidar" cosas del inicio de la conversación.

El comando /compact resume el historial de la sesión actual, preservando los puntos clave pero reduciendo el tamaño del contexto:

/compact

Úsalo proactivamente cuando llevas un rato en la misma sesión, antes de llegar al límite. Es como hacer un checkpoint.

Skills — comandos personalizados para tu flujo

Los Skills son la característica más poderosa de Claude Code para equipos y proyectos recurrentes. Un Skill es esencialmente un comando personalizado que encapsula un flujo de trabajo completo.

Dónde viven los Skills

Hay dos ubicaciones:

Ubicación	Alcance	Ruta
Personal	Solo tú, todos tus proyectos	`~/.claude/skills/<nombre>/SKILL.md`
Proyecto	Todo el equipo, este repo	`.claude/skills/<nombre>/SKILL.md`

Los Skills de proyecto se versiona junto al código — cuando alguien hace git clone, obtiene los Skills también. Ideal para workflows específicos del equipo.

Cómo invocar un Skill

Simplemente escribe /nombre-del-skill en Claude Code:

/dotnet-test
/csharp-review
/ef-migrate

Claude lee el archivo SKILL.md correspondiente y ejecuta el flujo definido en él.

Ejemplo 1: `/dotnet-test`

Crea el archivo .claude/skills/dotnet-test/SKILL.md:

# dotnet-test

Ejecuta la suite de tests del proyecto y presenta los resultados de forma clara.

## Pasos

1. Ejecuta `dotnet test ECommerceApi.sln --logger "console;verbosity=normal"`
2. Si hay fallos, muestra SOLO los tests fallidos con:
   - Nombre completo del test
   - El mensaje de error
   - La línea del código donde falló
3. Si todos pasan, confirma con un resumen: total de tests, tiempo de ejecución
4. Si hay errores de compilación, muéstralos primero antes de hablar de tests

## Notas
- No muestres los tests que pasaron a menos que el usuario lo pida
- Si el build falla, no intentes interpretar qué tests fallaron

Ejemplo 2: `/csharp-review`

Crea .claude/skills/csharp-review/SKILL.md:

# csharp-review

Revisa código C# buscando oportunidades de modernización con C# 14 / .NET 10.

## Qué revisar

### Records y tipos de valor
- ¿Se puede reemplazar una clase inmutable con un record?
- ¿Los DTOs usan record en vez de class?
- ¿Se usan init-only properties donde corresponde?

### Pattern matching
- ¿Hay cadenas de if/else que se pueden reemplazar con switch expressions?
- ¿Los switches son exhaustivos sobre discriminated unions?
- ¿Se usa list patterns donde aplica?

### Nullable reference types
- ¿Hay supresiones con ! sin justificación?
- ¿Los parámetros nullable están correctamente anotados?

### field keyword (C# 14)
- ¿Hay propiedades con backing fields explícitos que se pueden simplificar con field?

### Async/await
- ¿Hay .Result o .Wait() que deberían ser await?
- ¿Se usa ConfigureAwait correctamente en librerías?

## Formato de respuesta
Para cada issue encontrado:
- Código original
- Código mejorado
- Una línea explicando por qué es mejor

No reportes lo que ya está bien — solo oportunidades de mejora.

Ejemplo 3: `/ef-migrate`

Crea .claude/skills/ef-migrate/SKILL.md:

# ef-migrate

Guía para agregar una migración de Entity Framework Core al proyecto.

## Pasos

1. Ejecuta `dotnet ef migrations list --project src/ECommerceApi.Infrastructure --startup-project src/ECommerceApi.Api`
   para mostrar las migraciones existentes

2. Pregunta al usuario:
   - ¿Qué cambio hiciste en el modelo de dominio?
   - ¿Qué nombre quieres para la migración? (sugerencia: usa PascalCase descriptivo, ej: AddOrderShippingAddress)

3. Ejecuta:
   `dotnet ef migrations add <NombreMigracion> --project src/ECommerceApi.Infrastructure --startup-project src/ECommerceApi.Api`

4. Lee el archivo de migración generado y verifica:
   - Que el Up() tiene el cambio esperado
   - Que el Down() revierte correctamente
   - Que no hay columnas `nvarchar(max)` donde debería haber un tamaño específico

5. Si el usuario quiere aplicar la migración:
   `dotnet ef database update --project src/ECommerceApi.Infrastructure --startup-project src/ECommerceApi.Api`

## Notas
- Nunca ejecutes database update en producción desde aquí — solo desarrollo local
- Si hay conflictos de migración, muestra el error completo antes de sugerir soluciones

Estos tres Skills solos ya justifican el setup. Imagina tener un equipo de 10 personas donde todos invocan /csharp-review y obtienen el mismo estándar de revisión.

MCP — conectando herramientas externas

MCP (Model Context Protocol) es el mecanismo que permite a Claude Code conectarse con servicios externos como si fueran herramientas nativas.

En términos simples: un servidor MCP expone capacidades (leer PRs, consultar tickets, buscar documentación) y Claude puede usarlas durante la sesión.

Dos ejemplos relevantes para equipos .NET:

GitHub MCP — Claude puede leer los PRs abiertos del repo, ver los comentarios de revisión, y ayudarte a resolverlos sin que copies nada manualmente:

¿Qué cambios pendientes tengo en el PR #247?

Azure DevOps MCP — Claude puede ver el contexto del sprint actual, las user stories asignadas, y entender qué estás construyendo sin que tengas que explicarlo:

¿Cuáles son los criterios de aceptación de la historia US-1089?

Los servidores MCP se configuran en ~/.claude/mcp.json o .claude/mcp.json a nivel de proyecto. La documentación oficial de Claude Code tiene la lista de servidores MCP disponibles y cómo configurarlos.

Cuándo usar VS Code vs Visual Studio

La pregunta que todo desarrollador .NET acaba haciendo. La respuesta honesta:

Criterio	VS Code + Claude Code	Visual Studio 2022/2026
Integración con Claude Code	Completa — contexto automático, extensión nativa	Funcional — terminal integrada, sin extensión
Debugging de aplicaciones .NET	Bueno (con extensión C#)	Excelente — el mejor de la industria
IntelliSense y refactoring	Bueno	Excepcional — Roslyn completo
Diseñadores visuales (WinForms, WPF, MAUI)	No disponible	Completos
Profiling y diagnósticos	Limitado	Herramientas de clase mundial
Startup y rendimiento del IDE	Rápido	Lento en proyectos grandes
Desarrollo multiplataforma	Ideal	Limitado
Trabajo con soluciones grandes (50+ proyectos)	Puede ser lento	Optimizado
Skills y workflows de equipo	Integración nativa	Via terminal

Recomendación práctica: No elijas uno. Úsalos en paralelo.

Visual Studio sigue siendo insustituible para debugging pesado, profiling de memoria, y diseñadores de UI de escritorio. VS Code con Claude Code es donde vas a escribir código más rápido, refactorizar más limpio, y entender más fácil código ajeno.

Muchos equipos .NET han adoptado el siguiente flujo: VS Code para el día a día con Claude Code activo, Visual Studio cuando necesitan el debugger avanzado o las herramientas de diagnóstico. Los dos conviven perfectamente apuntando al mismo proyecto.

Puntos clave

CLAUDE.md es tu punto de partida — sin él, Claude no conoce tu proyecto. Con él, se convierte en un colaborador que entiende tu arquitectura, tus convenciones y tus decisiones técnicas. Ejecuta /init para generarlo y refínalo con el tiempo.
La integración de VS Code es completa; Visual Studio usa la terminal — en VS Code, la extensión anthropic.claude-code (requiere 1.98+) te da contexto automático. En Visual Studio, usa Ver > Terminal y corre claude ahí. Funciona igual de bien para la mayoría de tareas.
Las menciones @ son tu herramienta de precisión — @archivo.cs, @directorio/, y @archivo.cs#10-40 te permiten dar a Claude exactamente el contexto que necesita. En VS Code, el archivo activo se comparte automáticamente; en Visual Studio, sé explícito.
Los Skills son tu ventaja de equipo — crea Skills en .claude/skills/ y versiónalos junto al código. Un /csharp-review consistente para todo el equipo es más valioso que cualquier guideline de código que nadie lee.
Gestiona el contexto activamente — usa /compact antes de que se alargue demasiado la sesión, y usa /memory para verificar qué CLAUDE.md tiene cargado. Entender cómo Claude descubre el contexto (recorrido del filesystem, no archivos de proyecto) elimina mucha confusión.

Claude Code no reemplaza tu conocimiento de .NET — lo amplifica. La diferencia entre usarlo mediocremente y usarlo bien está en esas tres cosas: un buen CLAUDE.md, contexto preciso con @, y Skills que encapsulan tu flujo de trabajo. Con eso, la magia deja de parecer aleatoria.

C# 14: The `field` Keyword — Cleaner Properties, Zero Boilerplate

Juan Gómez — Wed, 10 Jun 2026 21:20:58 +0000

C# 14: The `field` Keyword — Cleaner Properties, Zero Boilerplate

Every C# developer has been there. You start with a clean auto-property, then requirements change and you need to add a tiny bit of validation. Suddenly that one-liner explodes into six lines of boilerplate — a private backing field, a getter that just returns it, a setter that assigns it. The logic is two words. The ceremony is everything else.

C# 14 fixes this with the field keyword: a contextual keyword that refers to the compiler-synthesized backing field of a property, letting you write custom accessor logic without ever declaring an explicit field.

The Problem: Boilerplate Tax on Simple Properties

Auto-properties are one of C#'s best quality-of-life features. This is clean:

public string Username { get; set; }

But the moment you need to trim whitespace on assignment, that cleanness evaporates:

private string _username = string.Empty;

public string Username
{
    get => _username;
    set => _username = value.Trim();
}

You now have six lines — and four of them exist only to hold the shape of the pattern together. The backing field _username is not carrying any meaningful design weight. Its only job is to be a storage slot that Username uses privately. You already know the compiler creates one for auto-properties. You are just forced to make it visible so you can reference it.

This is the boilerplate tax. You pay it every time you add even the smallest piece of logic to a property.

Why `field` Exists

The C# language team has discussed this friction for years. The challenge was finding syntax that is:

Unambiguous — no conflict with existing identifiers
Familiar — consistent with how value works in setters
Scoped — only meaningful inside a property accessor

The solution landed in C# 14: the contextual keyword field. Just like value refers to the incoming assignment in a setter, field refers to the hidden backing storage the compiler manages for the property.

It is contextual, which means it only acts as a keyword inside a property accessor. Everywhere else in your code, field is still a valid identifier name (with one gotcha covered later).

How It Works

Basic Syntax

Here is the same username property rewritten with field:

public string Username
{
    get;
    set => field = value.Trim();
}

The get accessor is still auto-implemented — it just returns field. The set accessor does its one job: trim the incoming value before storing it. The private backing field is gone. The compiler synthesizes it behind the scenes, and field lets you reach into it.

You can also go the other way — implement get and auto-implement set:

public string DisplayName
{
    get => field.ToUpperInvariant();
    set;
}

Or implement both sides:

public int Age
{
    get => field;
    set => field = value >= 0 ? value : throw new ArgumentOutOfRangeException(nameof(value), "Age cannot be negative.");
}

Works with `init` Too

init-only properties work exactly the same way:

public string Email
{
    get;
    init => field = value.Trim().ToLowerInvariant();
}

This is especially useful in immutable record-style classes where you want normalization on construction but no mutation afterwards.

Real-World Usage Patterns

1. Input Normalization

The most common use case. Trim strings, normalize casing, sanitize user input — all without a backing field:

namespace Blog.Models;

public sealed class UserProfile
{
    public string Username
    {
        get;
        set => field = value.Trim();
    }

    public string Email
    {
        get;
        set => field = value.Trim().ToLowerInvariant();
    }

    public string? DisplayName
    {
        get;
        set => field = string.IsNullOrWhiteSpace(value) ? null : value.Trim();
    }
}

All three properties look almost as clean as auto-properties, and each enforces its own invariant at the point of assignment.

2. Range Validation

Numeric properties that must stay within bounds are a perfect fit:

namespace Blog.Models;

public sealed class ProductListing
{
    private const decimal MaxPrice = 99_999.99m;

    public string Title
    {
        get;
        set => field = value.Trim();
    }

    public decimal Price
    {
        get;
        set
        {
            ArgumentOutOfRangeException.ThrowIfNegative(value);
            ArgumentOutOfRangeException.ThrowIfGreaterThan(value, MaxPrice);
            field = value;
        }
    }

    public int StockQuantity
    {
        get;
        set => field = int.Max(0, value); // Quietly clamp negatives — intentional product decision
    }
}

Notice ArgumentOutOfRangeException.ThrowIfNegative and ThrowIfGreaterThan — those are .NET 8+ helpers that are cleaner than manual if throws. Use the modern APIs.

3. Lazy Initialization

field shines for lazy-loaded properties. The classic pattern used to need a nullable backing field and a null-check dance:

// Before C# 14 — the old dance
private List<string>? _tags;
public List<string> Tags => _tags ??= [];

With field, you write the same logic right inside the property:

public List<string> Tags => field ??= [];

One line. The compiler owns the backing field. You own the logic.

4. Change Notification (INotifyPropertyChanged)

ViewModel properties in MVVM apps often look like this:

namespace Blog.ViewModels;

public sealed class OrderViewModel : INotifyPropertyChanged
{
    public event PropertyChangedEventHandler? PropertyChanged;

    public string CustomerName
    {
        get;
        set
        {
            if (field == value) return;
            field = value;
            PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(nameof(CustomerName)));
        }
    }

    public decimal Total
    {
        get;
        set
        {
            if (field == value) return;
            field = value;
            PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(nameof(Total)));
        }
    }
}

No private fields. No name collision risks. The pattern is still verbose (that is just the nature of INotifyPropertyChanged), but field removes one moving part from it.

The `field` Gotcha: When Your Property Is Named `field`

Here is where things get interesting. Because field is a contextual keyword, a property actually named Field (or field in a case-sensitive context) can shadow the keyword. Consider this:

public sealed class DatabaseRecord
{
    // This property is named "field" — uncommon, but legal
    public string field
    {
        get;
        // Inside here, does "field" mean the keyword or the property itself?
        set => field = value.Trim(); // Ambiguous!
    }
}

The compiler will warn you about the ambiguity. The fix is the verbatim identifier @field, which forces C# to treat it as an identifier, not the keyword:

public sealed class DatabaseRecord
{
    public string @field
    {
        get;
        set => @field = value.Trim(); // Explicit: this is the identifier, not the keyword
    }
}

Realistically, naming a property field is unusual. But if you work with code that maps to external schemas or databases that use reserved names, now you know the escape hatch.

When to Use `field`

Use field whenever you need some logic in a property accessor but the property is still the sole owner of its value:

Normalization on assignment — trimming, casing, formatting
Validation on assignment — range checks, null guards, format checks
Lazy initialization — compute-on-first-access patterns
Simple change tracking — equality check before raising events
init-only normalization — immutable objects that need clean input

The rule of thumb: if you would previously have written a private backing field that nothing else in the class references, replace it with field.

When NOT to Use `field`

field is not a silver bullet. There are cases where an explicit backing field is still the right tool:

The constructor bypass problem

Suppose you have a property that raises an event when assigned. You want the constructor to set the initial value silently, without firing the event. With field, you cannot do that — the only way into the backing storage is through the property accessor.

public sealed class Sensor
{
    // The event fires on every set — we want to skip it in the constructor
    public double Temperature
    {
        get;
        set
        {
            field = value;
            ReadingChanged?.Invoke(this, EventArgs.Empty);
        }
    }

    public event EventHandler? ReadingChanged;

    public Sensor(double initialTemperature)
    {
        // This fires ReadingChanged during construction — probably not what you want
        Temperature = initialTemperature;
    }
}

If you need the constructor to bypass the property's logic, keep the explicit backing field and set it directly from the constructor.

Multiple properties sharing state

If two or more properties read from or write to the same underlying value — for example a Radius and a Diameter that are computed from each other — you need an explicit field that both properties reference. field is per-property; it cannot be shared.

Complex derived state

If the "backing storage" is not a simple value but involves multiple fields, caches, or objects, an explicit field with a descriptive name communicates intent far better than the anonymous field keyword.

When a name is important for debugging

Explicit backing fields appear in debuggers with their declared name. The compiler-synthesized backing field for field-based properties gets a generated name (like <Username>k__BackingField) that is less readable in memory dumps or diagnostic tools. For hot paths under heavy diagnostics, you might prefer the explicit field.

Key Takeaways

field is a contextual keyword in C# 14 that refers to the compiler-synthesized backing field of a property — the same one auto-properties already create.
It lets you add logic to one or both accessors without promoting the backing field to an explicit private member.
It works in get, set, and init accessors, and you can mix auto-implementation with field-based implementation in the same property.
The gotcha to remember: if a property is named field, use @field to disambiguate the identifier from the keyword.
Prefer an explicit backing field when: the constructor needs to bypass property logic, multiple properties share one storage slot, or the field name matters for diagnostics.

C# 14: La keyword `field` — Propiedades más limpias, cero boilerplate

Juan Gómez — Wed, 10 Jun 2026 21:18:31 +0000

C# 14: La keyword `field` — Propiedades más limpias, cero boilerplate

Todo desarrollador de C# lo ha vivido. Empiezas con una auto-propiedad limpia, llegan nuevos requerimientos y necesitas agregar una pequeña validación. De repente esa línea explota en seis líneas de boilerplate — un campo privado, un getter que solo lo retorna, un setter que lo asigna. La lógica son dos palabras. La ceremonia es todo lo demás.

C# 14 resuelve esto con la keyword field: una keyword contextual que hace referencia al backing field sintetizado por el compilador de una propiedad, permitiéndote escribir lógica personalizada en los accessors sin necesidad de declarar un campo explícito.

El problema: el impuesto del boilerplate

Las auto-propiedades son una de las mejores mejoras de calidad de vida en C#. Esto es limpio:

public string Username { get; set; }

Pero en el momento en que necesitas hacer un trim del espacio en blanco al asignar, esa limpieza desaparece:

private string _username = string.Empty;

public string Username
{
    get => _username;
    set => _username = value.Trim();
}

Ahora tienes seis líneas — y cuatro de ellas existen únicamente para mantener la forma del patrón. El campo privado _username no aporta ningún peso de diseño significativo. Su único trabajo es ser un slot de almacenamiento que Username usa de forma privada. Ya sabes que el compilador crea uno para las auto-propiedades. Solo estás obligado a hacerlo visible para poder referenciarlo.

Este es el impuesto del boilerplate. Lo pagas cada vez que agregas la más mínima lógica a una propiedad.

Por qué existe `field`

El equipo de C# ha discutido esta fricción durante años. El desafío era encontrar una sintaxis que fuera:

Inequívoca — sin conflicto con identificadores existentes
Familiar — consistente con cómo funciona value en los setters
Acotada — con significado solo dentro de un accessor de propiedad

La solución llegó en C# 14: la keyword contextual field. Igual que value hace referencia al valor entrante en un setter, field hace referencia al almacenamiento interno que el compilador administra para la propiedad.

Es contextual, lo que significa que solo actúa como keyword dentro de un accessor de propiedad. En el resto de tu código, field sigue siendo un nombre de identificador válido (con una trampa que veremos más adelante).

Cómo funciona

Sintaxis básica

La misma propiedad Username reescrita con field:

public string Username
{
    get;
    set => field = value.Trim();
}

El accessor get sigue siendo auto-implementado — simplemente retorna field. El accessor set hace su único trabajo: hacer trim al valor entrante antes de almacenarlo. El campo privado desapareció. El compilador lo sintetiza en segundo plano, y field te permite acceder a él.

También puedes hacerlo al revés — implementar get y auto-implementar set:

public string DisplayName
{
    get => field.ToUpperInvariant();
    set;
}

O implementar ambos lados:

public int Age
{
    get => field;
    set => field = value >= 0 ? value : throw new ArgumentOutOfRangeException(nameof(value), "La edad no puede ser negativa.");
}

También funciona con `init`

Las propiedades de solo inicialización funcionan exactamente igual:

public string Email
{
    get;
    init => field = value.Trim().ToLowerInvariant();
}

Esto es especialmente útil en clases inmutables estilo record donde quieres normalización al construir pero sin mutación posterior.

Patrones de uso en el mundo real

1. Normalización de entrada

El caso de uso más común. Trim de strings, normalización de mayúsculas, saneamiento de input del usuario — todo sin un backing field:

namespace Blog.Models;

public sealed class UserProfile
{
    public string Username
    {
        get;
        set => field = value.Trim();
    }

    public string Email
    {
        get;
        set => field = value.Trim().ToLowerInvariant();
    }

    public string? DisplayName
    {
        get;
        set => field = string.IsNullOrWhiteSpace(value) ? null : value.Trim();
    }
}

Las tres propiedades se ven casi tan limpias como auto-propiedades, y cada una aplica su propio invariante en el punto de asignación.

2. Validación de rango

Las propiedades numéricas que deben mantenerse dentro de límites son un caso perfecto:

namespace Blog.Models;

public sealed class ProductListing
{
    private const decimal MaxPrice = 99_999.99m;

    public string Title
    {
        get;
        set => field = value.Trim();
    }

    public decimal Price
    {
        get;
        set
        {
            ArgumentOutOfRangeException.ThrowIfNegative(value);
            ArgumentOutOfRangeException.ThrowIfGreaterThan(value, MaxPrice);
            field = value;
        }
    }

    public int StockQuantity
    {
        get;
        set => field = int.Max(0, value); // Clamp silencioso — decisión intencional de producto
    }
}

Nota ArgumentOutOfRangeException.ThrowIfNegative y ThrowIfGreaterThan — helpers de .NET 8+ que son más limpios que los if manuales con throw. Usa las APIs modernas.

3. Inicialización lazy

field brilla en propiedades de carga diferida. El patrón clásico requería un backing field nullable y una danza de null-check:

// Antes de C# 14 — el baile de siempre
private List<string>? _tags;
public List<string> Tags => _tags ??= [];

Con field, escribes la misma lógica directamente dentro de la propiedad:

public List<string> Tags => field ??= [];

Una línea. El compilador administra el backing field. Tú administras la lógica.

4. Notificación de cambios (INotifyPropertyChanged)

Las propiedades de ViewModel en aplicaciones MVVM suelen verse así:

namespace Blog.ViewModels;

public sealed class OrderViewModel : INotifyPropertyChanged
{
    public event PropertyChangedEventHandler? PropertyChanged;

    public string CustomerName
    {
        get;
        set
        {
            if (field == value) return;
            field = value;
            PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(nameof(CustomerName)));
        }
    }

    public decimal Total
    {
        get;
        set
        {
            if (field == value) return;
            field = value;
            PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(nameof(Total)));
        }
    }
}

Sin campos privados. Sin riesgo de colisión de nombres. El patrón sigue siendo verboso (esa es la naturaleza de INotifyPropertyChanged), pero field elimina una pieza móvil del rompecabezas.

La trampa de `field`: cuando tu propiedad se llama `field`

Aquí las cosas se ponen interesantes. Como field es una keyword contextual, una propiedad que se llame efectivamente field puede entrar en conflicto con la keyword. Considera esto:

public sealed class DatabaseRecord
{
    // Esta propiedad se llama "field" — inusual, pero legal
    public string field
    {
        get;
        // Dentro de aquí, ¿"field" es la keyword o la propiedad misma?
        set => field = value.Trim(); // ¡Ambiguo!
    }
}

El compilador te advertirá sobre la ambigüedad. La solución es el identificador verbatim @field, que le indica a C# que lo trate como un identificador y no como la keyword:

public sealed class DatabaseRecord
{
    public string @field
    {
        get;
        set => @field = value.Trim(); // Explícito: este es el identificador, no la keyword
    }
}

En la práctica, nombrar una propiedad field es inusual. Pero si trabajas con código que mapea a esquemas externos o bases de datos que usan nombres reservados, ahora conoces la salida de emergencia.

Cuándo usar `field`

Usa field cuando necesitas algo de lógica en un accessor pero la propiedad sigue siendo la única dueña de su valor:

Normalización en asignación — trim, mayúsculas, formato
Validación en asignación — rangos, null guards, formato
Inicialización lazy — patrones de cálculo en primer acceso
Change tracking simple — verificación de igualdad antes de disparar eventos
Normalización en init — objetos inmutables que necesitan entrada limpia

La regla de oro: si antes hubieras escrito un backing field privado al que nada más en la clase hace referencia, reemplázalo con field.

Cuándo NO usar `field`

field no es una bala de plata. Hay casos donde un backing field explícito sigue siendo la herramienta correcta:

El problema del bypass en el constructor

Supón que tienes una propiedad que dispara un evento al asignarse. Quieres que el constructor establezca el valor inicial silenciosamente, sin disparar el evento. Con field no puedes hacerlo — la única forma de acceder al almacenamiento interno es a través del accessor de la propiedad.

public sealed class Sensor
{
    // El evento se dispara en cada set — queremos saltarlo en el constructor
    public double Temperature
    {
        get;
        set
        {
            field = value;
            ReadingChanged?.Invoke(this, EventArgs.Empty);
        }
    }

    public event EventHandler? ReadingChanged;

    public Sensor(double initialTemperature)
    {
        // Esto dispara ReadingChanged durante la construcción — probablemente no es lo que quieres
        Temperature = initialTemperature;
    }
}

Si el constructor necesita saltarse la lógica de la propiedad, mantén el backing field explícito y asígnalo directamente desde el constructor.

Múltiples propiedades que comparten estado

Si dos o más propiedades leen o escriben el mismo valor subyacente — por ejemplo Radius y Diameter calculadas una a partir de la otra — necesitas un campo explícito al que ambas propiedades hagan referencia. field es por propiedad; no puede compartirse.

Estado derivado complejo

Si el "almacenamiento interno" no es un valor simple sino que involucra múltiples campos, cachés u objetos, un campo explícito con un nombre descriptivo comunica la intención mucho mejor que la keyword anónima field.

Cuando el nombre importa para el diagnóstico

Los backing fields explícitos aparecen en los debuggers con su nombre declarado. El backing field sintetizado por el compilador para propiedades basadas en field recibe un nombre generado (como <Username>k__BackingField) que es menos legible en memory dumps o herramientas de diagnóstico. Para rutas críticas bajo diagnósticos intensivos, puede que prefieras el campo explícito.

Puntos clave

field es una keyword contextual de C# 14 que hace referencia al backing field sintetizado por el compilador — el mismo que las auto-propiedades ya crean.
Permite agregar lógica a uno o ambos accessors sin promover el backing field a un miembro privado explícito.
Funciona en accessors get, set e init, y puedes mezclar auto-implementación con implementación basada en field en la misma propiedad.
La trampa a recordar: si una propiedad se llama field, usa @field para distinguir el identificador de la keyword.
Prefiere un backing field explícito cuando: el constructor necesita saltarse la lógica de la propiedad, múltiples propiedades comparten un slot de almacenamiento, o el nombre del campo importa para el diagnóstico.