Writing a Technical Article
A full cycle from deciding on an angle to publishing.
Scenario: You want to write an article titled "How to use AI to write better code" and publish it on your blog. You have opinions on the topic but you're not sure if the angle is actually useful or if the article already exists a hundred times.
[Research] → Plan → [Plan Validation] → Build → ShipHow to read this example
Each step shows what was given to an agent as an instruction, what the agent returned as output, and what the human decided based on that output. The agent can be you, a collaborator, or an AI — the structure is the same either way. Gates are where the human reads the output and decides whether to proceed. That decision is never skipped.
Step 1: Research gate
Instruction given to agent
What already exists on the topic "AI and writing better code"? Is there a specific angle or audience that is underserved? Spend no more than 45 minutes.
Output from agent
- Most existing articles fall into two categories: (1) high-level hype pieces ("AI will replace developers"), or (2) tool-specific tutorials ("how to use Copilot")
- Very few address the mindset and workflow shift — not just the tools
- The audience most underserved: mid-level developers who already use AI tools but feel like they're not getting the full benefit
- Common complaint found in forums: "I use Copilot but I feel like I'm just accepting code I don't understand"
- Proposed angle: using AI to write better code, not AI tools for coding — the focus is on the developer getting better, not the tool being used
Human decision
The angle is real and underserved. The target reader has the tools — they need a mental model for using them intentionally. Proceed to Plan.
Step 2: Plan phase
Instruction given to agent
Using the research findings, write a Plan Brief for this article.
Reference files: Research findings from Step 1
Output from agent
Plan Brief
Problem
Mid-level developers use AI coding tools but feel passive and dependent — they accept suggestions without fully understanding them, which erodes their own skills over time.
Audience
Mid-level developers who already use AI coding tools but feel they're not getting the full benefit.
Goal
Write a practical article that gives developers a mental model for using AI as a thinking partner, not a code generator.
Appetite
One focused writing session (half day). If the article can't be done in that, scope it down — not extend the time.
Constraints
- Target length: 1,000–1,500 words (long enough to be useful, short enough to be read)
- Must be practical, not theoretical — every point needs a concrete example
- No paywalled content, no product promotion
- Tool-agnostic: no specific AI tool named by name
Success criteria
- The article has a clear, testable argument (not just tips)
- Every section includes a concrete, copy-able example
- A mid-level developer who reads it can apply the main idea the same day
- No specific AI tool is mentioned by name
Core assumption
The developer already has AI tools. The problem is not adoption — it is knowing how to use them intentionally.
Rabbit holes
Do not compare AI tools or benchmark outputs — that is a different article.
Out of scope
- AI tool comparisons or recommendations
- Beginner intro to AI coding tools
- Opinion on whether AI will replace developers
Human decision
The brief is solid but the goal sentence is vague ("mental model" is abstract). Proceed to Plan Validation before writing.
Step 3: Plan Validation gate
Instruction given to agent
Read this Plan Brief. Tell me in your own words: what is this article about, what does it argue, and what would you cut if it had to be 20% shorter?
Reference files: Plan Brief from Step 2
Output from agent
- "It's about using AI actively, not passively — like treating it as a pair programmer instead of autocomplete."
- "The argument is: most people are using AI reactively (accept/reject). There's a better way: proactive use."
- "I'd cut the constraint about not mentioning tools — it might make the examples feel vague."
Human decision
The agent's articulation of the argument ("reactive vs. proactive AI use") is sharper than what was in the Plan Brief. The tool-agnostic constraint stays — but it means examples need to be extra concrete to compensate. Update the brief before building.
Changes made to Plan Brief:
- Goal updated: "Write a practical article that argues for proactive AI use over reactive AI use, and gives developers a concrete framework for the shift."
- Added constraint: "Examples must be code-level and specific, since no tool names will be used."
Proceed to Build.
Step 4: Build phase
Instruction given to agent
Write the article according to this Plan Brief. The argument is reactive vs. proactive AI use. Every section needs a concrete code example. Target 1,000–1,500 words. No tool names.
Reference files: Updated Plan Brief from Step 3, Personal writing style guide
Output from agent
Draft produced with the following structure:
- Hook: the "accept/reject" trap — why most developers are using AI reactively
- Section 1: What reactive AI use looks like (code example: accepting a function you don't understand)
- Section 2: What proactive AI use looks like (code example: using AI to explain, then improve, then own)
- Section 3: A 3-question framework to run before accepting any AI output
- Closing: the shift from AI as a shortcut to AI as a thinking partner
Draft came in at 1,650 words.
Human decision — mid-build check
The 3-question framework in Section 3 didn't exist in the Plan Brief — it emerged during writing. It serves the goal directly, so it stays. Plan Brief updated to reflect it as an addition to success criteria.
Cut 200 words from Section 2 (the "reactive" example was over-explained). Final word count: 1,440 — within range.
Plan Brief updated: Added to success criteria: "The article includes a 3-question framework the reader can use immediately."
Proceed to Ship.
Step 5: Ship phase
Instruction given to agent
Review the final draft against the Plan Brief. Confirm all success criteria are met. List anything that is not.
Reference files: Final draft, Plan Brief (updated)
Output from agent
| Success criterion | Status | Note |
|---|---|---|
| Clear, testable argument | Met | Reactive vs. proactive AI use — stated in paragraph 1 |
| Every section has a concrete example | Met | Two code examples, both copy-able |
| Applicable the same day | Met | 3-question framework is immediately usable |
| No specific AI tool named | Met | Confirmed — no tool names in the draft |
| 3-question framework included | Met | Section 3 |
Word count: 1,440. All constraints met.
Human decision
All criteria met. This goes live. Published to personal blog, added to newsletter, shared in the developer community where the original problem surfaced during Research.
Confirmed live: opened the URL in an incognito window. Article loads. Code examples render correctly.
Learnings (captured for next cycle)
- The Plan Validation gate saved real time — the agent's reframing of the argument ("reactive vs. proactive") made the opening stronger before a word was written
- "Tool-agnostic" was the right call but created a constraint that required more concrete examples to compensate — factor this in earlier next time
- The 3-question framework emerged from the Build, not the Plan. This is normal (Build to learn). Updating the Plan Brief mid-build kept it honest
- Next cycle idea: a follow-up article specifically on the 3-question framework
What this example demonstrates
| Principle | Where it showed up |
|---|---|
| Clarity before action | Research gate prevented planning in the wrong direction |
| Build to learn | The 3-question framework emerged during writing, not planning |
| Reality is the only validator | Shipped at "good enough" — only publishing would show if the argument landed |
| Gates reduce cost, not momentum | Plan Validation caught a weak argument before hours of writing |
| The brief is your compass | Plan Brief was updated mid-build to stay honest |
| AI executes. Human decides. | At every gate, the human read the output and made the call — proceed, iterate, or cut |
The full cycle at a glance
[Research] → Plan → [Plan Validation] → Build → ShipEach arrow is a human decision: read the output, judge it, decide what comes next.
Escribir un Artículo Técnico
Un ciclo completo desde decidir el enfoque hasta publicar.
Escenario: Quieres escribir un artículo titulado "Cómo usar IA para escribir mejor código" y publicarlo en tu blog. Tienes opiniones sobre el tema pero no estás seguro de si el enfoque es realmente útil o si el artículo ya existe cien veces.
[Research] → Plan → [Plan Validation] → Build → ShipCómo leer este ejemplo
Cada paso muestra qué se le dio a un agente como instrucción, qué devolvió el agente como resultado, y qué decidió el humano basándose en ese resultado. El agente puede ser tú, un colaborador, o una IA — la estructura es la misma en cualquier caso. Las compuertas son donde el humano lee el resultado y decide si proceder. Esa decisión nunca se omite.
Paso 1: Compuerta de Investigación
Instrucción dada al agente
¿Qué ya existe sobre el tema "IA y escribir mejor código"? ¿Hay un ángulo o audiencia específica desatendida? Dedica no más de 45 minutos.
Resultado del agente
- La mayoría de los artículos existentes caen en dos categorías: (1) piezas de hype de alto nivel ("la IA reemplazará a los desarrolladores"), o (2) tutoriales específicos de herramientas ("cómo usar Copilot")
- Muy pocos abordan el cambio de mentalidad y flujo de trabajo — no solo las herramientas
- La audiencia más desatendida: desarrolladores de nivel medio que ya usan herramientas de IA pero sienten que no están obteniendo el beneficio completo
- Queja común encontrada en foros: "Uso Copilot pero siento que solo estoy aceptando código que no entiendo"
- Ángulo propuesto: usar IA para escribir mejor código, no herramientas de IA para programar — el enfoque es en que el desarrollador mejore, no en la herramienta que se usa
Decisión humana
El ángulo es real y desatendido. El lector objetivo ya tiene las herramientas — necesita un modelo mental para usarlas intencionalmente. Proceder a Planificar.
Paso 2: Fase de Planificar
Instrucción dada al agente
Usando los hallazgos de la investigación, redacta un Plan Brief para este artículo.
Archivos de referencia: Hallazgos de investigación del Paso 1
Resultado del agente
Plan Brief
Problema
Los desarrolladores de nivel medio usan herramientas de IA para programar pero se sienten pasivos y dependientes — aceptan sugerencias sin entenderlas completamente, lo que erosiona sus propias habilidades con el tiempo.
Audiencia
Desarrolladores de nivel medio que ya usan herramientas de IA para programar pero sienten que no están obteniendo el beneficio completo.
Objetivo
Escribir un artículo práctico que dé a los desarrolladores un modelo mental para usar la IA como compañero de pensamiento, no como generador de código.
Apetito
Una sesión de escritura enfocada (medio día). Si el artículo no puede completarse en ese tiempo, reducir el alcance — no extender el tiempo.
Restricciones
- Longitud objetivo: 1,000–1,500 palabras (suficiente para ser útil, corto suficiente para ser leído)
- Debe ser práctico, no teórico — cada punto necesita un ejemplo concreto
- Sin contenido de pago, sin promoción de productos
- Agnóstico en cuanto a herramientas: no se nombra ninguna herramienta de IA específica
Criterios de éxito
- El artículo tiene un argumento claro y comprobable (no solo consejos)
- Cada sección incluye un ejemplo concreto y copiable
- Un desarrollador de nivel medio que lo lea puede aplicar la idea principal el mismo día
- No se menciona ninguna herramienta de IA específica por nombre
Suposición central
El desarrollador ya tiene herramientas de IA. El problema no es la adopción — es saber cómo usarlas intencionalmente.
Trampas a evitar
No comparar herramientas de IA ni comparar resultados — ese es un artículo diferente.
Fuera de alcance
- Comparaciones o recomendaciones de herramientas de IA
- Introducción para principiantes a herramientas de IA para programar
- Opinión sobre si la IA reemplazará a los desarrolladores
Decisión humana
El brief es sólido pero la oración del objetivo es vaga ("modelo mental" es abstracto). Proceder a Validación del Plan antes de escribir.
Paso 3: Compuerta de Validación del Plan
Instrucción dada al agente
Lee este Plan Brief. Dime con tus propias palabras: ¿de qué trata este artículo, qué argumenta, y qué cortarías si tuviera que ser un 20% más corto?
Archivos de referencia: Plan Brief del Paso 2
Resultado del agente
- "Trata sobre usar la IA activamente, no pasivamente — como tratarla como un programador en pareja en lugar de autocompletar."
- "El argumento es: la mayoría de las personas están usando la IA de forma reactiva (aceptar/rechazar). Hay una mejor manera: uso proactivo."
- "Cortaría la restricción de no mencionar herramientas — podría hacer que los ejemplos se sientan vagos."
Decisión humana
La articulación del argumento por parte del agente ("uso reactivo vs. proactivo de la IA") es más precisa que lo que estaba en el Plan Brief. La restricción agnóstica en cuanto a herramientas se mantiene — pero significa que los ejemplos necesitan ser extra concretos para compensar. Actualizar el brief antes de construir.
Cambios realizados al Plan Brief:
- Objetivo actualizado: "Escribir un artículo práctico que argumente a favor del uso proactivo de la IA sobre el uso reactivo, y dé a los desarrolladores un marco concreto para el cambio."
- Restricción agregada: "Los ejemplos deben ser a nivel de código y específicos, ya que no se usarán nombres de herramientas."
Proceder a Construir.
Paso 4: Fase de Construir
Instrucción dada al agente
Escribe el artículo según este Plan Brief. El argumento es uso reactivo vs. proactivo de la IA. Cada sección necesita un ejemplo de código concreto. Objetivo 1,000–1,500 palabras. Sin nombres de herramientas.
Archivos de referencia: Plan Brief actualizado del Paso 3, Guía de estilo de escritura personal
Resultado del agente
Borrador producido con la siguiente estructura:
- Gancho: la trampa de "aceptar/rechazar" — por qué la mayoría de los desarrolladores está usando la IA reactivamente
- Sección 1: Cómo se ve el uso reactivo de la IA (ejemplo de código: aceptar una función que no entiendes)
- Sección 2: Cómo se ve el uso proactivo de la IA (ejemplo de código: usar la IA para explicar, luego mejorar, luego apropiarse)
- Sección 3: Un marco de 3 preguntas para ejecutar antes de aceptar cualquier resultado de IA
- Cierre: el cambio de la IA como atajo a la IA como compañero de pensamiento
El borrador resultó en 1,650 palabras.
Decisión humana — verificación a mitad de construcción
El marco de 3 preguntas en la Sección 3 no existía en el Plan Brief — surgió durante la escritura. Sirve directamente al objetivo, así que se mantiene. Plan Brief actualizado para reflejarlo como una adición a los criterios de éxito.
Se cortaron 200 palabras de la Sección 2 (el ejemplo "reactivo" estaba sobre-explicado). Recuento final de palabras: 1,440 — dentro del rango.
Plan Brief actualizado: Agregado a criterios de éxito: "El artículo incluye un marco de 3 preguntas que el lector puede usar inmediatamente."
Proceder a Lanzar.
Paso 5: Fase de Lanzar
Instrucción dada al agente
Revisa el borrador final contra el Plan Brief. Confirma que todos los criterios de éxito están cumplidos. Lista cualquier cosa que no lo esté.
Archivos de referencia: Borrador final, Plan Brief (actualizado)
Resultado del agente
| Criterio de éxito | Estado | Nota |
|---|---|---|
| Argumento claro y comprobable | Cumplido | Uso reactivo vs. proactivo de la IA — declarado en el párrafo 1 |
| Cada sección tiene un ejemplo concreto | Cumplido | Dos ejemplos de código, ambos copiables |
| Aplicable el mismo día | Cumplido | El marco de 3 preguntas es inmediatamente usable |
| Sin herramienta de IA específica nombrada | Cumplido | Confirmado — sin nombres de herramientas en el borrador |
| Marco de 3 preguntas incluido | Cumplido | Sección 3 |
Recuento de palabras: 1,440. Todas las restricciones cumplidas.
Decisión humana
Todos los criterios cumplidos. Esto sale en vivo. Publicado en el blog personal, agregado al boletín, compartido en la comunidad de desarrolladores donde el problema original surgió durante la Investigación.
Confirmado en vivo: abrió la URL en una ventana de incógnito. El artículo carga. Los ejemplos de código se renderizan correctamente.
Aprendizajes (capturados para el próximo ciclo)
- La compuerta de Validación del Plan ahorró tiempo real — la reformulación del argumento por parte del agente ("reactivo vs. proactivo") hizo la apertura más sólida antes de escribir una palabra
- "Agnóstico en cuanto a herramientas" fue la decisión correcta pero creó una restricción que requirió ejemplos más concretos para compensar — considerarlo antes la próxima vez
- El marco de 3 preguntas emergió de la Construcción, no del Plan. Esto es normal (Construir para aprender). Actualizar el Plan Brief a mitad de construcción lo mantuvo honesto
- Idea para el próximo ciclo: un artículo de seguimiento específicamente sobre el marco de 3 preguntas
Qué demuestra este ejemplo
| Principio | Dónde apareció |
|---|---|
| Claridad antes de acción | La compuerta de Investigación evitó planificar en la dirección equivocada |
| Construir para aprender | El marco de 3 preguntas surgió durante la escritura, no la planificación |
| La realidad es el único validador | Lanzado en "suficientemente bueno" — solo publicar mostraría si el argumento aterrizó |
| Las compuertas reducen el costo, no el impulso | La Validación del Plan detectó un argumento débil antes de horas de escritura |
| El brief es tu brújula | El Plan Brief se actualizó a mitad de construcción para mantenerse honesto |
| La IA ejecuta. El humano decide. | En cada compuerta, el humano leyó el resultado y tomó la decisión — proceder, iterar o cortar |
El ciclo completo de un vistazo
[Research] → Plan → [Plan Validation] → Build → ShipCada flecha es una decisión humana: leer el resultado, juzgarlo, decidir qué viene después.