<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Victor Zaragoza on Medium]]></title>
        <description><![CDATA[Stories by Victor Zaragoza on Medium]]></description>
        <link>https://medium.com/@victorxata?source=rss-96f440a430ea------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*D-WNDD3u3N4kKCQj.jpeg</url>
            <title>Stories by Victor Zaragoza on Medium</title>
            <link>https://medium.com/@victorxata?source=rss-96f440a430ea------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Thu, 19 Nov 2026 16:40:14 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@victorxata/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[The DevOps Handbook Turns 10. AI Just Broke Half of It]]></title>
            <link>https://medium.com/@victorxata/the-devops-handbook-turns-10-ai-just-broke-half-of-it-44f207dbaf8d?source=rss-96f440a430ea------2</link>
            <guid isPermaLink="false">https://medium.com/p/44f207dbaf8d</guid>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[devops]]></category>
            <category><![CDATA[code-review]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[prompt-engineering]]></category>
            <dc:creator><![CDATA[Victor Zaragoza]]></dc:creator>
            <pubDate>Thu, 16 Apr 2026 17:30:00 GMT</pubDate>
            <atom:updated>2026-04-16T17:30:00.645Z</atom:updated>
            <content:encoded><![CDATA[<p><em>Six articles on what goes wrong when AI meets DevOps — and the SDD, ATLAS, and GOTCHA patterns that actually work.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*915h-NVagJrFV5lN_fjzPA.png" /></figure><p>The <a href="https://itrevolution.com/product/the-devops-handbook-second-edition/">DevOps Handbook</a> is 10 years old this year. Most teams never really lived its principles. Now AI promises to finally unlock them — and instead, it’s making things worse.</p><p>I have seen it on three different teams in the past year. They adopt Copilot, they turn on an AI code review bot, they get excited. Six months later, their DORA metrics are worse than before. Lead time doubled. Change failure rate tripled. Code reviewers started ignoring the AI bot because 80% of its comments were noise.</p><p>This is not a tooling problem. It is a <strong>structure</strong> problem. And it hits all three of Gene Kim’s Three Ways at once.</p><h3>The Three Ways, broken</h3><p>Gene Kim, Jez Humble, Patrick Debois, and John Willis built DevOps on three ideas:</p><ol><li><strong>Flow</strong> — work moves smoothly from dev to prod. Small batches. No big handoffs.</li><li><strong>Feedback</strong> — problems detected fast, amplified, trusted.</li><li><strong>Continuous learning</strong> — the team gets better over time. Postmortems without blame. Knowledge sticks.</li></ol><p>AI, without structure, breaks all three:</p><ul><li><strong>Flow breaks.</strong> AI writes a 47-file PR in 45 minutes. Reviewer closes the tab. PR sits 6 days.</li><li><strong>Feedback breaks.</strong> AI reviewer leaves 22 comments on a clean PR. 19 are noise. Team learns to ignore it.</li><li><strong>Learning breaks.</strong> Code gets merged. Nobody understands it. At 2am, on-call has no idea why Kyber-768, why 90 days, why this retry policy.</li></ul><p>Three failure modes, one cause: AI was handed a prompt, not a structure.</p><h3>Three frameworks, one team</h3><p>Through 6 articles, I follow a real-feeling team — integrating <a href="https://quantumapi.eu/">QuantumAPI</a> post-quantum encryption into a .NET 10 + React + AKS app before a compliance audit — and apply three frameworks that each fix one of the Three Ways:</p><ul><li><strong>SDD (Spec-Driven Development)</strong> — <a href="https://github.com/github/spec-kit">GitHub Spec Kit</a> and <a href="https://kiro.dev/">AWS Kiro</a>. Write the spec before the prompt. The AI builds from the spec, not from vague wishes. Fixes the First Way.</li><li><strong>GOTCHA</strong> — a 6-section prompt structure (Goals, Orchestration, Tools, Context, Heuristics, Args). Turns a crying-wolf AI reviewer into one that only flags real issues. Fixes the Second Way.</li><li><strong>ATLAS</strong> — a human checklist (Architect, Trace, Link, Assemble, Stress-test) that keeps the human in the loop across the lifecycle. Complements SDD, supports learning.</li></ul><p>I am honest about where each one fails, too. Article 5 is a deliberate “when-not-to-use” piece, because stacking frameworks without thinking is how teams ship nothing.</p><h3>What I avoided</h3><ul><li>No AI hype. No “revolutionary”. No “game-changing”. Just what worked and what didn’t.</li><li>No one-size-fits-all. The same article includes anti-patterns (Spec Ceremony, Prompt Fossilization, Checklist Theater, Framework Tower).</li><li>No imaginary metrics. The numbers in the series match what I’ve seen in real teams: batch size drops from 47 to 5 files, AI review signal-to-noise goes from 14% to 87%, postmortem duration drops from 2 days to 90 minutes.</li></ul><h3>How a real team actually uses this</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*HSFlgoHXTX-acgB_.png" /></figure><p>After 6 months, the team in the series settled on this:</p><ul><li><strong>SDD</strong> — only for tasks ≥ 4 hours or ≥ 5 files. Skip for bug fixes.</li><li><strong>GOTCHA</strong> — for any AI task run more than twice a week (code review, PR summaries, postmortems, learning notes).</li><li><strong>ATLAS</strong> — just the “Architect” step, only for cross-team features. Skip the rest at sprint scale.</li><li><strong>For 45% of tasks</strong> — no framework. Just write the code.</li></ul><p>That is the most uncomfortable lesson of the series. Tools are tools. Pick them per task, not per identity.</p><h3>The full series</h3><p>Six articles. Each one follows the same structure: a real problem, a solution, hands-on code, and templates you can copy.</p><ol><li><a href="https://blog.victorz.cloud/blog/threeways-01-devops-handbook-ai-broke-it">The DevOps Handbook Turns 10. AI Just Broke Half of It.</a> — intro, thesis, the QuantumAPI team setup</li><li><a href="https://blog.victorz.cloud/blog/threeways-02-specs-before-code">Specs Before Code: Why AI Needs SDD to Keep Batches Small</a> — First Way + SDD, real 40-line spec example</li><li><a href="https://blog.victorz.cloud/blog/threeways-03-ai-code-review-no-cry-wolf">AI Code Review That Doesn’t Cry Wolf</a> — Second Way + GOTCHA, full prompt + Azure DevOps pipeline + Mistral via Scaleway</li><li><a href="https://blog.victorz.cloud/blog/threeways-04-continuous-learning">Continuous Learning When AI Writes Half Your Code</a> — Third Way + tutor mode + learning notes + AI-assisted postmortems</li><li><a href="https://blog.victorz.cloud/blog/threeways-05-when-to-use-what">SDD, ATLAS, GOTCHA: When to Use What (And When They All Fail)</a> — critical comparison, anti-patterns, decision tree</li><li><a href="https://blog.victorz.cloud/blog/threeways-06-devops-playbook">Your AI-Native DevOps Playbook</a> — synthesis, DORA + AI metrics, one-file playbook template</li></ol><p>Read in order if you want the full story. Jump to any one if you have a specific pain.</p><p>The Three Ways still hold. AI did not break them. It amplified whatever you already do. Good teams with structure ship faster with AI. Teams without structure ship technical debt wearing a tuxedo.</p><p>If this helps you, consider <a href="https://github.com/sponsors/victorZKov">sponsoring me on GitHub</a> or <a href="https://buymeacoffee.com/victorxata">buying me a coffee</a>.</p><p><em>I’m Victor Zaragoza, a cloud architect from Valencia, Spain. I build enterprise infrastructure on Azure and Kubernetes, and I write about structured AI-assisted development. The full series lives at </em><a href="https://blog.victorz.cloud/"><em>blog.victorz.cloud</em></a><em>.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=44f207dbaf8d" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[A Scaffold Generator for Claude — Built on Gartner’s Seven Invariants]]></title>
            <link>https://medium.com/@victorxata/a-scaffold-generator-for-claude-built-on-gartners-seven-invariants-a2bd92ead67b?source=rss-96f440a430ea------2</link>
            <guid isPermaLink="false">https://medium.com/p/a2bd92ead67b</guid>
            <dc:creator><![CDATA[Victor Zaragoza]]></dc:creator>
            <pubDate>Thu, 09 Apr 2026 14:29:48 GMT</pubDate>
            <atom:updated>2026-04-09T14:33:01.003Z</atom:updated>
            <content:encoded><![CDATA[<h3>The Problem</h3><p>You start a new project with Claude. You open a folder, type claude, and ask it to build something. Claude is happy to help. Too happy.</p><p>In the first 20 minutes you have:</p><ul><li>A package.json created with npm init (you wanted pnpm)</li><li>A terraform apply run against your dev subscription (you didn’t authorize that)</li><li>A commit signed with “Co-Authored-By: Claude” (your company forbids this)</li><li>An API key hardcoded in appsettings.json because “it’s just for testing”</li><li>A storage account with allow_blob_public_access = true because the AI saw it in a stack overflow answer from 2019</li><li>No tests, because you didn’t ask for them</li></ul><p>Each of these is a small thing. Together, they are the reason your security team blocks AI tools.</p><p>The fix is not “be careful”. The fix is make it impossible. Not for Claude — for the project. From the very first file.</p><h3>The Solution</h3><p>I built <a href="https://github.com/victorZKov/scaffold-generator">scaffold-generator</a>, a public repo on GitHub that does one thing: it generates a new project structure with all the guardrails already in place.</p><p>Not a template. Not a starter kit. A deterministic interview. You open the repo with Claude, and Claude asks you questions — one at a time — about what you want to build. Tech stack, architecture, requirements, CI/CD platform, ATLAS+GOTCHA methodology. Then, and only then, it generates the scaffolding.</p><p>The scaffolding includes:</p><ul><li>A CLAUDE.md with the rules of your specific project</li><li>14 hooks in .claude/hooks/ that block dangerous actions before they reach disk</li><li>A governance.md document with the seven invariants every artifact must pass</li><li>CI/CD pipelines for your platform (GitHub Actions, GitLab CI, or Azure DevOps)</li><li>A complete .NET Clean Architecture structure (or React, or Terraform, depending on your answers)</li><li>Real tests scaffolded — not stubs</li></ul><p>The interview matters. Claude does not assume things. It asks. If you don’t know an answer, it gives you options. If you give a vague answer, it asks for more detail. The whole point is: no design decisions made by the AI without your consent.</p><h3>Where Gartner fits in</h3><p>This is not made up. The architecture follows the Gartner research note <a href="https://www.gartner.com/"><em>How to Govern Anthropic’s Claude Code at Scale</em></a> (G00850426, March 2026). Gartner defines seven invariants that every AI-generated artifact must satisfy:</p><p>Invariant — What it means</p><p>1 Functional — Implements the spec, passes static analysis and contract tests</p><p>2 Tested — Unit + integration + E2E tests, ≥75% coverage</p><p>3 Secure — No secrets, no CVEs, no SAST findings, no insecure flows</p><p>4 Scalable — No N+1 queries, async I/O, idempotent handlers</p><p>5 Performant — Meets P95 latency budget, no regressions</p><p>6 Observable — Structured logs, metrics, traces from day one</p><p>7 Auditable — Conventional commits, SBOM, signed artifacts, prompt lineage</p><p>And three checkpoints where these invariants must be enforced:</p><ol><li>Generation — Claude hooks block bad actions as the file is being written</li><li>Pre-commit / pre-push — Git hooks run the same checks before code leaves your machine</li><li>CI/CD pipeline — The pipeline runs them again, with the same configuration</li></ol><p>The same tools at every checkpoint. Skipping any one creates an exploitable gap.</p><p>Most teams stop at the CI pipeline. By the time the pipeline catches a hardcoded secret, the secret is already in git history. The whole point of generation-time enforcement is to never let the bad code exist in the first place.</p><h3>Execute</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*BVEtrwQ9_5RQAeWj.jpg" /></figure><p>Let’s see what’s actually inside the repo.</p><h3>The interview flow</h3><p>When you open the repo and ask Claude to scaffold a project, it follows goals/scaffold.md. The first thing it does is detect your language. If you write in Spanish, the entire interview is in Spanish. If you switch to English mid-interview, it switches too.</p><p>Then it asks, in order:</p><pre>Phase 1 — Project Identity<br>  Q1: Project name (PascalCase)<br>  Q2: Description (1-2 sentences)</pre><pre>Phase 2 — Requirements<br>  Q3: Architecture description<br>  Q4: Functional requirements<br>  Q5: Non-functional requirements</pre><pre>Phase 3 — Project Type<br>  Q6: Web, mobile, infra, API, or combinations?</pre><pre>Phase 4 — DevOps<br>  Q7: GitHub, GitLab, or Azure DevOps?<br>  Q8: Issue tracking platform</pre><pre>Phase 5 — Methodology<br>  Q9: Apply ATLAS + GOTCHA + SDD?</pre><p>Only after you confirm with “SÍ” / “YES” does generation start. The generation order is also deterministic — files are created in a specific sequence so dependencies always exist when something references them.</p><h3>The hooks that protect you</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*NnPZVl_FKKUxmKp5.jpg" /></figure><p>Inside .claude/hooks/ there are 14 shell scripts. Each one fires on specific Claude tool calls (Write, Edit, Bash) and inspects what’s about to happen. If something looks wrong, the hook blocks the action and tells Claude why.</p><p>Here’s a sample:</p><pre># block-secrets.sh — fires on Write/Edit<br># Blocks AWS keys, GitHub PATs, Azure connection strings,<br># private keys, hardcoded passwords, JWTs in source files</pre><pre>PATTERNS=(<br>    &#39;AKIA[0-9A-Z]{16}&#39;                          # AWS Access Key<br>    &#39;ghp_[A-Za-z0-9]{36}&#39;                       # GitHub PAT<br>    &#39;AccountKey=[A-Za-z0-9+/=]{40,}&#39;            # Azure storage<br>    &#39;-----BEGIN (RSA |EC |OPENSSH )PRIVATE KEY-----&#39;<br>    &#39;(password|passwd|pwd)[[:space:]]*[:=][[:space:]]*[&quot;\x27][^&quot;\x27]{6,}[&quot;\x27]&#39;<br>)</pre><p>Or this one, which blocks the most expensive Terraform mistake — a public storage account:</p><pre># block-tf-public-exposure.sh — fires on Write/Edit for *.tf files<br>declare -a PATTERNS=(<br>    &#39;0\.0\.0\.0/0&#39;<br>        &quot;Open CIDR (0.0.0.0/0). Restrict to known ranges.&quot;<br>    &#39;public_network_access_enabled[[:space:]]*=[[:space:]]*true&#39;<br>        &quot;Use private endpoints instead.&quot;<br>    &#39;allow_blob_public_access[[:space:]]*=[[:space:]]*true&#39;<br>        &quot;Storage must be private.&quot;<br>    &#39;min_tls_version[[:space:]]*=[[:space:]]*&quot;TLS1_0&quot;&#39;<br>        &quot;TLS1_0 is deprecated. Use TLS1_2 minimum.&quot;<br>    &#39;skip_final_snapshot[[:space:]]*=[[:space:]]*true&#39;<br>        &quot;Production data must be snapshotted.&quot;<br>)</pre><p>The complete list of hooks:</p><p>HookWhat it blocksblock-npm.shAny npm install / npm run — pnpm onlyblock-git-push.shgit push without explicit user authorizationblock-terraform-apply.shterraform apply from your laptop — pipelines onlyblock-no-verify.shgit commit --no-verify — fix the hook, don’t skip itblock-claude-attribution.shCo-Authored-By: Claude in commitsblock-destructive-actions.shrm -rf, destructive az CLI commandsblock-secrets.shHardcoded credentials in any fileblock-tf-public-exposure.shPublic storage, open CIDRs, weak TLS in Terraformenforce-invariants.shFiles that violate the seven invariantsenforce-tf-policy.shTerraform without required tags, naming, encryptionprovenance-stamp.shStamps every generation with prompt lineagerequire-tests.shProduction code in Domain/Application/Api needs testsrequire-tf-module-tests.shTerraform modules need a tests/ folderrequire-tf-tags.shAll Azure resources need tags</p><p>These are not suggestions. They run automatically. If Claude tries to write a file that violates any of them, the hook exits with a non-zero code and Claude sees the error message and tries again.</p><h3>What the generated CLAUDE.md looks like</h3><p>After the interview, the generated project has its own CLAUDE.md. It includes all the guardrails plus the specific decisions you made:</p><pre># CLAUDE.md — QuantumApi</pre><pre>## What This Project Is<br>A REST API for managing post-quantum encryption keys.<br>Built with .NET 10 Clean Architecture, PostgreSQL, deployed<br>to Azure via GitHub Actions.</pre><pre>## Tech Stack<br>- Backend: .NET 10 (Domain / Application / Infrastructure / Api)<br>- Database: PostgreSQL 16<br>- Auth: Entra ID<br>- Hosting: Azure Container Apps<br>- IaC: Terraform<br>- CI/CD: GitHub Actions</pre><pre>## Methodology<br>ATLAS + GOTCHA + SDD applied to all features</pre><pre>## Coverage<br>75% minimum, 80% target — enforced in CI</pre><pre>## Guardrails (enforced by hooks)<br>- pnpm only (block-npm.sh)<br>- No git push without authorization (block-git-push.sh)<br>- No terraform apply locally (block-terraform-apply.sh)<br>- No Claude attribution (block-claude-attribution.sh)<br>- ... (the full list)</pre><p>This file is the first thing Claude reads in any new conversation. So every future session in that project starts with the rules already loaded.</p><h3>The prompt lineage ledger</h3><p>This is the part I am most proud of. Every time Claude generates a file, the provenance-stamp.sh hook writes an entry to .claude/provenance/&lt;date&gt;.jsonl. The entry contains:</p><ul><li>The exact prompt that triggered the generation</li><li>The model and version used</li><li>The file path that was created or modified</li><li>A SHA-256 hash of the content</li><li>The timestamp</li></ul><p>This is your audit trail. Six months from now, when someone asks “why does this function exist?”, you can answer: “because on April 9, the user asked X, and Claude generated this file in response, and here’s the hash to prove it hasn’t changed since.”</p><p>This is invariant number 7 — Auditable — and it’s the one most teams forget about.</p><h3>Template</h3><p>Here’s the minimum you need to use this on your next project. No cloning, no git tricks, no setup. Just open the project folder with Claude and ask:</p><pre># 1. Open the scaffold-generator folder<br>cd path/to/scaffold-generator</pre><pre># 2. Start Claude<br>claude</pre><p>Then say, in any language: <em>“I want to create a new project.”</em></p><p>Claude will detect your language, announce the interview, and start asking questions. Don’t skip ahead. Don’t say “use sensible defaults”. The whole point is that you make the decisions, and Claude documents them.</p><p>When the interview ends, Claude shows you a summary. If everything looks right, you reply with “SÍ” or “YES” and generation starts. The hooks are already active — they were active from the moment you opened Claude in this folder, because .claude/settings.json registered them.</p><p>If you want to verify the hooks are working before generating anything, ask Claude to write a file with a fake AWS key. It will refuse — and the error message will come from block-secrets.sh, not from Claude’s good intentions.</p><h3>Challenge</h3><p>Try this on a real project:</p><ol><li>Clone the <a href="https://github.com/victorZKov/scaffold-generator">scaffold-generator</a> repo</li><li>Pick a small idea — a TODO API, a personal expense tracker, a script that reads RSS feeds</li><li>Run the interview from start to finish (yes, all the questions)</li><li>Look at the generated project and count: how many decisions did Claude make on its own?</li></ol><p>The answer should be zero. Every folder name, every package version, every CI step, every Terraform tag — all of it came from your answers. That is what governable AI development looks like.</p><p>And then test the hooks. Try to commit a hardcoded password. Try to run npm install. Try to write a Terraform file with 0.0.0.0/0. See what happens.</p><p>The repo is public, MIT licensed. Use it, fork it, send PRs. If your team has a guardrail I missed, open an issue — I want to add it.</p><p>If this article helps you, consider <a href="https://github.com/sponsors/victorZKov">sponsoring me on GitHub</a> or <a href="https://buymeacoffee.com/victorxata">buying me a coffee</a>.</p><p><em>This is a standalone article. If you want to learn the prompt structure that ATLAS + GOTCHA + SDD use to drive these generations, start with the </em><a href="https://blog.victorz.cloud/blog?series=atlas-gotcha"><em>ATLAS + GOTCHA series</em></a><em>. If you want to see how the same governance model applies to a full Internal Developer Platform, the </em><a href="https://blog.victorz.cloud/blog?series=ai-native-idp"><em>AI-Native IDP series</em></a><em> walks through it end to end.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a2bd92ead67b" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Your Internal Developer Platform Is a Catalog. It Should Be an Assistant.]]></title>
            <link>https://medium.com/@victorxata/your-internal-developer-platform-is-a-catalog-it-should-be-an-assistant-8525094f45b3?source=rss-96f440a430ea------2</link>
            <guid isPermaLink="false">https://medium.com/p/8525094f45b3</guid>
            <category><![CDATA[devops]]></category>
            <category><![CDATA[backstage]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[internaldeveloperplatform]]></category>
            <dc:creator><![CDATA[Victor Zaragoza]]></dc:creator>
            <pubDate>Sat, 28 Mar 2026 13:14:44 GMT</pubDate>
            <atom:updated>2026-03-28T13:14:44.606Z</atom:updated>
            <content:encoded><![CDATA[<p><em>How I added six AI plugins to Backstage and turned a static portal into something developers actually use.</em></p><p>You set up Backstage. You filled the service catalog. You wrote templates. You even added TechDocs. Then you looked at the usage metrics and realized nobody opens it unless they absolutely have to.</p><p>I’ve seen this pattern in every enterprise I’ve worked with. The platform team builds the portal. Developers bookmark it. And then they go back to Slack, Confluence, and asking the person sitting next to them.</p><p>The problem isn’t Backstage. The problem is that a catalog is passive. It waits for you to search. It doesn’t know what you’re building. It can’t tell you that the service you’re about to create already exists, or that the template you picked doesn’t follow the latest security policy.</p><p>I spent the last few months building something different: an AI-native IDP. Same Backstage. Same catalog. But with a .NET AI service behind it that makes the platform active instead of passive.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*gzzyoN3KiMGQHkYjEIOSOw.png" /></figure><h3>What “AI-native” actually means</h3><p>Not chatbots. Not “ask AI anything” search boxes. Specific plugins that solve specific problems developers face every day:</p><p><strong>A catalog that enriches itself.</strong> When you register a new service, the AI reads the repository, detects the tech stack, identifies dependencies, and fills the catalog metadata. No more YAML files with description: &quot;TODO&quot;.</p><p><strong>Templates that adapt.</strong> Instead of 47 templates for every combination of language and framework, one smart template that asks what you need and generates the right scaffolding. Including security policies, CI/CD pipelines, and Kubernetes manifests that match your organization’s standards.</p><p><strong>Code review that knows your architecture.</strong> A Backstage plugin that sends pull requests to the AI service. The AI doesn’t just check syntax — it knows your catalog, your architecture decision records, your existing services. It catches things like “this service is calling the payments API directly instead of going through the gateway.”</p><p><strong>Documentation that answers questions.</strong> TechDocs with RAG. You ask “how does authentication work in our platform?” and get an answer synthesized from your actual architecture docs, ADRs, and runbooks. With sources.</p><p><strong>Governance you can see.</strong> A dashboard that scores every service against your organization’s policies. Not a spreadsheet someone updates quarterly — a live view powered by the AI analyzing each repository against your rules.</p><p><strong>Incident response that connects the dots.</strong> When something breaks, the AI correlates the alert with recent deployments, dependency changes, and past incidents. It doesn’t fix the problem. It gives the on-call engineer context in seconds instead of minutes.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*YWcKVHTXNARklLDEp_pdTg.png" /></figure><h3>The architecture</h3><p>The whole thing runs on three components:</p><ol><li><strong>Backstage</strong> — the portal, with six custom plugins (frontend + backend)</li><li><strong>A .NET Minimal API service</strong> — handles all AI logic, talks to Mistral (or any LLM), and connects to PostgreSQL for vector search and conversation history</li><li><strong>Kubernetes</strong> — everything runs on K8s with proper networking, secrets management, and observability</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*MsBSdTYGGMoUUrt-ZRyXDQ.png" /></figure><p>Each plugin is independent. You can deploy one, three, or all six. The .NET service exposes clean REST endpoints that each plugin calls. No monolith. No tight coupling.</p><p>I chose Mistral as the default LLM because it runs on European infrastructure (Scaleway), which matters if you care about data sovereignty. But the service is model-agnostic — swap in any provider by changing one configuration.</p><h3>Does it work?</h3><p>I built this with real enterprise constraints in mind. Not a demo. Not a proof of concept. The code handles authentication, AI usage tracking, and error handling. The Kubernetes manifests include security contexts, resource limits, and health checks. Rate limiting and full audit logging are left as production exercises — I cover those in a follow-up series.</p><p>Is it production-ready out of the box? No. Every organization has different policies, different infrastructure, different LLM choices. But the architecture is solid, the patterns are tested, and the code is open for you to read, fork, and adapt.</p><p>The point isn’t “install this and you’re done.” The point is “here’s how AI plugins in Backstage actually work, with real code, so you can build your own.”</p><h3>The full series</h3><p>I wrote 8 articles covering the entire journey. Each one follows the same structure: a real problem, a solution design, hands-on code, and something you can take away.</p><ol><li><a href="https://blog.victorz.cloud/blog/idp-01-why-your-idp-doesnt-help">Why Your IDP Doesn’t Help</a> — The gap between what platforms promise and what developers experience</li><li><a href="https://blog.victorz.cloud/blog/idp-02-teaching-your-catalog-to-think">Teaching Your Catalog to Think</a> — AI-powered catalog enrichment that fills metadata automatically</li><li><a href="https://blog.victorz.cloud/blog/idp-03-ai-powered-templates">AI-Powered Software Templates</a> — Smart scaffolding that adapts to your organization’s standards</li><li><a href="https://blog.victorz.cloud/blog/idp-04-ai-code-review">The AI Code Review Plugin</a> — Architecture-aware code review inside Backstage</li><li><a href="https://blog.victorz.cloud/blog/idp-05-techdocs-rag">TechDocs RAG — AI That Reads Your Docs</a> — Ask questions, get answers from your actual documentation</li><li><a href="https://blog.victorz.cloud/blog/idp-06-governance-dashboard">The AI Governance Dashboard</a> — Live compliance scoring for every service</li><li><a href="https://blog.victorz.cloud/blog/idp-07-incident-response">AI-Assisted Incident Response</a> — Context and correlation when things break</li><li><a href="https://blog.victorz.cloud/blog/idp-08-reference-architecture">The Reference Architecture</a> — How every piece connects, deploys, and extends</li></ol><p>The complete series is on my blog: <a href="https://blog.victorz.cloud/">victorz.cloud</a></p><p><em>I’m Victor Zaragoza, a cloud architect from Valencia, Spain. I build enterprise infrastructure on Azure and Kubernetes, and I write about making developer platforms smarter. The full AI-Native IDP series is at </em><a href="https://blog.victorz.cloud/"><em>blog.victorz.cloud</em></a><em>.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=8525094f45b3" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Stop Writing AI Prompts Like Wishes. Use a System Instead.]]></title>
            <link>https://medium.com/@victorxata/stop-writing-ai-prompts-like-wishes-use-a-system-instead-5e7b260b9755?source=rss-96f440a430ea------2</link>
            <guid isPermaLink="false">https://medium.com/p/5e7b260b9755</guid>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[productivity]]></category>
            <category><![CDATA[devops]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <dc:creator><![CDATA[Victor Zaragoza]]></dc:creator>
            <pubDate>Wed, 18 Mar 2026 10:50:29 GMT</pubDate>
            <atom:updated>2026-03-18T10:50:29.555Z</atom:updated>
            <content:encoded><![CDATA[<p><em>How two frameworks turned my AI-assisted development from guesswork into a repeatable process.</em></p><p>You open your AI tool. You type “create a users API with authentication.” You get something. Maybe it works. Maybe it uses a framework you hate. Maybe the database schema makes no sense for your project.</p><p>So you try again. You add more words. “Create a users API with JWT authentication and PostgreSQL.” Better. But now the AI picks bcrypt when you wanted Argon2. It uses controllers when you wanted minimal APIs. It skips soft delete. It invents field names that don’t match your existing database.</p><p>I’ve done this hundreds of times. I’m a cloud architect working with Azure, Kubernetes, and .NET in enterprise environments. When I started using AI for development, my prompts looked like everyone else’s: short, generic, and frustrating.</p><p>The problem wasn’t the AI. The problem was me. I was giving it wishes instead of specifications.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*tpmEhKQe7ugg4i0_j0bMEA.png" /></figure><h3>The real issue</h3><p>AI language models are probabilistic systems. The same prompt can produce different results each time. You can’t change that. But you can reduce the space of possible answers by being precise about what you need.</p><p>Most developers skip this part. They know what they want — or they think they do — and they jump straight into prompting. But “I know what I want” and “I can express what I want in a way an AI can process” are two very different things.</p><p>I found a pattern that works. Actually, two patterns that work together. I use them every day, and they’ve changed how I build software with AI.</p><h3>ATLAS: Think before you prompt</h3><p><strong>ATLAS</strong> is a checklist. Five phases of thinking you do before you open any AI tool:</p><p>Phase…….. Question you answer</p><p><strong>A</strong>rchitect .. What are we building? What are the boundaries and constraints?</p><p><strong>T</strong>race…..… How does data flow through the system?</p><p><strong>L</strong>ink….….. How do components connect to each other?</p><p><strong>A</strong>ssemble.. In what order do we build?</p><p><strong>S</strong>tress-test.. How do we validate this under real conditions?</p><p>This is your homework. The AI doesn’t see it. You do it for yourself, so that when you finally write a prompt, you know exactly what you need.</p><p>Think of it this way: ATLAS is what separates “create a users API” from “I need a REST API that handles registration, login, and user management with JWT tokens that expire in 1 hour, Argon2id password hashing, PostgreSQL with EF Core, soft delete filtered by a global query filter, and deployed to Kubernetes with proper security context.”</p><p>The second version isn’t longer because you’re being verbose. It’s longer because you actually thought about the problem.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*yniajIkHxh4A6wwg1-lz9w.png" /></figure><h3>GOTCHA: Tell the AI what it needs to know</h3><p>Once you’ve done ATLAS, you have a set of decisions. But the AI doesn’t read your notes. It reads prompts. And a prompt needs structure.</p><p><strong>GOTCHA</strong> is a 6-layer format that organizes your ATLAS thinking into categories the AI can process:</p><p>Layer……….….What it tells the AI</p><p><strong>G</strong>oals…………..What success looks like (the mission)</p><p><strong>O</strong>rchestration..In what order to build (the sequence)</p><p><strong>T</strong>ools……………What frameworks and libraries to use</p><p><strong>C</strong>ontext…………Background knowledge and constraints</p><p><strong>H</strong>euristics………Rules to follow, patterns to use, mistakes to avoid</p><p><strong>A</strong>rgs………………Specific parameters and configuration values</p><p>Each layer answers a different question. Each layer gives the AI a specific type of instruction. The AI doesn’t have to guess what’s a goal, what’s a constraint, and what’s a rule — because you’ve separated them.</p><h3>A real example</h3><p>Here’s what this looks like in practice. Same task: build a users API.</p><p><strong>Without ATLAS + GOTCHA:</strong></p><pre>Create a users API with CRUD operations and JWT authentication.</pre><p>The AI will guess everything. Database? Framework? Password hashing? Auth flow? Deployment? All up to the AI. And it will make different choices every time.</p><p><strong>With ATLAS + GOTCHA:</strong></p><pre>=== GOALS ===<br>Build a .NET 10 Web API for user management:<br>POST /users (register), POST /auth/login (JWT),<br>GET /users/{id} (auth required), PUT /users/{id} (auth + owner),<br>DELETE /users/{id} (auth + owner, soft delete).<br>All errors -&gt; RFC 7807 problem details.<br><br>=== ORCHESTRATION ===<br>1. User entity + DbContext + EF Core migration<br>2. IUserRepository + UserRepository<br>3. PasswordService (Argon2id, m=64MB, t=3, p=4)<br>4. JwtService (HS256, claims: sub, email, jti)<br>5. UsersController<br>6. JWT middleware + global error handler<br>7. Dockerfile (multi-stage, non-root) + K8s manifests<br><br>=== TOOLS ===<br>.NET 10, EF Core 10, Npgsql, Konscious.Security.Cryptography.Argon2,<br>System.IdentityModel.Tokens.Jwt, Docker, Kubernetes<br><br>=== CONTEXT ===<br>Deploys to AKS. Consumed by React frontend + internal services.<br>Soft delete via IsDeleted boolean (global EF query filter).<br>This service owns user credentials - no external identity provider.<br><br>=== HEURISTICS ===<br>DO: repository pattern, async/await, return DTOs not entities.<br>DON&#39;T: business logic in controllers, swallow exceptions,<br>return stack traces, store plain-text passwords.<br>K8s: runAsNonRoot: true, allowPrivilegeEscalation: false.<br><br>=== ARGS ===<br>JWT_SECRET: env var (32+ chars), JWT_EXPIRY: 60 min,<br>ARGON2: m=65536, t=3, p=4, PORT: 8080,<br>K8s namespace: users-api, replicas: 2</pre><p>That’s it. The AI knows the mission, the order, the tools, the constraints, the rules, and the config. It doesn’t have to guess. The output is predictable, consistent, and close to what you actually need.</p><p>Not perfect — you still review the code. But the review takes minutes instead of hours, because the AI was working from a real specification, not a wish.</p><h3>Does it actually work?</h3><p>I used ATLAS + GOTCHA to build a complete users API with PostgreSQL, JWT, and Kubernetes deployment in 45 minutes. Then I used it again to build a 5-stage CI/CD pipeline on Azure DevOps with security scanning. Both are production-quality. Both are open source.</p><p>The pattern scales. I’ve used it for mTLS certificate rotation, field-level PII encryption, OIDC integration, and supply chain security. Each time, the same two frameworks. Each time, the AI delivered code that was 90% ready on the first pass.</p><p>The 10% that needed adjusting? That’s the point. You’re the architect. The AI is the builder. ATLAS makes sure you do your job. GOTCHA makes sure the AI can do its.</p><h3>The full series</h3><p>I wrote an 8-article series covering ATLAS + GOTCHA from theory to production. Each article follows the same structure: a real problem, the framework applied to it, hands-on code, and a downloadable template.</p><p>Here’s the roadmap:</p><ol><li>Why AI Prompts Fail and What to Do About It</li><li>ATLAS: The 5 Phases Every Architect Must Know</li><li>GOTCHA: The 6 Layers That Make AI Think</li><li>The Perfect Mapping: ATLAS Meets GOTCHA</li><li>Hands-On: Build a Users API in 45 Minutes</li><li>Hands-On: A Production CI/CD Pipeline with Security Scanning</li><li>Advanced Patterns and Anti-Gotchas</li><li>Your 90-Day Roadmap: From Developer to ATLAS Architect</li></ol><p>The complete series is on my blog: <a href="https://victorz.cloud/">victorz.cloud</a></p><p>All the code is on GitHub:</p><ul><li><a href="https://github.com/victorZKov/atlas-gotcha-code">atlas-gotcha-code</a> — Users API + CI/CD pipeline</li></ul><p><em>I’m Victor Zaragoza, a cloud architect from Valencia, Spain. I build enterprise infrastructure on Azure and Kubernetes, and I write about making AI actually useful for real development work. The full ATLAS + GOTCHA series is at </em><a href="https://victorz.cloud/"><em>victorz.cloud</em></a><em>.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=5e7b260b9755" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>