<?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 Apurv Sheth on Medium]]></title>
        <description><![CDATA[Stories by Apurv Sheth on Medium]]></description>
        <link>https://medium.com/@apurvsheth?source=rss-a27130eabf4a------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*6ujbThh9Tx7CIJ7b6UGIgw.jpeg</url>
            <title>Stories by Apurv Sheth on Medium</title>
            <link>https://medium.com/@apurvsheth?source=rss-a27130eabf4a------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Tue, 17 Nov 2026 21:39:54 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@apurvsheth/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[Shipping & Running: Bitbucket/GitHub, Jenkins and Kubernetes in the ADLC (Part 3 of 3)]]></title>
            <link>https://apurvsheth.medium.com/shipping-running-bitbucket-github-jenkins-and-kubernetes-in-the-adlc-part-3-of-3-573374fb5353?source=rss-a27130eabf4a------2</link>
            <guid isPermaLink="false">https://medium.com/p/573374fb5353</guid>
            <category><![CDATA[agentic-ai]]></category>
            <category><![CDATA[technology]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[spring-boot]]></category>
            <dc:creator><![CDATA[Apurv Sheth]]></dc:creator>
            <pubDate>Tue, 08 Sep 2026 02:01:05 GMT</pubDate>
            <atom:updated>2026-09-08T02:01:05.012Z</atom:updated>
            <content:encoded><![CDATA[<p><em>Final part of a 3-part series translating Anthropic’s AI-Native SDLC Playbook into a Spring Boot / React / Jenkins / Kubernetes stack. Part 1 covered Plan and Design, Part 2 covered Build and Test.</em></p><h3>Start here: the one rule that governs everything below</h3><p>Before you read another line, write this down somewhere you’ll actually see it again: <strong>the agent may act right up to the production gate, and it cannot pass that gate on its own.</strong></p><p>Everything in this article — every hook, every pipeline stage, every Kubernetes control band — is just a different mechanism for making that one rule structurally true instead of procedurally hoped for. If you remember nothing else from Part 3, remember that sentence, because it’s the difference between an audit-ready deployment process and an incident report waiting to be written.</p><h3>Where we left off</h3><p>By this point in the loop, we have a merged, tested change with a full audit trail behind it: intent.md → spec.md → plan.md → the diff and its JUnit tests. What&#39;s left is the part every engineering org already spends the most process on: getting that change reviewed, into production, and kept healthy once it&#39;s there. This is Stage 5 (<strong>Deploy</strong>) and Stage 6 (<strong>Maintain</strong>).</p><h3>Stage 5 — Deploy: review runs both ways</h3><h3>Claude in the Bitbucket/GitHub PR loop</h3><p>Claude does two jobs in code review, not one: it reviews <em>incoming</em> pull requests against your organization’s standards, and it addresses review comments on the PRs <em>it</em> opened. That frees human reviewers to focus on the one thing only a human should judge — whether the change does what was intended, and whether the risk is acceptable — rather than spending their limited attention hunting for null-pointer risks a static pass would have caught anyway.</p><p>The review policy itself lives as a plain file at the repo root, so it’s versioned and reviewable like any other config:</p><pre># REVIEW.md<br><br>## Passes<br>Run three passes and tag each finding with its pass:<br>- Bugs: logic errors, broken edge cases, subtle regressions in<br>  Spring Boot service/controller layers<br>- Security: injection risks, missing @Valid, JWT bypass, PII in logs<br>- Compliance: the change matches spec.md, plan.md and our design<br>  principles<br><br>## What &quot;Important&quot; means here<br>Reserve Important for findings that would break behavior, leak<br>data, or breach policy. Naming and formatting are nits.<br><br>## Cap the nits<br>Report at most five nits per review; summarize the rest as a count.<br><br>## Do not report<br>Generated MapStruct classes under target/generated-sources/, and<br>anything Spotless/Checkstyle already enforces in CI.</pre><p>Whether you route this through the managed Code Review service or your own claude-code-action running inside Jenkins/GitHub Actions, the mechanics are the same: branch protection still requires a human code owner&#39;s approval before merge to main. Claude&#39;s findings inform that decision; they never replace it. When a reviewer tags @claude on a comment thread, Claude addresses it and pushes a fix — the thread itself becomes part of the audit record, showing both the request and the change.</p><p>One habit worth adopting from day one: <strong>when a review flags the same mistake twice, that correction goes straight into </strong><strong>CLAUDE.md</strong> from Part 2. Because review reads CLAUDE.md too, the mistake gets caught automatically from the very next PR onward.</p><h3>Hooks as approval gates</h3><p>Part 2 covered hooks as build-time guardrails — deterministic scripts that silently allow or block an action. Deploy is where a hook gets to do something more interesting: <strong>pause and ask a specific human for approval.</strong></p><pre>// .claude/settings.json<br>{<br>  &quot;hooks&quot;: {<br>    &quot;PreToolUse&quot;: [<br>      {<br>        &quot;matcher&quot;: &quot;Bash&quot;,<br>        &quot;hooks&quot;: [<br>          { &quot;type&quot;: &quot;command&quot;,<br>            &quot;command&quot;: &quot;${CLAUDE_PROJECT_DIR}/.claude/hooks/production-gate.sh&quot; }<br>        ]<br>      }<br>    ]<br>  }<br>}</pre><pre>#!/bin/bash<br># .claude/hooks/production-gate.sh<br># Production deploys require a named release authorization.<br>cmd=$(jq -r &#39;.tool_input.command&#39; &lt; /dev/stdin)<br>if [[ &quot;$cmd&quot; == *&quot;helm upgrade&quot;* &amp;&amp; &quot;$cmd&quot; == *&quot;--namespace production&quot;* ]]; then<br>   if [ -z &quot;$RELEASE_APPROVAL&quot; ]; then<br>     echo &quot;Production deploys need a release authorization.&quot; &gt;&amp;2<br>     exit 2   # exit 2 blocks the action; the message reaches Claude<br>   fi<br>fi<br>exit 0</pre><p>That single script is the difference between “Claude has kubectl access” (dangerous) and “Claude can prepare and stage a Kubernetes deployment, but a named release manager has to authorize the last step” (the actual policy most enterprises want). Team-level hooks live in .claude/settings.json in git; non-negotiable ones belong in centrally managed settings the platform team controls, which individual engineers can&#39;t switch off.</p><h3>The Jenkins pipeline itself</h3><p>This is the part that changes the least structurally and the most practically. Your Jenkinsfile stays a Jenkinsfile — deterministic stages, deterministic scripts — but a few stages now call Claude non-interactively for the judgment steps a script can’t do well: triaging a flaky test, writing a changelog, deciding whether a build failure looks real or flaky.</p><pre>pipeline {<br>  agent any<br>  stages {<br>    stage(&#39;Build&#39;) {<br>      steps { sh &#39;mvn -B clean verify&#39; }<br>    }<br>    stage(&#39;Triage on failure&#39;) {<br>      when { expression { currentBuild.result == &#39;FAILURE&#39; } }<br>      steps {<br>        sh &#39;&#39;&#39;<br>          claude -p &quot;Read the build log at target/build.log. Identify<br>          the most likely cause, say whether the failure looks flaky<br>          or real, and write a three-line summary.&quot; &gt;&gt; triage.md<br>        &#39;&#39;&#39;<br>      }<br>    }<br>    stage(&#39;Docker build &amp; push&#39;) {<br>      steps {<br>        sh &#39;docker build -t registry.acme.com/claims-service:${GIT_COMMIT} .&#39;<br>        sh &#39;docker push registry.acme.com/claims-service:${GIT_COMMIT}&#39;<br>      }<br>    }<br>    stage(&#39;Deploy: staging&#39;) {<br>      steps {<br>        sh &#39;helm upgrade --install claims-service ./chart --namespace staging --set image.tag=${GIT_COMMIT}&#39;<br>      }<br>    }<br>    stage(&#39;Verifier subagent: smoke test staging&#39;) {<br>      steps {<br>        sh &#39;&#39;&#39;<br>          claude -p &quot;Start against the staging namespace. Exercise the<br>          claims-status endpoint and the two nearest neighboring<br>          flows. Report what you ran and any behavior that doesn&#39;t<br>          match plan.md. Do not fix anything; report only.&quot; \<br>          --allowedTools &quot;Bash(kubectl *),Read&quot; &gt;&gt; verify.md<br>        &#39;&#39;&#39;<br>      }<br>    }<br>    stage(&#39;Deploy: production&#39;) {<br>      when { branch &#39;main&#39; }<br>      environment { RELEASE_APPROVAL = credentials(&#39;release-manager-approval&#39;) }<br>      steps {<br>        sh &#39;helm upgrade --install claims-service ./chart --namespace production --set image.tag=${GIT_COMMIT}&#39;<br>      }<br>    }<br>  }<br>}</pre><p>Notice what <em>doesn’t</em> change: branch protection still means nothing Claude writes reaches main without a PR and a human approval. Execution runs in a sandboxed Jenkins agent with short-lived, scoped credentials — no standing production access. The autonomy is <strong>tiered by environment</strong>: free rein in development, more oversight in staging, and a hard human gate before production, exactly like the production-gate.sh hook above enforces.</p><p>Rollback deserves the same rehearsal as any other pipeline stage. It should be a single command your agent (and your engineers) can run without ceremony, exercised regularly in staging — because Stage 6 below is going to call it under pressure, at 3 a.m., without a human in the loop.</p><h3>Midpoint checkpoint — the question every reviewer should be able to answer</h3><p>Stop for a second and ask this about your own production pipeline: <strong>if a hook script is deleted or disabled tomorrow, who finds out, and how fast?</strong></p><p>If the honest answer is “nobody, until something goes wrong,” you’ve just found the single highest-leverage fix available to you from this entire series — monitor your .claude/settings.json and hook files for unauthorized changes the same way you&#39;d monitor a firewall rule. It costs almost nothing to set up and it closes the one gap that makes every other control in this article theoretical rather than real.</p><h3>Stage 6 — Maintain: closing the loop on Kubernetes</h3><p>This is where the ADLC stops being “AI helps me code faster” and becomes an actual loop. So far, every stage started because a person prompted it. Maintain is different: <strong>a deterministic trigger invokes Claude with no human in the invocation path</strong>, and what it finds re-enters the pipeline as a fresh intent.md.</p><h3>Watching Kubernetes with control bands</h3><p>A platform engineer picks one metric with a stable baseline — post-deploy 5xx rate, pod restart count, p99 latency from your Kubernetes ingress — and writes a small, fully deterministic detection script against Prometheus (mean/standard-deviation over a rolling window, with response tiers configured, not hard-coded):</p><pre># bands.yaml<br>metric: claims_service_5xx_rate<br>baseline: rolling_30d<br>rules: western_electric<br>tiers:<br>  1sigma: { action: log }<br>  2sigma:<br>    action: diagnose<br>    tools: &quot;Read,Grep,Bash(kubectl logs *)&quot;<br>  3sigma:<br>    action: propose<br>    routes: [pull_request, &quot;runbook:rollback-deploy&quot;]</pre><p>At 1σ, the script just logs. At 2σ, it invokes Claude <em>read-only</em> to diagnose — pull pod logs, correlate with the last deploy, summarize. At 3σ, Claude may act, but only through pre-approved routes: opening a PR into the same review gate every other change goes through, or triggering a rollback runbook that was rehearsed and approved back in Stage 5.</p><p>Whatever Claude finds gets written as an intent.md, in exactly the format from Part 1 — the anomaly, the evidence, affected systems, open questions — and it flows into the pipeline like any other piece of work. A human still triages the queue: fix now, schedule, or dismiss. This is the moment the &quot;SDLC&quot; genuinely becomes a <em>loop</em> rather than a line.</p><h3>What to measure across Deploy and Maintain</h3><ul><li><strong>Leading indicator:</strong> time to first review on a PR (should fall to minutes); time from a Kubernetes control-band breach to an intent.md landing in the triage queue.</li><li><strong>Lagging indicator:</strong> defects caught before merge vs. escaping to production; the standard DORA metrics your CI/CD tooling already emits; repeat incidents of the same class, which should trend down as fixes turn into permanent evals from Part 2.</li></ul><h3>Diagram: the Jenkins pipeline with Claude gates</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*GJ4kd_OdlaP7CGhuG6Bw3A.png" /></figure><h3>Closing thoughts on the whole series</h3><p>Twenty years in, the thing I keep coming back to is that none of this removes engineering judgment — it relocates it. A senior engineer’s time used to go into writing boilerplate CRUD endpoints and chasing down flaky tests. In the ADLC, that time goes into writing a sharper spec.md, interrogating a plan.md before code exists, deciding what belongs in REVIEW.md, and being the named human behind the production gate. That&#39;s a better use of twenty years of experience, not a smaller one.</p><p>If you’re a fresher reading this series wondering where you fit: learn to read and write intent.md and plan.md as fluently as you&#39;d read a stack trace today. That&#39;s the new baseline skill, underneath whichever framework happens to be popular this year.</p><h3>Before you go — the one-week challenge</h3><p>Don’t just bookmark this series. Pick <strong>one</strong> thing from across all three parts and do it this week:</p><ul><li>No intent.md folder yet? Create it and write one, for real, on your next feature.</li><li>No plan.md discipline? Require it on your next PR and compare the review cycle time against your last five.</li><li>No hook behind your production gate? Write the twenty-line script from Stage 5 before your next release.</li></ul><p>Come back in a month and measure the difference with the metrics listed in each part. That comparison — not this article — is what actually convinces a skeptical team lead or a cautious CxO. Numbers from your own repo beat anyone else’s blog post every time, including this one.</p><h3>References and credits</h3><ul><li>Anthropic, <em>“The AI-Native SDLC Playbook,”</em> Claude blog, published August 21, 2026 — the primary source for the Deploy/Maintain stage structure, the REVIEW.md/hooks/control-band patterns, and the CI/CD and closing-the-loop concepts adapted throughout this series: <a href="https://claude.com/blog/the-ai-native-sdlc-playbook"><strong>https://claude.com/blog/the-ai-native-sdlc-playbook</strong></a></li><li>Anthropic, <em>“How Anthropic secures its AI-native software development lifecycle”</em> — <a href="https://claude.com/blog/how-anthropic-secures-its-ai-native-software-development-lifecycle">https://claude.com/blog/how-anthropic-secures-its-ai-native-software-development-lifecycle</a></li><li>Anthropic, <em>“How Claude Tag runs on-call for CI/CD at Anthropic”</em> — <a href="https://claude.com/blog/ai-ci-cd-on-call">https://claude.com/blog/ai-ci-cd-on-call</a></li><li>Claude Code documentation — Hooks reference: <a href="https://code.claude.com/docs/en/hooks">https://code.claude.com/docs/en/hooks</a></li><li>Claude Code documentation — GitHub Actions integration: <a href="https://code.claude.com/docs/en/github-actions">https://code.claude.com/docs/en/github-actions</a></li><li>Claude Code documentation — Settings reference: <a href="https://code.claude.com/docs/en/settings">https://code.claude.com/docs/en/settings</a></li><li>Claude Code documentation — Monitoring (OpenTelemetry): <a href="https://code.claude.com/docs/en/monitoring-usage">https://code.claude.com/docs/en/monitoring-usage</a></li></ul><p><em>All pipeline and hook code samples are illustrative, adapted for a Spring Boot/Maven/Jenkins/Kubernetes context, and not copied verbatim from Anthropic’s source material. All diagrams are original works created for this series and are not affiliated with or endorsed by Anthropic.</em></p><p><em>This concludes the 3-part series. Part 1: Plan &amp; Design · Part 2: Build &amp; Test · Part 3: Deploy &amp; Maintain (this article).</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=573374fb5353" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Building & Testing in the ADLC: Claude Code, Spring Boot, Maven and JUnit (Part 2 of 3)]]></title>
            <link>https://apurvsheth.medium.com/building-testing-in-the-adlc-claude-code-spring-boot-maven-and-junit-part-2-of-3-21d8668a17af?source=rss-a27130eabf4a------2</link>
            <guid isPermaLink="false">https://medium.com/p/21d8668a17af</guid>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[agentic-ai]]></category>
            <category><![CDATA[spring-boot]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[technology]]></category>
            <dc:creator><![CDATA[Apurv Sheth]]></dc:creator>
            <pubDate>Thu, 03 Sep 2026 02:01:02 GMT</pubDate>
            <atom:updated>2026-09-03T02:01:02.572Z</atom:updated>
            <content:encoded><![CDATA[<p><em>Part 2 of a 3-part series translating Anthropic’s AI-Native SDLC Playbook into a Spring Boot / React / Jenkins / Kubernetes stack. If you haven’t read Part 1, it covers Plan and Design — the </em><em>intent.md and </em><em>spec.md artifacts everything below assumes exist.</em></p><h3>Start here: one habit, disproportionate payoff</h3><p>Of everything in this three-part series, the single change with the best return on the least effort is this: <strong>stop letting Claude Code touch a file until it has written down its plan.</strong> That’s it. That one habit — plan mode, covered below — catches more expensive mistakes before they exist than any amount of post-hoc code review ever will.</p><p>Keep that claim in mind as you read the next section. By the end of it, you should be able to explain to a skeptical teammate exactly why a document that takes two minutes to read can save a day of rework — and you should be able to point to the specific line in a plan.md that would have caught your last production incident.</p><h3>Recap in one line</h3><p>By the time engineering picks up work in the ADLC, there’s already an accepted spec.md sitting in the repo. Build doesn&#39;t start from a Jira ticket and a blank IDE — it starts from a document an agent and a product owner already agreed on.</p><p>This article covers Stage 3 (<strong>Build</strong>) and Stage 4 (<strong>Test</strong>) — the two stages where most Spring Boot and Java teams will feel the biggest day-to-day change.</p><h3>Stage 3 — Build: nothing gets implemented without a plan</h3><h3>Plan mode as the default starting point</h3><p>The single habit that changes the most for a Java/Spring Boot engineer is this: <strong>you don’t let Claude Code start writing files immediately.</strong> You start every session in <a href="https://code.claude.com/docs/en/permission-modes">plan mode</a>, where Claude can read your codebase but cannot edit it, hand it the spec.md from Design, and let it interview you.</p><p>In a traditional workflow, how a change is going to be made — which classes, which layers, which tests — lives in the engineer’s head, or at best a ticket comment nobody else reads. The first thing a reviewer sees is the finished diff, by which point rework is expensive. Plan mode forces that decision to happen <em>before</em> code exists, when changing course just means editing a document.</p><p><strong>A worked plan for our claims-status example</strong>, targeting a Spring Boot service:</p><pre># Plan: claims status self-service (from intent.md 2026-06-02)<br><br>## Files that change<br>portal/src/claims/StatusPanel.tsx (new, React)<br>claims-service/src/main/java/com/acme/claims/controller/StatusController.java (new)<br>claims-service/src/main/java/com/acme/claims/service/StatusService.java (new)<br>claims-service/src/test/java/com/acme/claims/StatusControllerTest.java (new)<br><br>## Order of work<br>1. Add GET /api/claims/{id}/status behind existing JWT auth filter.<br>2. StatusService calls claims-core API with 50rps rate-limit awareness.<br>3. React StatusPanel consumes the endpoint and renders state/date.<br>4. Wire the panel into the existing portal nav.<br><br>## Risks<br>claims-core rate-limits at 50 rps; StatusService must cache<br>per-claim responses for 60s to avoid tripping it under load.<br><br>## Proof<br>StatusControllerTest covers all four claim states (submitted,<br>in-review, approved, denied); a React screenshot test matches<br>the approved Claude Design mock.</pre><p>Interrogate this the way you’d interrogate a junior engineer’s design doc: what could this break, which step is riskiest, what did Claude choose <em>not</em> to do? Iterate until someone who’s never seen the conversation could implement the change from plan.md alone. Then commit it — it becomes part of the audit trail, and later, the review stage checks the final diff against it.</p><h3>CLAUDE.md: institutional knowledge as a file, not tribal memory</h3><p>Every Spring Boot repo accumulates conventions that live in senior engineers’ heads: <em>we always use </em><em>BigDecimal for money, never </em><em>double; the legacy </em><em>v1 package is frozen; don&#39;t bump Spring Boot minor versions without platform-team sign-off.</em> In the ADLC, this becomes a version-controlled file Claude reads at the start of every session: <strong>CLAUDE.md</strong>.</p><pre># claims-service<br><br>## Commands<br>- Build: mvn clean install<br>- Test: mvn test (unit), mvn verify -Pintegration (needs Testcontainers/Docker)<br>- Lint: mvn spotless:check (runs in CI; fix locally before pushing)<br><br>## Conventions<br>- Java 21, Spring Boot 3.3. No new Lombok in new modules.<br>- Money is always BigDecimal, never double or float.<br>- Every REST controller needs a matching @SpringBootTest in src/test.<br>- DTOs live in api/dto; never expose JPA entities directly.<br><br>## Architecture<br>- controller/ → REST layer, service/ → domain logic,<br>  repository/ → Spring Data JPA, client/ → external API adapters.<br>- Kafka event schemas are defined in schemas/; never hand-edit<br>  the generated Avro classes.<br><br>## Things Claude gets wrong<br>- Do not bump Spring Boot or dependency versions; platform team owns them.<br>- The legacy v1/ controller package is frozen; new work goes in v2/.</pre><p>Run /init in the repo to get a starting version, trim it to what a new joiner actually needs on day one, and check it into git at the repo root so changes to it are reviewed like code. The rule of thumb that keeps it useful: <strong>when Claude makes the same mistake twice, the correction goes into </strong><strong>CLAUDE.md.</strong></p><h3>Skills and hooks: advisory vs. deterministic guardrails</h3><p>Two different mechanisms enforce standards during Build, and it’s worth being precise about the difference:</p><ul><li>A <strong>skill</strong> (a SKILL.md file under .claude/skills/) is <em>advisory</em>. It makes Claude likely to follow a policy — say, an API security standard — while it writes code. Nothing forces compliance.</li><li>A <strong>hook</strong> is <em>deterministic</em>. It’s a script that runs before Claude takes an action and can allow, ask, or block it outright.</li></ul><p>For a Spring Boot API, a security skill might look like:</p><pre>---<br>name: secure-api-review<br>description: Apply the API security standard whenever creating or<br>  modifying a Spring Boot REST endpoint.<br>---<br># Secure API review<br><br>1. Authentication: every endpoint requires the existing JWT filter;<br>   no unauthenticated routes outside /actuator/health.<br>2. Input validation: validate @RequestBody payloads with Bean<br>   Validation (@Valid) and reject unknown fields (FAIL_ON_UNKNOWN_PROPERTIES).<br>3. Audit: every state-changing endpoint publishes an audit event<br>   with actor, action, entity ID and timestamp.<br>4. PII: fields tagged @Pii in the DTO must never appear in logs.</pre><p>Where a policy must hold <em>without exception</em> — say, “never edit files under v1/ without a change ticket&quot; — back it with a hook, not just a skill. Skills make violations rare; hooks make them close to impossible.</p><h3>Parallel sessions across a Spring Boot + React monorepo</h3><p>Because the front end (React) and back end (Spring Boot) are usually separable pieces of work, this is a natural place to run <strong>parallel Claude Code sessions in separate git worktrees</strong> — one session on feature-claims-status-api, another on feature-claims-status-ui, each in its own worktree so they don&#39;t collide on files. Two or three concurrent sessions is a sensible ceiling; the limit isn&#39;t how many Claude can run, it&#39;s how many an engineer can actually review.</p><h3>Midpoint checkpoint — the one line worth memorizing</h3><p>If you take nothing else from the Build stage, take this: <strong>“if a test fails, fix the code, not the test.”</strong> That single instruction, sitting in CLAUDE.md, is what separates an agent that&#39;s genuinely productive from one that&#39;s quietly hollowing out your test suite to look productive.</p><p>Hold onto that line. The next section shows you exactly how to enforce it structurally — not just write it down and hope.</p><h3>Stage 4 — Test: give Claude a feedback loop it can run itself</h3><p>The single biggest lever in the Test stage is simple to state and easy to under-invest in: <strong>give the agent a way to check its own work before a human ever sees it.</strong> For a Maven/JUnit project, that’s usually already sitting right there.</p><h3>Wiring the feedback loop</h3><ol><li>Make sure mvn test and mvn verify each exit non-zero on failure — most Maven/Surefire/Failsafe setups already do this.</li><li>List both commands in CLAUDE.md&#39;s Commands section, with an example of healthy output.</li><li>Give Claude a <em>quantifiable</em> target, not a vibe: “all tests in StatusControllerTest pass,&quot; not &quot;make sure it works.&quot;</li><li><strong>For bug fixes specifically, write the failing test first.</strong> Ask Claude to reproduce the bug as a JUnit test, confirm it fails for the expected reason, and commit that test <em>before</em> asking Claude to fix the code — with a hook blocking edits to the test file during the fix. A test that pre-dates the fix, and that the agent couldn’t quietly rewrite, is real proof the bug is gone.</li><li>For the React side, close the loop visually: give Claude a browser or screenshot tool, hand it the Claude Design mock from Part 1, and let it iterate — implement, screenshot, compare, adjust. Two or three rounds is normal.</li></ol><pre>## Verifying your work<br><br>- Build: mvn clean install (must finish with &quot;BUILD SUCCESS&quot;)<br>- Test:  mvn test (all green; never skip or delete a failing test)<br>- Lint:  mvn spotless:check (zero violations)<br><br>Run all three before reporting any task complete, and paste the<br>output. If a test fails, fix the code — never the test.</pre><p>This is the practice that keeps Claude from marking its own homework. The last line matters more than it looks: an agent under pressure to finish a task will sometimes “fix” a failing test by loosening its assertion. A hook that blocks edits to *Test.java files during a fix task closes that loophole structurally, rather than relying on the agent&#39;s good judgment.</p><h3>Continuous evals in Jenkins</h3><p>Unit tests verify the <em>code</em>. <strong>Evals</strong> verify the <em>agent’s configuration</em> — your CLAUDE.md, your skills, your hooks — the same way tests verify a class. Every time you change any of those, you want a regression check that says &quot;does Claude still do the work to the same standard,&quot; not just &quot;does the existing code still compile.&quot;</p><p>The pattern: collect 20–50 real tasks from recent work, each with its expected outcome, and run them non-interactively whenever CLAUDE.md or .claude/** changes — plus on a nightly schedule.</p><pre># Jenkinsfile (declarative, agent-evals stage)<br>pipeline {<br>  agent any<br>  triggers { cron(&#39;0 2 * * *&#39;) }<br>  stages {<br>    stage(&#39;Agent evals&#39;) {<br>      when {<br>        anyOf {<br>          changeset &quot;CLAUDE.md&quot;<br>          changeset &quot;.claude/**&quot;<br>          triggeredBy &#39;TimerTrigger&#39;<br>        }<br>      }<br>      steps {<br>        sh &#39;npm install -g @anthropic-ai/claude-code&#39;<br>        sh &#39;&#39;&#39;<br>          for eval in evals/*.json; do<br>            claude -p &quot;$(jq -r &#39;.prompt&#39; $eval)&quot; \<br>              --allowedTools &quot;Read,Edit,Bash(mvn test)&quot; \<br>              --output-format json &gt; result.json<br>            ./evals/check.sh &quot;$eval&quot; result.json<br>          done<br>        &#39;&#39;&#39;<br>      }<br>    }<br>  }<br>}</pre><p>Every production incident earns its own eval, written by the team that owned it, and stays in the suite permanently as a regression test — the same discipline good teams already apply to flaky-test postmortems, just extended to cover the agent’s configuration too.</p><h3>What to measure coming out of Build &amp; Test</h3><ul><li><strong>Leading indicator:</strong> share of changes that merge from the first implementation pass; first-pass CI success rate for agent-authored changes in Jenkins.</li><li><strong>Lagging indicator:</strong> rework cycles per change (from PR metadata); how often the merged diff still matches the committed plan.md; the eval pass-rate trend over time.</li></ul><h3>Diagram: stack-to-stage mapping</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Z2rI7LI2_YFTggewIs_6yQ.png" /></figure><p><em>Original diagram created for this series.</em></p><h3>Try this before Part 3</h3><p>Open your most recently merged PR in Bitbucket or GitHub. Ask yourself honestly: was there a plan.md, or did the diff just appear? If the answer is &quot;just appeared,&quot; you now have a concrete, low-risk experiment for next sprint — require plan mode for one feature, and compare the rework rate against your last five PRs that skipped it. That comparison is worth more than anything in this article on its own.</p><h3>Coming up in Part 3</h3><p>We close the loop: how Claude reviews and receives review on pull requests in Bitbucket or GitHub, how a Jenkins pipeline runs Claude non-interactively with hooks acting as production approval gates, how the built image actually lands on Kubernetes, and how a breached metric in production writes a brand-new intent.md that restarts the whole cycle.</p><h3>References and credits</h3><ul><li>Anthropic, <em>“The AI-Native SDLC Playbook,”</em> Claude blog, published August 21, 2026 — source for the Build/Test stage structure, the CLAUDE.md, skills, hooks and continuous-evals patterns adapted here: <a href="https://claude.com/blog/the-ai-native-sdlc-playbook"><strong>https://claude.com/blog/the-ai-native-sdlc-playbook</strong></a></li><li>Claude Code documentation — Memory (CLAUDE.md): <a href="https://code.claude.com/docs/en/memory">https://code.claude.com/docs/en/memory</a></li><li>Claude Code documentation — Hooks: <a href="https://code.claude.com/docs/en/hooks">https://code.claude.com/docs/en/hooks</a></li><li>Claude Code documentation — Worktrees: <a href="https://code.claude.com/docs/en/worktrees">https://code.claude.com/docs/en/worktrees</a></li><li>Claude Code documentation — Sub-agents: <a href="https://code.claude.com/docs/en/sub-agents">https://code.claude.com/docs/en/sub-agents</a></li></ul><p><em>All code samples are illustrative, adapted for a Spring Boot/Maven/JUnit context, and not copied verbatim from Anthropic’s source material.</em></p><p><em>Next: Part 3 — Deploy &amp; Maintain: Bitbucket/GitHub PR review, Jenkins pipelines, Kubernetes, and closing the loop.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=21d8668a17af" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[From SDLC to ADLC: Rewiring Software Delivery for the Agentic Era (Part 1 of 3)]]></title>
            <link>https://apurvsheth.medium.com/from-sdlc-to-adlc-rewiring-software-delivery-for-the-agentic-era-part-1-of-3-0185ef5b4567?source=rss-a27130eabf4a------2</link>
            <guid isPermaLink="false">https://medium.com/p/0185ef5b4567</guid>
            <category><![CDATA[spring-boot]]></category>
            <category><![CDATA[technology]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[agentic-ai]]></category>
            <category><![CDATA[ai]]></category>
            <dc:creator><![CDATA[Apurv Sheth]]></dc:creator>
            <pubDate>Tue, 01 Sep 2026 02:01:08 GMT</pubDate>
            <atom:updated>2026-09-01T02:01:08.413Z</atom:updated>
            <content:encoded><![CDATA[<p><em>A practitioner’s guide for teams running Spring Boot, Java, Maven, React, Bitbucket/GitHub, Jenkins, JUnit and Kubernetes — mapped against Anthropic’s AI-native SDLC playbook.</em></p><h3>Open with this question</h3><p>Here’s a question worth sitting with before you read another line: <strong>if an AI agent can write your next Spring Boot endpoint in fifteen minutes, what exactly is your team still spending three days reviewing?</strong></p><p>That’s not rhetorical. Write down your actual answer. By the end of this three-part series, you’ll have a concrete framework to check that answer against — and most teams find the honest answer is uncomfortable. Not because their review process is bad, but because it was built for a world where writing the code was the slow part. That world is ending, stage by stage, whether your process has caught up or not.</p><h3>Why I’m writing this</h3><p>Twenty-plus years ago, my first “architecture review” was a printed sequence diagram and a room full of skeptical seniors. Since then I’ve watched Waterfall give way to Agile, Agile give way to DevOps, and DevOps give way to platform engineering. Each shift moved the bottleneck somewhere else in the pipeline.</p><p>We’re in the middle of the next shift, and it’s the biggest one yet. Anthropic recently published <strong>The AI-Native SDLC Playbook</strong>, a stage-by-stage guide to running the software development lifecycle with Claude embedded at every step. I’d call what it describes the <strong>ADLC — Agentic Development Lifecycle</strong>: the same six stages we’ve always had (Plan, Design, Build, Test, Deploy, Maintain), but restructured as a closed loop where an AI agent does a large share of the mechanical work and humans concentrate their judgment at a small number of gates.</p><p>This series translates that playbook into a stack most enterprise teams already run day to day: <strong>Spring Boot + Java + Maven</strong> on the backend, <strong>React</strong> on the front end, <strong>Bitbucket or GitHub</strong> for source control, <strong>Jenkins</strong> for CI/CD, <strong>JUnit</strong> for testing, and <strong>Kubernetes</strong> for runtime. If you’re a fresher trying to understand where AI actually fits into a real SDLC, or a mid-level engineer wondering how your Jenkinsfile is about to change, this is written for you.</p><blockquote><em>Part 1 (this article): what ADLC is, and how the </em><strong><em>Plan</em></strong><em> and </em><strong><em>Design</em></strong><em> stages work. <br>Part 2: </em><strong><em>Build</em></strong><em> and </em><strong><em>Test</em></strong><em> — Claude Code, Spring Boot, Maven, JUnit. <br>Part 3: </em><strong><em>Deploy</em></strong><em> and </em><strong><em>Maintain</em></strong><em> — Bitbucket/GitHub PRs, Jenkins pipelines, Kubernetes, and closing the loop.</em></blockquote><h3>The core idea: code stopped being the bottleneck</h3><p>For most of the SDLC’s history, writing code was the slowest, most expensive part of building software. Every process we invented — PRDs, story-point estimation, architecture sign-off, staged QA gates — existed to protect that scarce, expensive resource: developer time spent typing code.</p><p>Agentic coding tools have broken that assumption. A well-scoped Claude Code session can produce a working Spring Boot service or a React component tree in minutes, not days. When the build phase collapses from days to hours, three things happen, almost immediately, in any organization that doesn’t adapt:</p><ol><li><strong>The bottleneck moves.</strong> It shifts to the stages either side of Build — Plan, Design, Review, and Deploy — which still run at human speed.</li><li><strong>Old controls stop matching reality.</strong> Line-by-line human code review made sense when a person wrote every line. It doesn’t scale when an agent produces most of the diff.</li><li><strong>Governance gets more expensive, not less.</strong> Exceptions still route through weekly change boards while the volume of change goes up.</li></ol><p>Think about your own Spring Boot repo. If Claude Code can generate a new REST endpoint, its service layer, and its JPA repository in fifteen minutes, but your Jenkins pipeline still waits three days for a human code reviewer and a security sign-off meeting that happens every other Tuesday, you haven’t sped anything up — you’ve just moved the queue.</p><p>The ADLC’s answer isn’t “remove the humans.” It’s “move the humans to the decisions that actually need judgment, and let the agent do the rest inside guardrails that are enforced as code.”</p><h3>What actually changes, stage by stage</h3><p>Stage Traditional SDLC ADLC (AI-native) <strong>Plan</strong> Requirements gathered by committee, written up by hand over days or weeks Claude captures intent directly from the originator as a version-controlled intent.md <strong>Design</strong> Analysts write requirements, designers separately turn them into a spec Requirements and design happen in one working session with Claude, constrained by encoded standards <strong>Build</strong> Code and tests hand-written; docs written after the fact Claude Code plans, writes code and tests together; institutional knowledge lives in CLAUDE.md and skills <strong>Test</strong> QA gates sit at stage boundaries Continuous, automated evals run through implementation, inside Jenkins <strong>Deploy</strong> Humans review every line; governance happens in inconsistent review cycles Layered agentic review + human review reserved for higher-risk or regulated code; hooks enforce approval gates <strong>Maintain</strong> Humans watch production and react to alerts Agents monitor Kubernetes and metrics, diagnose breaches, and write a new intent.md to restart the loop</p><p>The thread running through every row on the right is <strong>the committed artifact</strong>. Each stage ends by writing a file to version control — intent.md, spec.md, plan.md, the diff and its tests, the pull request and its review findings, the incident record — and the next stage starts by reading it. That chain of commits <em>is</em> the audit trail: who asked for what, what the agent produced, and who signed off.</p><p>This matters enormously for regulated or enterprise teams. Nobody is asking you to trust an agent blindly. You’re asking it to leave a paper trail that’s actually more complete than what most human-run SDLCs produce today.</p><h3>Pause here — a quick self-check</h3><p>Before you keep reading, take thirty seconds and answer this for your own team: <strong>which of your six stages currently has no committed artifact at all?</strong> For most teams it’s Plan — ideas live in Slack threads and standup notes, not in a file anyone can point to six months later.</p><p>That gap is exactly where Stage 1 of the ADLC starts. Keep your answer in mind as you read the next section — you’ll be able to map it directly onto your own repo by the time you finish this article.</p><h3>Stage 1 — Plan: capturing intent as intent.md</h3><p>In a traditional SDLC, an idea has to survive backlog grooming, story-point estimation, and a refinement meeting before an engineer ever looks at it. By the time it reaches the team, it’s several translations removed from what the person who had the idea actually meant.</p><p>In the ADLC, the originator — a product owner, a support lead, even an on-call engineer reacting to an incident — brainstorms directly with Claude. Claude asks the questions an analyst would ask (scope, users, constraints, success criteria) and writes the outcome as a markdown file called <strong>intent.md</strong>, committed straight into the repo.</p><p>For a Spring Boot / React product, the simplest home for this is an intent/ folder inside the same repository as the code it will eventually change. That keeps the artifact chain — intent → spec → plan → diff — next to the code it produced, and it means your existing Bitbucket or GitHub repo (and its access controls) is the only new piece of infrastructure you need.</p><p><strong>A worked example</strong>, adapted to a claims-status feature on a Spring Boot backend:</p><pre># Intent: claims status self-service<br>Author: A. Sheth (claims operations). Status: draft.</pre><pre>## Problem<br>Customers call the contact center to ask where their claim is.<br>Handlers spend roughly a third of call time on status-only queries.</pre><pre>## Proposed outcome<br>Customers see claim status, next step and expected date in the<br>React portal, backed by a new read endpoint on claims-service.</pre><pre>## Affected users and systems<br>Claims handlers, portal team (React), claims-service (Spring Boot),<br>claims-core API.</pre><pre>## Constraints<br>No new PII exposed in the portal session. Existing JWT auth only.</pre><pre>## Open questions<br>Do third-party loss adjusters need access too?</pre><p>Every contributor doesn’t need git experience to do this — a connector between Claude and your Bitbucket or GitHub org lets Claude commit intent.md on their behalf. A technical lead just needs to stand up the folder once and agree on a template.</p><p><strong>What to measure:</strong> time from first conversation to a committed intent.md (read straight from git history), and the &quot;survival rate&quot; — the share of intent.md files the product owner actually accepts into Design rather than closing. Expect the elicitation cycle to collapse from weeks to hours.</p><h3>Stage 2 — Design: requirements and design in one session</h3><p>Traditionally, requirements and design are two separate phases owned by two separate roles: an analyst formalizes the idea, then a designer parses that document back into a UI and technical design. The split exists for accountability, but it’s slow and lossy — information degrades at every handoff.</p><p>In the ADLC, both phases collapse into a single prompted session. The product owner opens Claude with the accepted intent.md attached, alongside the organization&#39;s <strong>skills</strong> — encoded, versioned standards for brand, security, compliance and UX (Claude Code&#39;s <a href="https://code.claude.com/docs/en/skills">skills</a> feature is built exactly for this). Claude produces a requirements-and-design spec constrained by those skills, with concerns flagged inline rather than discovered three weeks later in a security review.</p><p>For the React front end specifically, this is where <strong>Claude Design</strong> earns its keep: the product owner mocks the screen up directly from intent.md, iterates on it conversationally, and exports it toward Claude Code to build against — so the eventual React component tree starts from an agreed visual spec instead of a Figma file nobody on engineering has opened yet.</p><p><strong>The prompt pattern</strong> looks like this:</p><pre>Read the attached intent.md and produce a requirements and design<br>spec for integrating it into our existing claims-service (Spring<br>Boot) and portal (React) codebases. Apply the skills available to<br>you so the plan conforms to our brand guidelines, security policies<br>and UX standards. Document the result as spec.md, ready to hand to<br>the engineering team. Flag clearly any areas where policies<br>conflict or cannot be fully satisfied.</pre><p>The product owner reviews the resulting spec.md against two questions: does it solve the stated problem, and are the open questions from intent.md answered or explicitly carried forward? Flagged concerns get resolved with the relevant policy owner <em>before</em> engineering ever sees the spec — which is the opposite of how most Spring Boot teams currently discover security requirements (usually: after the PR is already open).</p><p>Once approved, spec.md is committed alongside intent.md. That committed pair — what was asked for, and what was decided — is what triggers Stage 3: Build, which we cover in Part 2.</p><p><strong>What to measure:</strong> elapsed time between the intent.md commit and the spec.md commit (two git timestamps), and requirements rework after build starts — counted as spec.md commits dated <em>after</em> the first plan.md commit for the same change.</p><h3>Where this leaves a fresher or mid-level engineer</h3><p>If you’re early in your career, the Plan and Design stages might feel like “not my job” — historically they were owned by product and design, not engineering. That’s changing. Because these artifacts are markdown files living in the same repo as your Spring Boot code, engineers are increasingly expected to <em>read</em> intent.md and spec.md before touching Claude Code, the same way you&#39;d read a JIRA ticket today — except this ticket is richer, versioned, and was written in partnership with an AI that already checked it against your org&#39;s security and UX rules.</p><p>The practical takeaway for Part 1: <strong>before you open your IDE, check whether there’s an accepted </strong><strong>spec.md for the work you&#39;re about to do.</strong> If there isn&#39;t, that&#39;s the gap to close first — not a reason to start writing code from a Jira one-liner.</p><h3>Diagram: the six-stage ADLC loop</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1022/1*hz2IkQSf9fuC-dMyfUBYYw.png" /></figure><p><em>Original diagram created for this series, inspired by the stage structure described in Anthropic’s AI-Native SDLC Playbook.</em></p><h3>Before you close this tab</h3><p>Go check one repo you own right now. Does an intent/ folder — or anything equivalent — exist? If not, that&#39;s a fifteen-minute setup task, not a quarter-long initiative. The teams that get the most out of Part 2 and Part 3 of this series are the ones who have <em>something</em> committed for Plan and Design before they start automating Build. Don&#39;t skip the foundation to get to the exciting part.</p><h3>Coming up in Part 2</h3><p>We move into the stage most engineers care about most: <strong>Build</strong>. I’ll walk through Claude Code’s plan mode against a real Spring Boot service, what a good CLAUDE.md looks like for a Java/Maven project, how skills and hooks act as guardrails during implementation, and how JUnit fits into a feedback loop the agent can run on its own before a human ever sees the diff.</p><h3>References and credits</h3><ul><li>Anthropic, <em>“The AI-Native SDLC Playbook,”</em> Claude blog, published August 21, 2026 — the primary source for the stage structure, intent.md/spec.md/plan.md artifact chain, and terminology used throughout this series: <a href="https://claude.com/blog/the-ai-native-sdlc-playbook"><strong>https://claude.com/blog/the-ai-native-sdlc-playbook</strong></a></li><li>Claude Code documentation — Skills: <a href="https://code.claude.com/docs/en/skills">https://code.claude.com/docs/en/skills</a></li><li>Claude Code documentation — Permission modes (plan mode): <a href="https://code.claude.com/docs/en/permission-modes">https://code.claude.com/docs/en/permission-modes</a></li><li>Claude Design (beta): <a href="https://claude.com/product/design">https://claude.com/product/design</a></li></ul><p><em>All diagrams in this series are original works created for this article and are not sourced from or affiliated with Anthropic’s published materials.</em></p><p><em>Next: Part 2 — Build &amp; Test: Claude Code, Spring Boot, Maven and JUnit in the ADLC.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=0185ef5b4567" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[SDD Across Microservices: The Hard Problem Nobody Talks About]]></title>
            <link>https://apurvsheth.medium.com/sdd-across-microservices-the-hard-problem-nobody-talks-about-d041bfb87b75?source=rss-a27130eabf4a------2</link>
            <guid isPermaLink="false">https://medium.com/p/d041bfb87b75</guid>
            <category><![CDATA[java]]></category>
            <category><![CDATA[python]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[ai]]></category>
            <dc:creator><![CDATA[Apurv Sheth]]></dc:creator>
            <pubDate>Thu, 18 Jun 2026 02:31:00 GMT</pubDate>
            <atom:updated>2026-06-18T02:31:00.798Z</atom:updated>
            <content:encoded><![CDATA[<p><em>Single-repo tutorials make SDD look easy. Here’s what happens when your feature spans five services, three repos, and two teams — and how I’m solving it.</em></p><p>Let me start with a confession: the first two posts in this series made SDD look cleaner than it actually is.</p><p>I described a workflow — propose, apply, archive — that works beautifully in a single repository. And it does. If you have a monolith or a monorepo, stop reading and go install OpenSpec right now. It’ll change your life and I’ll see you in the comments.</p><p>But here’s the reality of where I actually work: a microservices architecture. Five services, four repositories, two squads, one shared message bus, and a very strong opinion from the team lead that we do not introduce inter-service coupling in our specs.</p><p>That’s where the tutorials end and the real engineering starts.</p><h3>The Problem, Precisely Stated</h3><p>SDD works by giving the AI a spec to work against. The spec lives in the repository. The AI reads it, generates code, checks against it, and archives it.</p><p>In a single repo, this is elegant. The spec knows everything about the system because <em>everything about the system is in the same place</em>.</p><p>In a microservices architecture, each service is its own bounded context. The auth service doesn’t know about the order service’s data model. The notification service doesn’t know about the auth service’s session handling. This is by design — it’s the whole point of microservices.</p><p>But features don’t respect service boundaries.</p><p>A “user account deletion” feature might touch: the auth service (delete credentials), the orders service (anonymise historical orders), the notification service (cancel subscriptions), the user profile service (delete profile data), and a data-export service (generate a GDPR-compliant export before deletion). That’s five services. Five repositories. Five separate spec contexts.</p><p>The naive approach: write a separate proposal for each service and coordinate manually. I’ve tried this. It works until it doesn’t — and it usually doesn’t around the time you discover that two services made incompatible assumptions about what “deleted” means.</p><h3>What’s Actually Possible Today</h3><p>I want to be honest about the current state of tooling here, because I’ve seen blog posts that oversell it.</p><p>Neither OpenSpec nor SpecKit has a native multi-repo solution. OpenSpec’s documentation acknowledges this directly and mentions “we’re building deeper team features for complex cases: large codebases, multi-repo systems, microservices.” That’s a roadmap item, not a shipped feature.</p><p>What both tools <em>do</em> provide are building blocks you can compose into a workable pattern. Here’s what I’ve pieced together.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*r_IEVO7lqxDexTkp0weN5A.png" /><figcaption><strong>SubAgents running in parallel</strong> — showing how three isolated contexts converge into a single verified merge.</figcaption></figure><h3>The Pattern I’ve Settled On</h3><h3>Layer 1: The Shared Intent Document</h3><p>Before any service-level proposal is written, I create a shared intent document that lives outside any service repository — in a shared /architecture repo, in a Confluence page, wherever the team stores cross-cutting concerns.</p><p>This document answers one question: <em>What is this feature doing from a user perspective, what are the service boundaries it crosses, and what are the contracts between services?</em></p><p>It is not a spec. It does not go into any GIVEN/WHEN/THEN format. It is a <em>brief</em> — two pages max — that establishes shared vocabulary and prevents two squads from making incompatible assumptions.</p><p>Writing this document together (human-to-human, not AI-assisted) is the most valuable hour you’ll spend on a cross-service feature. It surfaces the assumptions before they become bugs.</p><h3>Layer 2: Per-Service Proposals with Explicit Cross-Service Contracts</h3><p>Once the shared intent exists, each service team writes their own OpenSpec proposal — in their own repository, against their own source-of-truth spec.</p><p>The key discipline: each proposal must explicitly document its <em>interface with the outside world</em>. What events does this service publish? What events does it consume? What API contracts does it promise? What does it assume about the data it receives?</p><p>These interface contracts are the seams between services. They go in a contracts/ directory within each service&#39;s spec folder.</p><p>When the auth service proposal says “ADDED: publishes user.deleted event with schema {userId: uuid, timestamp: ISO8601, reason: string}&quot;, and the orders service proposal says &quot;ADDED: consumes user.deleted event, anonymises matching orders&quot;, those two contracts can be reviewed together before either service writes a line of code.</p><p>This is where most cross-service bugs live — in the gap between what one service <em>expects</em> to publish and what another service <em>expects</em> to receive. Making this explicit in the spec catches it before implementation.</p><h3>Layer 3: Git Worktrees and SubAgents for Parallel Work</h3><p>Here’s where it gets genuinely interesting.</p><p>OpenSpec recently added support for a workflow using Git Worktrees and SubAgents — a pattern that enables parallel feature development across service boundaries.</p><p>The idea: check out multiple branches simultaneously in separate directories using git worktree. Then use SubAgents (AI agents running in isolated contexts) to implement each service&#39;s changes in parallel.</p><pre># From your main service directory<br>git worktree add ../auth-feat-delete feat/user-deletion-auth<br>git worktree add ../orders-feat-delete feat/user-deletion-orders<br>git worktree add ../notify-feat-delete feat/user-deletion-notify</pre><p>Each worktree gets its own SubAgent. Each SubAgent reads only the spec for <em>its</em> service — crucially, it doesn’t have access to the other services’ code or specs. This respects the bounded context principle.</p><p>Each SubAgent runs /opsx:verify before its changes are merged. The source-of-truth spec for each service stays consistent.</p><p>The practical result: what used to take three sequential implementation sessions (do auth, then orders, then notify) now runs in parallel. For a five-service feature, that’s a meaningful cycle-time reduction.</p><p>The caveat, which I want to be clear about: <strong>you still have to coordinate the merges manually</strong>. OpenSpec doesn’t know that the auth service’s implementation needs to be merged before the orders service’s migration runs. That dependency graph is still your responsibility as the developer. This is not a solved problem.</p><h3>The AGENTS.md File: The Secret Weapon</h3><p>One tool that makes this whole pattern work is something OpenSpec calls AGENTS.md — a file the project describes as &quot;the README for robots.&quot;</p><p>Unlike your human-facing README, AGENTS.md tells the AI <em>how to behave in this repository</em>. It specifies: how to read the project structure, which patterns to follow, what conventions are in use, and — critically — what to read before starting any task.</p><p>For a microservices project, AGENTS.md becomes the place you encode cross-service awareness without putting it in the spec itself. Something like:</p><pre>## Cross-service context<br>Before writing any code that publishes or consumes events, <br>read contracts/events.md in this repo and the shared <br>architecture/service-contracts.md document.</pre><pre>## This service&#39;s responsibilities<br>This service owns: user credential storage and authentication.<br>This service does NOT own: user profiles, order history, notifications.</pre><p>This guidance stays with the repository permanently. Every new session, every new agent, reads it first. It’s the institutional memory that doesn’t disappear when the context window fills up.</p><h3>The Compliance Dimension</h3><p>One more angle worth addressing: compliance and audit.</p><p>In regulated industries — I know some of you work in fintech, healthcare, insurance — the question isn’t just “did we build the right thing” but “can we prove we built it according to documented requirements.”</p><p>SDD handles this naturally. Every feature has a proposal that was reviewed and approved before implementation. Every implementation was verified against the spec. The archive creates a permanent, version-controlled record of: what the requirement was, when it was approved, and what the implementation was.</p><p>This is genuinely useful for audit. I’ve been in post-incident reviews where reconstructing “what were the requirements for this feature” took half a day of digging through Jira tickets, Confluence pages, and Slack threads. With SDD, the proposal.md <em>is</em> the requirements document, and it lives in the same git history as the code that implements it.</p><p>For multi-service features, the pattern I described above produces proposals in each service repository. A compliance reviewer can pull the proposals from each service repo, see how they reference the shared intent document, and trace the full feature lineage.</p><p>It’s not perfect — it still requires discipline to write proposals that are genuinely descriptive rather than perfunctory. But the structure is there.</p><h3>What SDD Across Services Still Can’t Do</h3><p>I want to close with honesty about the limits, because I think the conversation in the industry is getting a bit breathless.</p><p><strong>Automatic cross-service contract validation</strong> — Tools don’t yet automatically check that two services’ contracts are compatible. You can review them together manually, but there’s no tooling equivalent of a type checker that runs across service boundaries. This is the biggest gap.</p><p><strong>Spec synchronization during parallel implementation</strong> — If two agents are implementing changes to two services simultaneously, and one of them discovers something that requires a contract change, there’s no mechanism to pause the other agent and update its spec. This coordination still happens in your head.</p><p><strong>Brownfield adoption at scale</strong> — Getting spec coverage on an existing large system is genuinely hard. You can’t generate specs retroactively for all existing behaviour (the tools acknowledge this). You adopt SDD incrementally, as you touch existing code. For large legacy systems, you’ll have significant portions of the codebase that are spec-dark for a long time.</p><h3>Where I’ve Landed</h3><p>After three months of applying this pattern, here’s my honest summary:</p><p>SDD works. Not perfectly, not magically, but it works. The discipline of writing a proposal before implementation has caught more design problems early than any review process I’ve used before.</p><p>For single-repo or monorepo projects, just go use OpenSpec. The overhead is low, the benefits are immediate, and the community is active enough that problems get solved quickly.</p><p>For microservices, adopt SDD per-service first. Get the discipline working in each bounded context before you try to coordinate across them. The cross-service patterns I’ve described are genuine improvements, but they require a team that already understands SDD at the service level.</p><p>The shared intent document pattern — the human-written brief that establishes contracts before any AI gets involved — is the single most impactful thing I’ve added to my workflow this year. It’s not a tool. It’s just good engineering. SDD gives it a natural home.</p><h3>The Bigger Picture</h3><p>I’ll end with a frame I keep coming back to.</p><p>Software architecture used to be about where you put the code. The modern question is where you put the <em>intent</em> — the decisions, the rationale, the requirements that explain why the code is what it is.</p><p>For most of software history, intent lived in people’s heads. When people left, the intent went with them. When context windows filled up, the AI’s version of intent went too.</p><p>SDD is an attempt to make intent a first-class artefact. Version-controlled, machine-readable, persistent across sessions and team members.</p><p>We’re early. The tooling is immature. The patterns for microservices are still being worked out in public. But the direction is right, and the teams I know who’ve committed to it are building more reliable software with AI assistance than the teams who haven’t.</p><p>Write the spec first. The code is just implementation details.</p><p><em>This is the final post in my three-part SDD series. If you’re just arriving: start with Part 1 (the why), then Part 2 (the how), then come back here. Questions, pushback, and war stories from your own codebase are very welcome in the comments.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d041bfb87b75" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How OpenSpec Actually Works: A Three-Phase Workflow That Keeps AI Honest]]></title>
            <link>https://apurvsheth.medium.com/how-openspec-actually-works-a-three-phase-workflow-that-keeps-ai-honest-3d4aeb61e9fa?source=rss-a27130eabf4a------2</link>
            <guid isPermaLink="false">https://medium.com/p/3d4aeb61e9fa</guid>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[python]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[java]]></category>
            <category><![CDATA[ai]]></category>
            <dc:creator><![CDATA[Apurv Sheth]]></dc:creator>
            <pubDate>Tue, 16 Jun 2026 02:31:00 GMT</pubDate>
            <atom:updated>2026-06-16T02:31:00.842Z</atom:updated>
            <content:encoded><![CDATA[<p><em>You’ve heard the pitch. Here’s the plumbing — and why the 50KB limit is the most important line of code in the whole framework.</em></p><p>I got a comment on my last post that I want to address before anything else.</p><p>Someone wrote: <em>“This sounds like you’re just writing documentation before you code. We’ve been doing that since 2003. What’s new?”</em></p><p>It’s a fair challenge. And the answer is in a detail that’s easy to miss in the high-level pitch.</p><p>The difference between SDD and traditional upfront documentation is not <em>what</em> you write. It’s <em>who reads it</em>.</p><p>Traditional documentation is written for humans and then politely ignored by the tools. SDD specs are written <em>for your AI agent</em> — structured so that the model can reference them mid-generation, check its output against them, and recover context when a session ends and a new one begins.</p><p>The spec isn’t a human artefact that happens to be near the code. It’s a <em>machine-readable contract</em> that the AI is constrained to honour.</p><p>That distinction changes everything about how you write specs, how you structure them, and which tool you use to manage them.</p><h3>Why I Chose OpenSpec</h3><p>I evaluated both major open-source options — GitHub’s SpecKit and OpenSpec by Fission-AI. I’ll go deeper on the comparison in a future post, but the headline is this:</p><p>SpecKit is powerful. It has a “constitution” model that encodes cross-cutting rules (TDD requirements, coding standards, compliance constraints) into every feature workflow. For an enterprise compliance scenario, that’s genuinely valuable.</p><p>OpenSpec is <em>fast</em>. Three commands. No constitution to write upfront. Works with 25+ AI tools out of the box. And critically — it has a hard 50KB context limit per spec, which I’ll explain why matters enormously in a moment.</p><p>I’m building with Claude Code and occasionally Cursor, across a brownfield codebase with existing patterns I need to respect. OpenSpec suited me better. If you’re in a regulated industry and need to enforce rules like “every API endpoint requires OpenAPI documentation,” SpecKit’s constitution model might suit you better — and that’s a legitimate tradeoff.</p><h3>The Three-Phase Workflow</h3><p>OpenSpec enforces a strict state machine. No phase is optional. No phase can be skipped. Here’s how it actually works.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*v1OnHCeIn0wxsO2prYDMCA.png" /><figcaption>OpenSpec: 3 Phase Workflow</figcaption></figure><h3>Phase 1: Propose</h3><p>You start with an intent. Not code — <em>intent</em>.</p><pre>/opsx:propose &quot;add rate limiting to the public API endpoints&quot;</pre><p>The agent reads your existing openspec/specs/ (the source of truth about your current system), then generates a new folder: openspec/changes/add-rate-limiting/ containing:</p><p><strong>proposal.md</strong> — structured document covering: what problem this solves, what will change (marked ADDED, MODIFIED, or REMOVED), what won&#39;t change, and key risks or dependencies.</p><p><strong>specs/</strong> — behavioural scenarios in GIVEN/WHEN/THEN format. These are the acceptance criteria. They are specific enough that the AI can use them as test cases.</p><p><strong>design.md</strong> — technical approach. Libraries, patterns, architectural decisions.</p><p><strong>tasks.md</strong> — implementation checklist broken into small, independently reviewable chunks.</p><p>You — the human — review all of this before a single line of implementation code is written. This is the gate. If you approve, Phase 2 begins. If the proposal is wrong, you correct it <em>here</em>, not after three hours of implementation.</p><p>The delta markers (ADDED/MODIFIED/REMOVED) deserve special attention. They force you — and the AI — to be explicit about what exists <em>now</em> versus what will exist <em>after</em>. This sounds bureaucratic. In practice it catches a surprising number of “oh wait, that module already does this” moments before they become technical debt.</p><h3>Phase 2: Apply</h3><p>Once the proposal is approved:</p><pre>/opsx:apply</pre><p>The AI works through tasks.md one task at a time, reading the spec at each step. Not your prompt from memory — the spec file. This is the key difference from unstructured AI coding.</p><p>Each task is small and independently testable. If a task fails or produces unexpected output, you can see exactly which spec scenario was violated. The feedback loop is tight.</p><p>When Apply finishes, you run:</p><pre>/opsx:verify</pre><p>This checks the implementation against the specs. It doesn’t just run the tests — it validates that the code’s <em>behaviour</em> matches the GIVEN/WHEN/THEN scenarios. When it finds a gap, it tells you exactly which scenario is unaddressed.</p><p>I’ve run verify on maybe thirty features now. It finds a gap on about a third of them. Always something small — a missing error state, an edge case the tasks didn’t cover. The fact that it catches these before merge is the entire value of the framework.</p><h3>Phase 3: Archive</h3><pre>/opsx:archive</pre><p>The change folder moves to openspec/changes/archive/, and the delta specs merge into the main openspec/specs/ — the project&#39;s unified source of truth.</p><p>This is the part that distinguishes OpenSpec from SpecKit structurally. SpecKit maintains separate spec files per feature indefinitely. OpenSpec consolidates everything into one living document that represents the <em>current state of the system</em>.</p><p>The result: at any point in time, you can read openspec/specs/ and understand the full system without assembling context from dozens of feature files. The AI can read it too — and does, at the start of every new proposal.</p><h3>The 50KB Context Limit: A Feature, Not a Bug</h3><p>Let me explain why this seemingly arbitrary constraint is one of the most important design decisions in the framework.</p><p>Modern LLMs have massive context windows — some over a million tokens. You might think: great, load in everything. All the specs, all the code, all the history.</p><p>The problem is that large context doesn’t mean <em>focused</em> context. When you feed an agent 800KB of specs and code, it doesn’t read all of it equally. It attends to some parts more than others — and the parts it attends to aren’t necessarily the parts you care about for <em>this specific task</em>.</p><p>OpenSpec’s 50KB limit forces you to be disciplined about what goes into the spec. You can’t dump everything in. You have to think about what the agent actually needs to know to implement this feature correctly.</p><p>This discipline has a side effect: your specs get better. Concise, targeted, genuinely useful. Not a brain-dump — a brief.</p><p>For teams running multiple agents in parallel across a large codebase (which I’ll cover in part three), this constraint also means you can run several agents concurrently without them eating each other’s context budget. That’s an operational concern that becomes critical at scale.</p><h3>A Real Example: The Rate Limiting Feature</h3><p>Let me make this concrete. Here’s a condensed version of what a real proposal looks like from a project I’m working on.</p><p><strong>proposal.md excerpt:</strong></p><pre>## What is changing</pre><pre>ADDED: Rate limiting middleware on all /api/v1/* routes<br>MODIFIED: Express app configuration to mount rate limiter before routes<br>ADDED: Redis-backed rate limit counter (per API key, per 15-minute window)</pre><pre>## What is NOT changing</pre><pre>Authentication flow, response format, existing error codes.</pre><pre>## Risk</pre><pre>Redis dependency — if Redis is unavailable, the middleware must fail open <br>(allow requests) not fail closed (block all traffic).</pre><p><strong>specs/rate-limiting.md excerpt:</strong></p><pre>GIVEN a valid API key making requests<br>WHEN the key exceeds 100 requests per 15-minute window<br>THEN the API returns 429 with a Retry-After header</pre><pre>GIVEN Redis is unavailable<br>WHEN a request arrives at the rate limiter<br>THEN the request proceeds as normal (fail-open behaviour)</pre><p>This second scenario — the fail-open Redis behaviour — was something I added during review. It wasn’t in the AI’s first draft of the spec. It came from me thinking through the failure mode.</p><p>That’s the spec review doing its job: forcing me to think about the system, not just describe a feature.</p><p>The resulting code handled Redis failures gracefully. Not because the AI is smart about resilience. Because the spec <em>told it</em> the behaviour it needed to implement.</p><h3>What Makes Specs Good</h3><p>After writing dozens of these, here’s what I’ve learned separates a useful spec from a useless one.</p><p><strong>Be behavioural, not prescriptive.</strong> Describe <em>what the system should do</em>, not <em>how to implement it</em>. “Users must be notified within 30 seconds” is a good spec. “Use a WebSocket to push notifications” is an implementation decision that belongs in design.md.</p><p><strong>Name your edge cases.</strong> The happy path is easy. The spec earns its value in the edge cases. What happens when the thing fails? What happens when it’s called twice? What happens with empty input?</p><p><strong>Keep each scenario atomic.</strong> One GIVEN/WHEN/THEN per scenario. Don’t nest conditions. If you need to express complex logic, use multiple scenarios.</p><p><strong>Write specs in plain English you’d be comfortable showing a non-technical stakeholder.</strong> If it requires three paragraphs to set up the context, the scenario is too complex.</p><h3>The Honest Trade-off</h3><p>Proposal time is real overhead. On a good day, writing and reviewing a proposal takes 20–30 minutes. On a complex feature, it can take a couple of hours.</p><p>I’ve stopped thinking of this as overhead. I think of it as <em>the actual work</em> — the thinking that needs to happen regardless, just moved to before implementation rather than during or after. The debugging and rework it replaces is almost always longer than the spec took to write.</p><p>If you’ve ever spent an afternoon untangling an AI-generated implementation that did something subtly but completely wrong — you’ll understand the appeal of 30 minutes upfront.</p><h3>Next: The Hard Problem</h3><p>Part 1 covered <em>why</em> SDD matters. Part 2 (this one) covered <em>how</em> OpenSpec implements it in a single repo.</p><p>But there’s a third problem nobody talks about in the SDD tutorials: what do you do when your system isn’t a single repo? What do you do when a feature change touches the auth service, the orders service, and the notification service — each in their own repository, each potentially worked on by a different agent running in a different context window?</p><p>That’s Part 3. And it’s where I think SDD is still genuinely immature — but where the most interesting patterns are emerging.</p><p><em>Liked this breakdown? The next post covers multi-repo SDD. Follow so you don’t miss it — and drop any questions in the comments. I read all of them.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3d4aeb61e9fa" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[I Spent 6 Months Vibe Coding. Here’s Why I’ll Never Do It Again.]]></title>
            <link>https://apurvsheth.medium.com/i-spent-6-months-vibe-coding-heres-why-i-ll-never-do-it-again-6fa375246e25?source=rss-a27130eabf4a------2</link>
            <guid isPermaLink="false">https://medium.com/p/6fa375246e25</guid>
            <category><![CDATA[spec-driven-development]]></category>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[python]]></category>
            <category><![CDATA[java]]></category>
            <category><![CDATA[software-development]]></category>
            <dc:creator><![CDATA[Apurv Sheth]]></dc:creator>
            <pubDate>Thu, 11 Jun 2026 02:31:00 GMT</pubDate>
            <atom:updated>2026-06-11T02:31:00.824Z</atom:updated>
            <content:encoded><![CDATA[<p><em>A developer’s honest account of the moment specs stopped being documentation and became the actual product.</em></p><p>I’m going to tell you about the worst bug I ever shipped.</p><p>It wasn’t a null pointer exception. It wasn’t a race condition. It was a feature — a fully working, tests-passing, code-reviewed feature — that did exactly what I <em>thought</em> I’d asked for. Not what I <em>needed</em>.</p><p>The AI built it faithfully. I just didn’t know how to ask.</p><p>That’s the thing nobody talks about with vibe coding. The problem isn’t that AI writes bad code. The problem is that it writes <em>exactly</em> what you describe in the moment, without any memory of everything you said three sessions ago, without any understanding of how this new thing interacts with that old thing, and without any way to push back when your off-the-cuff prompt is missing half the context.</p><p>For six months I lived in that world. Chat prompt, generated code, tweak, repeat. I was moving fast. I felt productive. My commit history looked impressive.</p><p>Then I hit a wall.</p><h3>The Wall</h3><p>It was a Tuesday. I was adding what should have been a simple notification system to a service I’d been building incrementally with AI assistance over several weeks. Four chat sessions, maybe five. Each one started fresh — I’d paste in some context, describe what I needed, review the output, merge it.</p><p>The notifications feature took an afternoon. Looked clean. The AI even wrote the tests.</p><p>Except three weeks later, a user reported they were getting double-emails on checkout. The kind of bug that’s invisible in a single session but catastrophic in production.</p><p>I went back to trace it. What I found wasn’t a logic error in the notification code. It was a <em>context collision</em> — two different sessions had each added their own event listener for the same checkout event, because neither session knew about the other. Both pieces of code were “correct” in isolation. Together they were a disaster.</p><p>I had no spec. I had no record of intent. I had chat logs I couldn’t search, comments I hadn’t written, and a growing sense that my codebase was a collection of AI opinions I had agreed to at various points in history.</p><p>That was the wall.</p><h3>What I Was Actually Missing</h3><p>Here’s what I’ve come to understand: the problem with vibe coding isn’t that AI is bad at writing code. It’s that <strong>requirements only exist in your head and in the conversation history</strong>, and both of those are terrible places to store them.</p><p>Your head forgets. Conversation history fills up. Context windows overflow. And when the AI inevitably makes an assumption — because every coder, human or machine, fills in blanks with assumptions — there’s nothing to check that assumption against.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*itA8DP3BFbz5yXBXqvhOvg.png" /><figcaption>Vibe Coding vs SDD</figcaption></figure><p>What you need is a <em>spec</em>. Not a design doc you write once and forget. Not a README that drifts from reality within a week. A living, version-controlled, machine-readable expression of intent that the AI actually reads before it writes a single line.</p><p>That idea has a name now: <strong>Spec-Driven Development</strong>, or SDD.</p><h3>What SDD Actually Is (And Isn’t)</h3><p>I want to be careful here because there’s a lot of hype around this phrase, and not all of it is useful.</p><p>SDD is not a return to waterfall. You are not writing a 40-page requirements document before you’re allowed to touch a keyboard. You are not promising your team that the spec is complete and frozen.</p><p>SDD is the practice of <strong>agreeing on what you’re building before you start building it</strong>, encoding that agreement in a file that lives in your repository, and using that file as the actual input to your AI coding agent rather than an improvised chat prompt.</p><p>The spec becomes the contract. The AI becomes the contractor. You become the architect.</p><p>The difference sounds subtle. The outcome is profound.</p><h3>My First Real Spec</h3><p>After the double-email incident, I went looking for tooling. I found two main options: GitHub’s <strong>SpecKit</strong> and a community project called <strong>OpenSpec</strong>. I’ll write more about the comparison in the next post — the short version is I chose OpenSpec for its lighter footprint and active community.</p><p>Here’s what my first spec looked like. I was adding a user preference center — a fairly involved feature with multiple subsystems. Old me would have described it to the AI in a prompt, got something back, iterated, merged, and moved on.</p><p>New me ran npm install -g @fission-ai/openspec and then typed:</p><pre>/opsx:propose &quot;user preference centre — allow users to set notification frequency, email format, and data export options&quot;</pre><p>The AI generated a folder: openspec/changes/user-preference-centre/ containing:</p><ul><li>proposal.md — a structured description of <em>why</em> we were building this and <em>what</em> it would change</li><li>specs/ — GIVEN/WHEN/THEN scenarios for each user-facing behaviour</li><li>design.md — a technical approach</li><li>tasks.md — a checklist of implementation steps</li></ul><p>I reviewed it. Changed three things. Approved it.</p><p>Then I ran /opsx:apply.</p><p>The AI implemented the feature — task by task, reading the spec at each step. Not my frantic prompt from memory. The actual spec.</p><p>When it was done, I ran /opsx:verify. It checked the implementation against the spec. Found one gap — a missing error state for the export function. I fixed it.</p><p>Then /opsx:archive. The spec merged into the project&#39;s source-of-truth document.</p><p>The whole thing took two hours. The feature worked first time in staging. And six months later, when someone needed to modify it, they read the spec and understood <em>exactly</em> what the original intention had been.</p><p>No double-emails.</p><h3>Why This Changes Everything</h3><p>Here’s what I noticed after about a month of working this way.</p><p><strong>I stopped dreading the “context window full” message.</strong> When you hit the limit with a spec-driven workflow, you don’t start over. You start a new session, hand the agent the spec file, and pick up exactly where you left off. Intent doesn’t live in the chat anymore — it lives in the file.</p><p><strong>My code reviews got faster.</strong> Instead of reviewers having to reverse-engineer what the code was <em>trying</em> to do, they could read the proposal first. The spec gave them a frame. Reviews that used to take an hour took fifteen minutes.</p><p><strong>AI hallucinations dropped noticeably.</strong> This surprised me. When the AI has a spec to work against, it has something to <em>check</em> itself against. The structured GIVEN/WHEN/THEN format gives it test cases it can reason about before generating code. The outputs were just… better.</p><p><strong>I have an audit trail.</strong> Every feature change has a corresponding proposal explaining why it was built the way it was. When something breaks, I know exactly where to look.</p><h3>The Honest Caveat</h3><p>I’m not going to pretend SDD has no cost. There is overhead. For a small bug fix, writing a spec is overkill — just fix the bug.</p><p>The sweet spot is anything that crosses more than one file, involves more than one session, or touches logic that someone else might need to understand later. For that kind of work, the ten minutes you spend writing a proposal saves you hours on the back end.</p><p>The framework I use (OpenSpec) makes this easy enough that I now do it almost reflexively for any feature work. It’s like writing a commit message — slightly annoying in the moment, invaluable six months later.</p><h3>What’s Next</h3><p>This is the first post in a three-part series.</p><p><strong>Next up:</strong> I’m going to walk you through exactly how OpenSpec works under the hood — the three-phase workflow, the delta marker system, and why the 50KB context limit is a feature not a bug. If you want to understand <em>how</em> specs actually get fed to an AI agent, that post is for you.</p><p><strong>In part three:</strong> The hard part — making SDD work across a microservices architecture with multiple repos and multiple agents running in parallel. Because the dirty secret is that most SDD tutorials assume a single repo. Real enterprise work doesn’t look like that.</p><p><em>Follow me for parts 2 and 3. If any of this resonated — particularly the double-email story — I’d genuinely love to hear your version in the comments. We all have one.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=6fa375246e25" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Java/Spring Boot Dev? Python Stole Your DevOps Playbook — Here’s How to Get It Back]]></title>
            <link>https://apurvsheth.medium.com/java-spring-boot-dev-python-stole-your-devops-playbook-heres-how-to-get-it-back-f5e239c6919f?source=rss-a27130eabf4a------2</link>
            <guid isPermaLink="false">https://medium.com/p/f5e239c6919f</guid>
            <category><![CDATA[python]]></category>
            <category><![CDATA[ai-engineering]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[spring-boot]]></category>
            <category><![CDATA[ai]]></category>
            <dc:creator><![CDATA[Apurv Sheth]]></dc:creator>
            <pubDate>Wed, 10 Jun 2026 02:31:00 GMT</pubDate>
            <atom:updated>2026-06-10T02:31:00.925Z</atom:updated>
            <content:encoded><![CDATA[<p><em>A battle-tested guide for Spring Boot veterans navigating the AI-Python era — with zero condescension and maximum caffeine.</em></p><blockquote><strong><em>TL;DR:</em></strong><em> AI tooling is Python-first. If you’re a Java/Spring Boot engineer who’s tired of feeling like a tourist in your own CI/CD pipeline, this guide maps everything you already know to its Python equivalent. Bookmark it. You’ll thank yourself later.</em></blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*UJ4hfaWGWZ8qetm9Qj9oUQ.png" /><figcaption>Java &amp; Python AI Era Edition</figcaption></figure><h3>Why This Article Exists</h3><p>Let’s be honest. The AI era didn’t just bring us ChatGPT and hallucinating interns — it quietly handed Python the keys to the DevOps kingdom.</p><p>LangChain? Python. Hugging Face? Python. Your team’s brand-new ML microservice that’s inexplicably being bolted onto your beautiful Spring Boot monolith? You guessed it — <strong>Python</strong>.</p><p>If you’re a Java/Spring Boot developer who’s spent years mastering Maven lifecycles, JAR packaging, and Nexus repositories, and suddenly you’re staring at a pyproject.toml like it owes you money — welcome. You&#39;re in the right place.</p><p>This guide is your <strong>Rosetta Stone</strong>. One column for the Java world you know, one column for the Python world you’re learning to coexist with. Let’s go.</p><h3>Chapter 1: Project Structure — “Where Does Everything Live?”</h3><p>In Spring Boot, you crack open a project and immediately know what’s what. The src/main/java hierarchy is as familiar as your morning commute.</p><p><strong>Spring Boot:</strong></p><pre>my-service/<br>├── src/<br>│   ├── main/<br>│   │   ├── java/com/company/myservice/<br>│   │   └── resources/application.yml<br>│   └── test/java/<br>├── pom.xml<br>└── Dockerfile</pre><p><strong>Python (FastAPI / general microservice):</strong></p><pre>my-service/<br>├── src/<br>│   └── my_service/<br>│       ├── __init__.py<br>│       ├── main.py<br>│       └── config.py<br>├── tests/<br>├── pyproject.toml        ← This is your pom.xml. Breathe.<br>└── Dockerfile</pre><p><strong>The key insight:</strong> __init__.py makes a folder a Python <em>package</em>. It&#39;s Python&#39;s way of saying &quot;this directory matters.&quot; Think of it as the package-info.java you always forgot to write.</p><h3>📦 Chapter 2: Dependency Management — “Who Broke the Build This Time?”</h3><p>This is where most Java devs have their first existential crisis with Python. “Where’s my pom.xml?!&quot; — you&#39;ll ask, clutching your coffee.</p><h3>Build Tool Mapping</h3><p>Java/Spring Boot Python Purpose Maven (pom.xml) Poetry (pyproject.toml) Dependency declaration &amp; lifecycle Gradle (build.gradle) PDM / Hatch Alternative build tools mvn install poetry install Install all dependencies mvn dependency:tree poetry show --tree Visualize the dependency graph mvn versions:display-dependency-updates poetry update --dry-run Check for updates</p><h3>The Poetry Crash Course (For Maven Loyalists)</h3><pre># pyproject.toml — your new pom.xml, minus 400 lines of XML<br>[tool.poetry]<br>name = &quot;my-ai-service&quot;<br>version = &quot;0.1.0&quot;<br>description = &quot;Does ML things. Probably.&quot;</pre><pre>[tool.poetry.dependencies]<br>python = &quot;^3.11&quot;<br>fastapi = &quot;^0.110.0&quot;<br>langchain = &quot;^0.1.0&quot;</pre><pre>[tool.poetry.group.dev.dependencies]<br>pytest = &quot;^8.0.0&quot;<br>black = &quot;^24.0.0&quot;</pre><pre># Maven muscle memory → Poetry translation<br>mvn install          →  poetry install<br>mvn test             →  poetry run pytest<br>mvn package          →  poetry build<br>mvn clean            →  rm -rf dist/ __pycache__/  (yes, really)</pre><blockquote><strong>💡 Hook:</strong> Think of poetry.lock as your pom.xml&#39;s lockfile dream that Maven never had. It pins every transitive dependency. No more &quot;works on my machine&quot; for dependency versions.</blockquote><h3>Dependency Scopes: The Concept Survives</h3><pre>&lt;!-- Maven --&gt;<br>&lt;dependency&gt;<br>  &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;<br>  &lt;artifactId&gt;spring-boot-starter-test&lt;/artifactId&gt;<br>  &lt;scope&gt;test&lt;/scope&gt;<br>&lt;/dependency&gt;</pre><pre># Poetry — same concept, cleaner syntax<br>[tool.poetry.group.test.dependencies]<br>pytest = &quot;^8.0&quot;<br>httpx = &quot;^0.27&quot;   # For FastAPI test client</pre><h3>🐍 Chapter 3: Virtual Environments — “Wait, Python Doesn’t Have a .m2 folder?”</h3><p>Ah yes. The part where Java devs either laugh or cry.</p><p>Maven has a global ~/.m2/repository. Everything lives there. Neat, central, occasionally a 4GB nightmare to delete.</p><p>Python’s philosophy? <strong>Every project gets its own isolated environment.</strong> It’s like Maven giving each project its own private .m2. Chaotic? Liberating? Yes to both.</p><pre># The old (painful) way — pure Python<br>python -m venv .venv<br>source .venv/bin/activate     # Unix<br>.venv\Scripts\activate        # Windows (sigh)<br>pip install -r requirements.txt</pre><pre># The Poetry way (recommended)<br>poetry shell                  # Activates virtualenv automatically<br>poetry install                # Installs everything from pyproject.toml</pre><p><strong>The modern shortcut with </strong><strong>uv</strong> (think: Maven Wrapper but 10x faster):</p><pre># uv is the new hotness — Rust-powered, blazingly fast<br>pip install uv<br>uv venv<br>uv pip install fastapi langchain</pre><blockquote><strong>Spring Boot parallel:</strong> ./mvnw (Maven Wrapper) ensures everyone on your team uses the same Maven version. uv does the same for Python tooling — pinned, reproducible, no &quot;but I have Python 3.9&quot; arguments.</blockquote><h3>🧪 Chapter 4: Testing — “JUnit Had a Python Baby”</h3><p>Good news: testing concepts translate almost 1:1. Bad news: @BeforeEach now has a different name. Prepare your muscle memory.</p><h3>Framework Mapping</h3><p>JUnit 5 / Spring Boot Test pytest Purpose @Test def test_*(): Test method @BeforeEach @pytest.fixture (autouse) Setup before each test @AfterEach yield in a fixture Teardown @SpringBootTest TestClient (FastAPI) Integration test Mockito @Mock unittest.mock.Mock / pytest-mock Mocking assertThat(x).isEqualTo(y) assert x == y Assertions</p><h3>Real Example: Testing a REST Endpoint</h3><p><strong>Spring Boot:</strong></p><pre>@SpringBootTest(webEnvironment = RANDOM_PORT)<br>class UserControllerTest {</pre><pre>    @Autowired<br>    private TestRestTemplate restTemplate;</pre><pre>    @Test<br>    void shouldReturnUser() {<br>        ResponseEntity&lt;User&gt; response = restTemplate<br>            .getForEntity(&quot;/api/users/1&quot;, User.class);<br>        assertThat(response.getStatusCode()).isEqualTo(OK);<br>        assertThat(response.getBody().getName()).isEqualTo(&quot;Alice&quot;);<br>    }<br>}</pre><p><strong>FastAPI / Python:</strong></p><pre>from fastapi.testclient import TestClient<br>from myservice.main import app</pre><pre>client = TestClient(app)</pre><pre>def test_should_return_user():<br>    response = client.get(&quot;/api/users/1&quot;)<br>    assert response.status_code == 200<br>    assert response.json()[&quot;name&quot;] == &quot;Alice&quot;</pre><p>Less ceremony. Same intent. You’ll miss the IDE autocomplete for approximately 2 days, then you won’t.</p><h3>Mocking: Mockito vs pytest-mock</h3><pre>// Mockito<br>@Mock UserRepository userRepository;<br>when(userRepository.findById(1L)).thenReturn(Optional.of(mockUser));</pre><pre># pytest-mock<br>def test_get_user(mocker):<br>    mock_repo = mocker.patch(&quot;myservice.service.user_repository&quot;)<br>    mock_repo.find_by_id.return_value = mock_user</pre><blockquote><strong>💡 Hook:</strong> pytest fixtures are genuinely more powerful than @BeforeEach. You can scope them to a test, class, module, or session. It&#39;s dependency injection for tests. You&#39;ll miss Spring&#39;s DI for about 30 seconds until you realize fixtures scratch the same itch.</blockquote><h3>🏭 Chapter 5: Packaging — “JAR Files Had a Baby Named Wheel”</h3><p>This is where Python’s history gets a little… chaotic. But stay with me.</p><h3>Packaging Format Mapping</h3><p>Java/Spring Boot Python Notes .jar (thin) .whl (wheel) Distributable library package Fat JAR / Uber JAR Bundled with Docker Python doesn&#39;t really do fat wheels Spring Boot executable JAR Docker image The Python &quot;deployable unit&quot; META-INF/MANIFEST.MF pyproject.toml metadata Package metadata</p><h3>Building a Python Package</h3><pre># Build your wheel (equivalent to mvn package)<br>poetry build</pre><pre># Output:<br>dist/<br>├── my_ai_service-0.1.0-py3-none-any.whl   ← your JAR<br>└── my_ai_service-0.1.0.tar.gz              ← source distribution</pre><p>The .whl file is a ZIP (just like a JAR!). It contains your Python code + metadata. You can literally unzip it and browse the contents. Go on, try it. It&#39;s strangely satisfying.</p><h3>The “Fat JAR” Problem in Python</h3><p>Spring Boot’s fat JAR is one of its killer features — everything bundled into one self-contained executable. Python doesn’t have an equivalent <em>at the library level</em>. Instead, the Python world went a different direction:</p><pre># Python&#39;s answer to the Fat JAR: a well-crafted Docker image<br>FROM python:3.11-slim</pre><pre>WORKDIR /app<br>COPY dist/my_ai_service-0.1.0-py3-none-any.whl .<br>RUN pip install my_ai_service-0.1.0-py3-none-any.whl</pre><pre>CMD [&quot;uvicorn&quot;, &quot;my_service.main:app&quot;, &quot;--host&quot;, &quot;0.0.0.0&quot;, &quot;--port&quot;, &quot;8080&quot;]</pre><blockquote><strong>Spring Boot parallel:</strong> java -jar app.jar → uvicorn my_service.main:app Uvicorn is your embedded Tomcat. Gunicorn is your more battle-hardened Tomcat. Pick your fighter.</blockquote><h3>🚀 Chapter 6: Artifact Publishing — “Maven Central’s Python Cousin”</h3><h3>Repository Mapping</h3><p>Java/Spring Boot Python Purpose Maven Central PyPI (pypi.org) Public package registry JFrog Artifactory JFrog Artifactory (also supports Python!) Private enterprise registry Nexus Repository Nexus Repository (also supports PyPI format!) Self-hosted registry GitHub Packages GitHub Packages (Python) GitHub-native registry mvn deploy poetry publish Push to registry</p><p>The good news: JFrog and Nexus both support Python package registries out of the box. If your enterprise already runs Nexus, you can point Poetry at it with minimal ceremony.</p><h3>Publishing to PyPI</h3><pre># First-time setup<br>poetry config pypi-token.pypi your-api-token-here</pre><pre># Publish (equivalent to mvn deploy)<br>poetry publish --build</pre><pre># Or with Twine (the manual way, like running mvn:deploy with custom args)<br>pip install twine<br>twine upload dist/*</pre><h3>Publishing to a Private Registry (Nexus/Artifactory)</h3><pre># Tell Poetry about your private registry<br>poetry config repositories.company-pypi https://nexus.company.com/repository/pypi-releases/<br>poetry config http-basic.company-pypi your-username your-password</pre><pre># Publish to private registry<br>poetry publish --repository company-pypi</pre><pre># Install from private registry<br>pip install --index-url <a href="https://nexus.company.com/repository/pypi-all/simple/">https://nexus.company.com/repository/pypi-all/simple/</a> my-package</pre><pre># pyproject.toml — declare your private source<br>[[tool.poetry.source]]<br>name = &quot;company-pypi&quot;<br>url = &quot;https://nexus.company.com/repository/pypi-all/simple/&quot;<br>priority = &quot;supplemental&quot;</pre><blockquote><strong><em>💡</em> Hook:</strong> Maven’s distributionManagement block and Poetry&#39;s source configuration are doing identical jobs. If you&#39;ve ever configured settings.xml for Nexus, this will feel instantly familiar — just with less XML therapy required.</blockquote><h3>🔄 Chapter 7: CI/CD Pipeline — Where It All Comes Together</h3><p>Let’s build a complete, side-by-side pipeline comparison. This is the section to share with your DevOps team.</p><h3>GitHub Actions: Spring Boot vs Python AI Service</h3><p><strong>Spring Boot Pipeline:</strong></p><pre># .github/workflows/spring-boot.yml<br>name: Spring Boot CI/CD</pre><pre>on: [push, pull_request]</pre><pre>jobs:<br>  build:<br>    runs-on: ubuntu-latest<br>    steps:<br>      - uses: actions/checkout@v4</pre><pre>      - name: Set up JDK 21<br>        uses: actions/setup-java@v4<br>        with:<br>          java-version: &#39;21&#39;<br>          distribution: &#39;temurin&#39;<br>          cache: maven</pre><pre>      - name: Build &amp; Test<br>        run: mvn clean verify</pre><pre>      - name: Build Docker Image<br>        run: docker build -t my-service:${{ github.sha }} .</pre><pre>      - name: Publish to Nexus<br>        run: mvn deploy -DskipTests<br>        env:<br>          NEXUS_USERNAME: ${{ secrets.NEXUS_USER }}<br>          NEXUS_PASSWORD: ${{ secrets.NEXUS_PASS }}</pre><p><strong>Python AI Service Pipeline:</strong></p><pre># .github/workflows/python-ai-service.yml<br>name: Python AI Service CI/CD</pre><pre>on: [push, pull_request]</pre><pre>jobs:<br>  build:<br>    runs-on: ubuntu-latest<br>    steps:<br>      - uses: actions/checkout@v4</pre><pre>      - name: Set up Python 3.11           # ← setup-java equivalent<br>        uses: actions/setup-python@v5<br>        with:<br>          python-version: &#39;3.11&#39;</pre><pre>      - name: Install Poetry               # ← Maven is pre-installed; Poetry isn&#39;t<br>        run: pip install poetry</pre><pre>      - name: Install Dependencies         # ← mvn install equivalent<br>        run: poetry install</pre><pre>      - name: Lint (Ruff)                  # ← Checkstyle equivalent<br>        run: poetry run ruff check .</pre><pre>      - name: Type Check (Mypy)            # ← No Java equivalent needed (types are built-in)<br>        run: poetry run mypy src/</pre><pre>      - name: Test                         # ← mvn test equivalent<br>        run: poetry run pytest --cov=src tests/</pre><pre>      - name: Build Package                # ← mvn package equivalent<br>        run: poetry build</pre><pre>      - name: Build Docker Image<br>        run: docker build -t my-ai-service:${{ github.sha }} .</pre><pre>      - name: Publish to PyPI             # ← mvn deploy equivalent<br>        if: github.ref == &#39;refs/heads/main&#39;<br>        run: poetry publish<br>        env:<br>          POETRY_PYPI_TOKEN_PYPI: ${{ secrets.PYPI_TOKEN }}</pre><p>The structural parallel is almost poetic (pun intended). Same stages, different commands.</p><h3>The Code Quality Stack, Mapped</h3><p>Java/Spring Boot Python Purpose Checkstyle Ruff / Flake8 Linting / style enforcement PMD / SpotBugs Pylint / Bandit Static analysis SonarQube SonarQube (supports Python!) Code quality gates JaCoCo pytest-cov Code coverage Spotless Black / Ruff format Auto-formatting ErrorProne Mypy / Pyright Type checking</p><pre># Your Python quality toolkit in one shot<br>poetry add --group dev ruff black mypy pytest pytest-cov bandit</pre><pre># Run everything (put this in a Makefile — yes, Python projects use Makefiles)<br>ruff check .          # Lint<br>black --check .       # Format check<br>mypy src/             # Type check<br>pytest --cov=src      # Test + coverage<br>bandit -r src/        # Security scan</pre><h3>🐳 Chapter 8: Containerization — Docker Speaks Both Languages</h3><p>Good news: Docker doesn’t care if you write Java or Python. Bad news: the base images are completely different, and Python image selection has more opinions than a senior architect in a design review.</p><h3>Dockerfile Comparison</h3><p><strong>Spring Boot:</strong></p><pre># Multi-stage build — the Java way<br>FROM eclipse-temurin:21-jdk-alpine AS build<br>WORKDIR /app<br>COPY pom.xml .<br>COPY src ./src<br>RUN mvn clean package -DskipTests</pre><pre>FROM eclipse-temurin:21-jre-alpine<br>WORKDIR /app<br>COPY --from=build /app/target/*.jar app.jar<br>EXPOSE 8080<br>ENTRYPOINT [&quot;java&quot;, &quot;-jar&quot;, &quot;app.jar&quot;]</pre><p><strong>Python AI Service:</strong></p><pre># Multi-stage build — the Python way<br>FROM python:3.11-slim AS build<br>WORKDIR /app<br>RUN pip install poetry<br>COPY pyproject.toml poetry.lock ./<br>RUN poetry config virtualenvs.in-project true &amp;&amp; \<br>    poetry install --no-dev --no-root<br>COPY src/ ./src/</pre><pre>FROM python:3.11-slim AS runtime<br>WORKDIR /app<br>COPY --from=build /app/.venv ./.venv<br>COPY --from=build /app/src ./src<br>ENV PATH=&quot;/app/.venv/bin:$PATH&quot;<br>EXPOSE 8080<br>CMD [&quot;uvicorn&quot;, &quot;my_service.main:app&quot;, &quot;--host&quot;, &quot;0.0.0.0&quot;, &quot;--port&quot;, &quot;8080&quot;]</pre><h3>Python Docker Image Options (Because Choices)</h3><p>Image Size Use Case python:3.11 ~900MB Development, full tooling python:3.11-slim ~130MB Production (recommended) python:3.11-alpine ~50MB Minimal (watch for glibc issues with ML libs) nvidia/cuda:12.3-python3.11 ~6GB GPU workloads / ML training</p><blockquote><strong><em>⚠️</em> Gotcha for Java devs:</strong> Alpine Linux uses musl libc instead of glibc. Most ML libraries (numpy, scipy, torch) are compiled against glibc. If you&#39;re running AI workloads, stick with slim variants to avoid hours of mysterious import errors. Consider this your official warning.</blockquote><h3>☸️ Chapter 9: Kubernetes Deployment — Same YAML, Different Image</h3><p>Here’s where your Spring Boot knowledge transfers almost perfectly. Kubernetes doesn’t know if you’re running Java or Python — it just sees containers.</p><pre># deployment.yaml — nearly identical for both<br>apiVersion: apps/v1<br>kind: Deployment<br>metadata:<br>  name: my-ai-service<br>spec:<br>  replicas: 3<br>  selector:<br>    matchLabels:<br>      app: my-ai-service<br>  template:<br>    metadata:<br>      labels:<br>        app: my-ai-service<br>    spec:<br>      containers:<br>      - name: my-ai-service<br>        image: my-ai-service:latest<br>        ports:<br>        - containerPort: 8080<br>        env:<br>        - name: OPENAI_API_KEY          # AI-specific config<br>          valueFrom:<br>            secretKeyRef:<br>              name: ai-secrets<br>              key: openai-key<br>        resources:<br>          requests:<br>            memory: &quot;512Mi&quot;             # Python ML services: think &quot;2Gi&quot; minimum<br>            cpu: &quot;250m&quot;<br>          limits:<br>            memory: &quot;1Gi&quot;<br>            cpu: &quot;1000m&quot;<br>        readinessProbe:<br>          httpGet:<br>            path: /health               # FastAPI health endpoint<br>            port: 8080<br>          initialDelaySeconds: 10       # Python starts faster than JVM — adjust accordingly</pre><blockquote><strong>💡 Hook — The JVM vs Python startup time plot twist:</strong> Your Spring Boot app might take 15–30 seconds to warm up. A FastAPI app? Under 2 seconds. Your initialDelaySeconds just got a makeover. This also makes Python a natural fit for serverless/lambda-style deployments where cold starts matter.</blockquote><h3>🔧 Chapter 10: Configuration Management — application.yml Meets… YAML Again</h3><p>Another pleasant surprise: configuration patterns map cleanly.</p><h3>Configuration Mapping</h3><p>Spring Boot Python Purpose application.yml .env / config.yml Environment config @ConfigurationProperties Pydantic BaseSettings Typed config binding Spring Profiles Environment variables + python-dotenv Environment-specific config @Value(&quot;${property}&quot;) os.getenv(&quot;PROPERTY&quot;) Single value injection</p><h3>Pydantic Settings — The Python @ConfigurationProperties</h3><pre># config.py — this is your @ConfigurationProperties class<br>from pydantic_settings import BaseSettings</pre><pre>class Settings(BaseSettings):<br>    # Type-safe, validated, IDE-friendly config<br>    app_name: str = &quot;My AI Service&quot;<br>    database_url: str<br>    openai_api_key: str<br>    max_tokens: int = 2000<br>    debug: bool = False</pre><pre>    class Config:<br>        env_file = &quot;.env&quot;           # Like Spring&#39;s @PropertySource</pre><pre>settings = Settings()               # Reads from env vars or .env file</pre><pre># main.py — inject settings like Spring&#39;s @Autowired<br>from .config import settings<br>from fastapi import FastAPI</pre><pre>app = FastAPI(title=settings.app_name)</pre><pre>@app.get(&quot;/health&quot;)<br>def health():<br>    return {&quot;status&quot;: &quot;UP&quot;, &quot;service&quot;: settings.app_name}</pre><pre># .env file — your application.yml, but flatter<br>DATABASE_URL=postgresql://localhost:5432/mydb<br>OPENAI_API_KEY=sk-...<br>MAX_TOKENS=4000<br>DEBUG=false</pre><h3>🤖 Chapter 11: The AI Era Twist — What Python Has That Java Doesn’t (Yet)</h3><p>Let’s be real. The reason Python won the AI era isn’t because it’s a better language. It’s because the ML community picked it, and network effects did the rest.</p><p>Here’s what you’ll encounter when building AI pipelines:</p><h3>The Python AI Stack vs Spring Boot AI</h3><p>Use Case Python Library Spring Boot Equivalent LLM integration LangChain, LlamaIndex Spring AI (catching up!) Vector databases ChromaDB, Pinecone SDK Spring AI vector stores HTTP APIs FastAPI, Flask Spring MVC / WebFlux Async processing asyncio, Celery Spring WebFlux, @Async Data pipelines Pandas, Polars Spring Batch Model serving FastAPI + uvicorn Spring Boot + embedded Tomcat</p><h3>Spring AI — The Java Ecosystem’s Response</h3><pre>// Spring AI is real and it&#39;s growing fast<br>@Service<br>public class AiService {</pre><pre>    private final ChatClient chatClient;</pre><pre>    public AiService(ChatClient.Builder builder) {<br>        this.chatClient = builder.build();<br>    }</pre><pre>    public String askQuestion(String question) {<br>        return chatClient.prompt()<br>            .user(question)<br>            .call()<br>            .content();<br>    }<br>}</pre><pre># FastAPI + LangChain equivalent<br>from langchain_openai import ChatOpenAI<br>from fastapi import FastAPI</pre><pre>app = FastAPI()<br>llm = ChatOpenAI(model=&quot;gpt-4o&quot;)</pre><pre>@app.post(&quot;/ask&quot;)<br>async def ask_question(question: str):<br>    response = await llm.ainvoke(question)<br>    return {&quot;answer&quot;: response.content}</pre><blockquote><strong>💡 Hot take:</strong> Spring AI is genuinely good and improving rapidly. If you’re building an enterprise AI product with complex security, transaction management, and existing Spring infrastructure, you might not need Python at all. But knowing the Python ecosystem makes you a better architect regardless.</blockquote><h3>🗺️ The Complete Cheat Sheet</h3><p>Cut this out. Tape it to your monitor. You’re welcome.</p><pre>PROJECT MANAGEMENT<br>─────────────────────────────────────────────────────<br>mvn install              →  poetry install<br>mvn clean package        →  poetry build<br>mvn test                 →  poetry run pytest<br>mvn verify               →  poetry run pytest + ruff + mypy<br>mvn deploy               →  poetry publish<br>./mvnw                   →  poetry (self-managed) / uv</pre><pre>DEPENDENCY MANAGEMENT<br>─────────────────────────────────────────────────────<br>pom.xml                  →  pyproject.toml<br>pom.xml &lt;dependencies&gt;   →  [tool.poetry.dependencies]<br>&lt;scope&gt;test&lt;/scope&gt;      →  [tool.poetry.group.test.dependencies]<br>mvn dependency:tree      →  poetry show --tree<br>~/.m2/repository         →  ~/.cache/pypoetry/ (or virtualenv)</pre><pre>PACKAGING &amp; DISTRIBUTION<br>─────────────────────────────────────────────────────<br>.jar (library)           →  .whl (wheel)<br>fat JAR                  →  Docker image<br>Maven Central            →  PyPI<br>Nexus / Artifactory      →  Nexus / Artifactory (PyPI mode)<br>mvn deploy               →  poetry publish / twine upload</pre><pre>RUNTIME<br>─────────────────────────────────────────────────────<br>Spring MVC               →  FastAPI / Flask<br>Spring WebFlux           →  FastAPI (async) / Starlette<br>Embedded Tomcat          →  Uvicorn / Gunicorn<br>@RestController          →  @app.get / @app.post<br>@Service                 →  Plain Python class (DI is manual or via FastAPI Depends)<br>@ConfigurationProperties →  Pydantic BaseSettings<br>application.yml          →  .env + pyproject.toml config</pre><pre>TESTING<br>─────────────────────────────────────────────────────<br>JUnit 5                  →  pytest<br>@Test                    →  def test_*():<br>@BeforeEach              →  @pytest.fixture<br>Mockito                  →  unittest.mock / pytest-mock<br>@SpringBootTest          →  FastAPI TestClient<br>JaCoCo                   →  pytest-cov<br>AssertJ                  →  plain assert / pytest assertions</pre><pre>CODE QUALITY<br>─────────────────────────────────────────────────────<br>Checkstyle               →  Ruff (linting)<br>Spotless / google-java-format → Black (formatting)<br>PMD / SpotBugs           →  Pylint / Bandit<br>Mypy annotation style    →  Mypy (type checking)<br>SonarQube                →  SonarQube (supports both!)</pre><h3>🎯 Final Thoughts: You’re Already 80% There</h3><p>Here’s the thing nobody tells you: <strong>the hard parts of software engineering don’t change.</strong></p><p>Dependency management, reproducible builds, artifact versioning, CI/CD pipelines, containerization, configuration management — these are <em>solved problems</em> in both ecosystems. The vocabulary shifts, but the concepts don’t.</p><p>You already understand:</p><ul><li>✅ Why reproducible builds matter (hello, pom.xml + poetry.lock)</li><li>✅ Why dependency scoping is important (test vs runtime vs compile)</li><li>✅ Why artifact versioning with SemVer keeps everyone sane</li><li>✅ Why code quality gates prevent technical debt from compounding</li><li>✅ Why Docker + Kubernetes is the universal deployment story</li></ul><p>The 20% you’ll learn is vocabulary, tooling ergonomics, and some Python-specific gotchas (the GIL, async subtleties, dynamic typing footguns). That 20% is absolutely learnable — especially with a cheat sheet this good.</p><p>The AI era isn’t replacing Spring Boot. It’s adding Python services to the ecosystem you already operate. Being fluent in both makes you the engineer every team needs right now.</p><p>Now go install Poetry, create a FastAPI service, and deploy it with the same discipline you’d apply to your Spring Boot apps. Your future self — and your team’s Python intern — will thank you.</p><p><strong>Tags:</strong> Spring Boot Python DevOps CI/CD AI Engineering FastAPI Maven Poetry Java MLOps</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=f5e239c6919f" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Your GitHub Copilot Has Been Whispering for Help. You Just Never Knew How to Listen.]]></title>
            <link>https://apurvsheth.medium.com/your-github-copilot-has-been-whispering-for-help-you-just-never-knew-how-to-listen-72eb9f34a5db?source=rss-a27130eabf4a------2</link>
            <guid isPermaLink="false">https://medium.com/p/72eb9f34a5db</guid>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[github-copilot]]></category>
            <category><![CDATA[design]]></category>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[software-architecture]]></category>
            <dc:creator><![CDATA[Apurv Sheth]]></dc:creator>
            <pubDate>Mon, 08 Jun 2026 02:31:00 GMT</pubDate>
            <atom:updated>2026-06-08T02:31:00.922Z</atom:updated>
            <content:encoded><![CDATA[<p>The complete guide to markdown files that transform Copilot from a fancy autocomplete into an AI teammate that actually knows your project — written for developers at every level.</p><blockquote><strong>Part 2 of the GitHub Copilot Setup Series.</strong> <a href="https://medium.com/@apurvsheth/i-spent-3-days-fighting-github-copilot-then-i-found-the-files-that-changed-everything-b1423e64ffac">Part </a>1 covered directory structure and the one file that changes everything. This one goes deeper — into Prompts, Skills, and Agents. <strong>New here?</strong> The short version: Copilot isn’t dumb. It’s blind. Markdown files fix that. Now let’s fix it completely.</blockquote><p>A developer on my team — eleven days into the project — opened a PR that looked like it was written by someone who’d been there a year.</p><p>Tenant scoping. Zod validation. Our exact logger format. Error handling done right.</p><p>I asked him what he did differently.</p><p>He opened his .github/ folder and showed me four markdown files I&#39;d never created.</p><p><em>That</em> was the moment I realised I’d been using Copilot like a calculator when it was capable of being an entire engineering team.</p><p>This article is those four files — what they are, what goes in them, and exactly what changes when you add them.</p><blockquote><strong>How to read this:</strong> Each section stands alone. Beginner? Start at Pillar 1 and stop when you need a break. Already past the basics? Jump straight to Prompts or Agents. Either way — by the end, you’ll have a setup most developers don’t know exists.</blockquote><h4>The Mental Model</h4><p>Hiring a brilliant engineer and giving them zero onboarding is expensive. They write decent code. It just doesn’t feel like your code.<br>Now give them four documents on day one:</p><ul><li>The rules - how this system works, what to never do</li><li>Task templates — how to scaffold an endpoint, write a test, build a component</li><li>A playbook — step-by-step for the complex stuff</li><li>A specialist — an AI that autonomously handles an entire job category</li></ul><p>That’s the framework. Four files. Four pillars.<br>Rules → Tasks → Playbooks → Specialists.<br>Copilot already knows how to read all four. You just haven’t written them yet.</p><h4>The Four Files at a Glance</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/679/1*AH1zKWoPyr67RHKhmwTcXQ.png" /><figcaption>github copilot markdowns</figcaption></figure><h4>Pillar 1: copilot-instructions.md — The Rulebook</h4><p><strong>One sentence:</strong> Write your team’s rules once. Copilot follows them in every file, forever.</p><pre>your-project/<br>└── .github/<br>    └── copilot-instructions.md  ← exact location matters</pre><p>Here’s a real one for a TypeScript + Node.js + React project:</p><pre># Copilot Instructions<br><br>## Project<br>B2B SaaS for HR onboarding. Node.js 20 + Express 5 backend,<br>React 18 + TypeScript 5 frontend, PostgreSQL via Prisma ORM.<br><br>## Non-Negotiable Rules<br>- Every DB query MUST include `tenantId` — we&#39;re multi-tenant, this is security<br>- Routes call Services. Services call Prisma. Routes never touch DB directly.<br>- Use `AppError` from `src/lib/errors.ts` — never throw raw errors<br>- Use `logger` from `src/lib/logger.ts` — never `console.log`<br>- No `any` in TypeScript. Use `unknown` and narrow it.<br>- Soft deletes only — set `deletedAt`, never hard delete<br><br>## Never Do This<br>- Raw SQL strings — use Prisma query builder<br>- `import _ from &#39;lodash&#39;` — use `import debounce from &#39;lodash/debounce&#39;`<br>- Class components in React<br>- `useEffect` for data fetching — use React Query</pre><h4>The Before/After That Makes This Real</h4><p><strong>Without this file.</strong> You type: // get all employees</p><pre>async function getEmployees() {<br>  return prisma.employee.findMany();<br>}</pre><p>Looks fine. Ships. Two weeks later: every company can see every other company’s employees. Security incident.</p><p><strong>With this file.</strong> Same comment:</p><pre>async function getEmployees(<br>  tenantId: string,<br>  options: EmployeeQueryOptions = {}<br>): Promise&lt;Employee[]&gt; {<br>  return prisma.employee.findMany({<br>    where: { tenantId, deletedAt: null },<br>    orderBy: { createdAt: &#39;desc&#39; },<br>  });<br>}</pre><p>tenantId scoped. Soft-delete filtered. Typed. That&#39;s not a better suggestion — that&#39;s a prevented incident.</p><blockquote><strong>15-minute win:</strong> Stop here, create .github/copilot-instructions.md, add your stack + 3 rules + 2 &quot;never do this&quot; lines. You&#39;ll feel the difference before you finish your next feature.</blockquote><h4>Pillar 2: .prompt.md Files — Your Reusable Task Templates</h4><p><strong>One sentence:</strong> Stop re-explaining the same task. Write it once, trigger it with a / command.</p><p>Every team has tasks they do on repeat — new API endpoints, unit tests, React components. A prompt file turns “re-explain everything each time” into “type /new-endpoint and go.&quot;</p><pre>.github/<br>└── prompts/<br>    ├── new-api-endpoint.prompt.md<br>    ├── write-unit-tests.prompt.md<br>    └── create-react-component.prompt.md</pre><p><strong>Prompt File: New API Endpoint</strong></p><pre>---<br>name: New API Endpoint<br>description: Scaffold a complete endpoint — schema, service, route, tests<br>---<br><br>Scaffold a complete REST endpoint for: **${input:featureName}**<br><br>Generate these four files:<br><br>**1. `src/api/schemas/${input:featureName}.schema.ts`**<br>- Zod schema for request body<br>- Export the inferred TypeScript type<br><br>**2. `src/services/${input:featureName}.service.ts`**<br>- Accept `tenantId` as first param<br>- Use Prisma (never raw SQL)<br>- Throw `AppError` on failure, log with `logger`<br><br>**3. `src/api/routes/${input:featureName}.ts`**<br>- Express Router<br>- Validate body against Zod schema before anything else<br>- Call service — never call Prisma from here<br>- Return `{ data, error: null }` on success<br><br>**4. `src/services/${input:featureName}.service.test.ts`**<br>- Happy path, validation errors, not-found case<br>- Mock Prisma with `vi.mock`<br><br>Generate all four now.</pre><p><strong>How to use it:</strong> Open Copilot Chat → type /new-api-endpoint → enter the feature name → watch it generate a schema, service, route, and test suite in one shot.</p><p>That’s 25 minutes of scaffolding in 15 seconds.</p><h4>Prompt File: Write Unit Tests</h4><pre>---<br>name: Write Unit Tests<br>description: Generate tests for the currently open file<br>---<br><br>Write unit tests for the file currently open.<br><br>- Framework: Vitest (`describe`, `it`, `expect`, `vi`)<br>- Cover: happy path, error cases, edge cases, boundary values<br>- Structure every test as Arrange → Act → Assert<br>- Mock external deps: `vi.mock(&#39;../lib/db&#39;, () =&gt; ({ prisma: { ... } }))`<br>- Name tests as sentences: `&#39;should throw AppError when tenantId is missing&#39;`<br><br>One test = one assertion focus. No multi-assertion tests.<br>Write the complete test file. Nothing else.</pre><p><strong>The workflow shift this creates:</strong> You write the function. You type /write-unit-tests. Done. No mental context-switching into &quot;test mode.&quot; No re-explaining your stack.</p><blockquote><strong>The thing nobody tells you about prompt files:</strong> They’re not just for code. /write-pr-description, /draft-architecture-doc, /summarise-this-file — any repeated Copilot Chat task becomes a one-liner. Start with the three you use most.</blockquote><h4>Pillar 3: .skill.md Files — Playbooks for Complex Work</h4><p><strong>One sentence:</strong> When a task is too nuanced for a prompt, write the full playbook and let Copilot follow it.</p><p>A prompt file says <em>“do this.”</em> A skill file says <em>“here’s how to master this entire category of work”</em> — with decision trees, common mistakes, and step-by-step sequences.</p><p>Use skill files for things that go wrong in specific ways when done without context. Database migrations are the classic example.</p><pre>.github/<br>└── skills/<br>    └── database-migration.skill.md</pre><h4>Skill File: Database Migration</h4><pre># Skill: Safe Database Migration<br><br>## When to Use This<br>Any time a Prisma schema change needs a migration.<br><br>---<br><br>## Step 1: Classify the Change<br>Before writing anything:<br>- **Additive** (new table, new nullable column, new index) → usually safe in one step<br>- **Destructive** (rename, drop, make nullable→required) → always two migrations<br><br>If destructive: stop. Plan a two-step migration. Document it in `docs/decisions/`.<br><br>---<br><br>## Step 2: Schema Rule<br>Non-nullable new columns MUST have a `@default`. No exceptions.<br>All new tables need: `id`, `createdAt`, `updatedAt`, `deletedAt?`, `tenantId`.<br><br>---<br><br>## Step 3: Generate<br>```bash<br>npx prisma migrate dev --name add_department_to_employees<br>```<br>Naming: `verb_column_to_table` or `create_table_name`.<br><br>---<br><br>## Step 4: Review the SQL<br>Open `prisma/migrations/[timestamp]/migration.sql`. Check for:<br>- `ADD COLUMN` without a default on a live table → will fail in prod<br>- `DROP COLUMN` → is any code still reading this?<br>- `RENAME` → deploy in two steps: add new → migrate data → remove old<br><br>---<br><br>## Common Mistakes (That Will Ruin Your Day)<br>| Mistake | What Happens | Fix |<br>|---|---|---|<br>| NOT NULL column, no default | Migration fails on existing rows | Always add `@default()` |<br>| Drop column in one step | Old app version crashes | Two-step: deprecate first |<br>| Rename in one migration | Same crash | Add new + copy data + remove old |</pre><p>Now when you say <em>“help me add a column to the Employee table,”</em> Copilot doesn’t just write the schema change. It classifies the risk, checks for defaults, generates the migration, reviews the SQL, and flags the footguns — because you wrote the playbook.</p><blockquote><strong>What makes skill files different from just “better prompts”:</strong> Prompts are inputs. Skills are <em>judgment</em>. A skill file teaches Copilot when to slow down, when to ask a question, and what to check before acting. That’s the difference between a fast typist and a careful engineer.</blockquote><h4>Pillar 4: Agents — When Copilot Does the Whole Job</h4><p><strong>One sentence:</strong> Stop asking Copilot questions. Give it a <em>role</em> and let it run.</p><p>An agent isn’t a suggestion. It’s an AI with a defined job, a set of tools, and the autonomy to complete an entire workflow — reading files, writing code, running commands — without you steering every step.</p><p>Think of it like the difference between asking a contractor <em>“how would you fix this?”</em> and handing them the keys and saying <em>“fix it.”</em></p><h4>The Test Coverage Agent</h4><p>The most immediately useful agent you can configure. Drop this in .github/agents/test-agent.md:</p><pre># Agent: Test Coverage<br><br>## Your Role<br>You are a testing specialist. When invoked on a file, you write complete,<br>meaningful tests for it. You don&#39;t summarise. You don&#39;t explain. You write tests.<br><br>## Before You Write Anything<br>1. Read the entire source file<br>2. Check if a test file already exists — don&#39;t duplicate<br>3. List every exported function and every error path<br><br>## What You Cover<br>- Happy path with realistic inputs<br>- Every error condition (`AppError` throws)<br>- Boundary values: empty array, null, zero, very long strings<br>- Side effects: mock Prisma, mock logger, mock external APIs<br><br>## Your Standards<br>- One assertion focus per test — split complex checks<br>- Arrange / Act / Assert with a blank line between phases<br>- Test names read as sentences: `&#39;should return 404 when employee not found&#39;`<br>- Mock at the boundary — mock Prisma, not internal service calls<br>- Target: 90%+ branch coverage<br><br>## Output<br>Complete test file. Then a short list of anything you couldn&#39;t test and why.</pre><h4>The Onboarding Agent</h4><p>Your new team member’s best friend on day one:</p><pre># Agent: Developer Onboarding<br><br>## Your Role<br>Help new developers get set up and oriented without interrupting the team.<br>Be patient, specific, and encouraging. Never say &quot;just&quot; or &quot;it&#39;s easy.&quot;<br><br>## When Someone Says &quot;I&#39;m new, help me start&quot;<br><br>### Check Their Environment First<br>```bash<br>node --version   # needs 20+<br>npm --version    # needs 9+<br>psql --version   # needs 14+<br>```<br>Report what&#39;s missing before doing anything else.<br><br>### Then Set Up<br>```bash<br>cp .env.example .env &amp;&amp; npm install<br>npx prisma generate &amp;&amp; npx prisma migrate dev<br>npm run seed &amp;&amp; npm test<br>```<br><br>### Then Orient Them<br>Read and summarise in 2–3 sentences each:<br>- `README.md` → what does this product do?<br>- `src/lib/errors.ts` → how do we handle errors?<br>- `prisma/schema.prisma` → what&#39;s the data model?<br>- `src/api/middleware/auth.ts` → how does auth work?<br><br>### Finally<br>Find open issues tagged `good-first-issue`. Suggest one that matches<br>their experience level and explain why it&#39;s a good starting point.</pre><blockquote><strong>The mindset shift with agents:</strong> You’re not writing a prompt. You’re hiring a specialist. Define the role clearly, give them standards, and get out of the way. The more specific the role, the better the output. A vague agent is as useless as a vague job description.</blockquote><h4>The Complete .github/ Structure</h4><pre>.github/<br>├── copilot-instructions.md          ← Always on. Always read.<br>│<br>├── prompts/<br>│   ├── new-api-endpoint.prompt.md   ← /new-api-endpoint<br>│   ├── write-unit-tests.prompt.md   ← /write-unit-tests<br>│   ├── create-react-component.prompt.md<br>│   └── write-pr-description.prompt.md<br>│<br>├── skills/<br>│   ├── database-migration.skill.md<br>│   ├── debugging-playbook.skill.md<br>│   └── code-review-checklist.skill.md<br>│<br>├── agents/<br>│   ├── test-agent.md<br>│   └── onboarding-agent.md<br>│<br>└── PULL_REQUEST_TEMPLATE.md         ← Copilot Chat uses this for PR summaries</pre><h4>Start Here Based on Where You Are</h4><p><strong>🟢 Brand new to Copilot (30 min)</strong> Create copilot-instructions.md. Add your stack, 3 rules, 2 &quot;never do this&quot; lines. That&#39;s it. You&#39;ll feel the difference today.</p><p><strong>🟡 Been using Copilot a while (2 hours)</strong> Fill out your instructions file properly. Add 2–3 prompt files for your most repeated tasks. Test each one in Copilot Chat.</p><p><strong>🔴 Want the full setup (half a day)</strong> Instructions + prompts + skill files + at least one agent. Start with the test agent — it delivers value immediately and costs nothing to configure.</p><h4>The One Line That Matters</h4><blockquote><em>Copilot is only as smart as the context you give it.</em></blockquote><p>The developers who feel like Copilot genuinely <em>knows</em> their project aren’t using a different tool. They’re using the same tool with four markdown files you now know how to write.</p><p>Create .github/copilot-instructions.md before you write another line of code today. Everything else in this article builds from that one file.</p><h4>Quick Reference</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/670/1*uTDEqDWuPAgmxOvdZiOCtQ.png" /><figcaption>Github Copilot — Markdown Quick Reference</figcaption></figure><p><em>Part 3 is coming — covering how teams share these files across repos and keep Copilot context in sync as the codebase grows.</em></p><p><em>If this saved you time, share it with the developer on your team who’s still hitting Tab and sighing.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=72eb9f34a5db" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[I Spent 3 Days Fighting GitHub Copilot. Then I Found the Files That Changed Everything.]]></title>
            <link>https://apurvsheth.medium.com/i-spent-3-days-fighting-github-copilot-then-i-found-the-files-that-changed-everything-b1423e64ffac?source=rss-a27130eabf4a------2</link>
            <guid isPermaLink="false">https://medium.com/p/b1423e64ffac</guid>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[github-copilot]]></category>
            <dc:creator><![CDATA[Apurv Sheth]]></dc:creator>
            <pubDate>Thu, 02 Apr 2026 02:31:01 GMT</pubDate>
            <atom:updated>2026-04-02T02:31:01.508Z</atom:updated>
            <content:encoded><![CDATA[<p>Most developers use 20% of what Copilot can do. Here’s the other 80%.</p><p>You’ve felt this before.</p><p>You install GitHub Copilot, start typing, and watch it confidently suggest code that completely ignores your architecture, your naming conventions, your entire tech stack.</p><p>You hit Tab anyway. You fix it. You move on.</p><p>And slowly, Copilot becomes just a faster autocomplete. A $10/month tab key.</p><p>Here’s what nobody tells you: Copilot isn’t dumb. It’s blind. And a handful of markdown files are the difference between a distracted intern and a senior engineer who actually knows your codebase.</p><p>Let me show you exactly what those files are — and what happens when you add them.</p><h4>The “Aha” Moment Most Copilot Users Never Have</h4><p>Imagine you hire a brilliant engineer. First day on the job, you hand them a laptop with the codebase and say nothing. No README. No architecture docs. No conventions guide.</p><p>They’d write decent code. But it wouldn’t feel like your code.</p><p>Now imagine you give them a 2-page brief: how your system works, what patterns you use, what to avoid. Suddenly their output feels like it came from the inside.</p><p>That’s exactly what’s happening under the hood with Copilot. It reads:</p><ul><li>What files you have open</li><li>Your file and folder names</li><li>Your comments and JSDoc</li><li>And — this is the big one — <strong>specific markdown files you’ve probably never created</strong></li></ul><p>Let’s fix that right now.</p><h4>The File That Changes Everything: .github/copilot-instructions.md</h4><p>This is not a secret. It’s just criminally underdiscussed.</p><p>GitHub Copilot reads .github/copilot-instructions.md as a <strong>persistent instruction set</strong> for your entire repository. It&#39;s the first thing you should create in any project you care about.</p><p>Here’s what it looks like for a real Node.js + React + PostgreSQL project:</p><pre># Copilot Instructions<br><br>## What This Project Is<br>Multi-tenant SaaS for restaurant inventory management.<br>Backend: Node.js 20, Express 5, Prisma ORM.<br>Frontend: React 18, TypeScript 5, TailwindCSS.<br>Database: PostgreSQL 16.<br><br>## The Rules Copilot Must Follow<br><br>### Architecture<br>- Services live in `src/services/` — routes never touch the DB directly<br>- Every DB query MUST include a `tenantId` filter (multi-tenant isolation)<br>- Use `AppError` from `src/lib/errors.ts` — never throw raw errors<br>- Log using `logger` from `src/lib/logger.ts` — never use `console.log`<br><br>### TypeScript<br>- No `any`. Ever.<br>- All functions need explicit return types<br>- Validate all external input with Zod<br><br>### Never Do This<br>- Raw SQL strings — use Prisma query builder<br>- Hard imports from `lodash` — use `import debounce from &#39;lodash/debounce&#39;`<br>- Class components in React</pre><p><strong>Before this file</strong>, Copilot suggests generic user creation:</p><pre>async function createUser(name: string, email: string) {<br>  const user = await db.users.create({ name, email });<br>  return user;<br>}</pre><p>No tenant scoping. No error handling. No validation. Looks fine, breaks in production.</p><p><strong>After this file</strong>, you type the same prompt and get:</p><pre>async function createUser(<br>  tenantId: string,<br>  input: CreateUserInput<br>): Promise&lt;User&gt; {<br>  const validated = CreateUserSchema.parse(input);<br><br>  const existing = await prisma.user.findFirst({<br>    where: { email: validated.email, tenantId, deletedAt: null },<br>  });<br><br>  if (existing) {<br>    throw new AppError(&#39;User already exists&#39;, 409);<br>  }<br><br>  const user = await prisma.user.create({<br>    data: { ...validated, tenantId },<br>  });<br><br>  logger.info({ userId: user.id, tenantId }, &#39;User created&#39;);<br>  return user;<br>}</pre><p>Same prompt. Completely different output. That’s not magic — that’s context.</p><h4>The Directory Structure That Makes Copilot Actually Smart</h4><p>Structure isn’t just for humans. The way you name and organize your folders is live context for every suggestion Copilot makes.</p><pre>my-saas-app/<br>│<br>├── .github/<br>│   ├── copilot-instructions.md   ← 🧠 The brain<br>│   ├── PULL_REQUEST_TEMPLATE.md  ← Copilot Chat reads this for PR summaries<br>│   └── workflows/<br>│<br>├── docs/                         ← 📚 Architecture context<br>│   ├── architecture.md<br>│   ├── api-reference.md<br>│   └── decisions/                ← Why you made key choices<br>│       ├── 001-use-prisma.md<br>│       └── 002-rest-over-graphql.md<br>│<br>├── src/<br>│   ├── api/<br>│   │   ├── routes/               ← Copilot knows: routing layer<br>│   │   └── middleware/           ← Copilot knows: cross-cutting concerns<br>│   ├── services/                 ← Copilot knows: business logic lives here<br>│   ├── lib/<br>│   │   ├── errors.ts             ← Referenced in instructions → always suggested<br>│   │   ├── logger.ts             ← Referenced in instructions → always suggested<br>│   │   └── db.ts<br>│   └── utils/<br>│<br>├── tests/<br>│   ├── unit/<br>│   └── e2e/<br>│<br>├── README.md                     ← 🚪 First impression<br>└── CONTRIBUTING.md               ← Dev workflow context</pre><p>Notice how a folder named services/ tells Copilot <em>this is where business logic lives</em> — and it will suggest service-layer patterns (not raw DB calls) when you&#39;re working there. A folder named middleware/ gets middleware patterns. Names matter more than you think.</p><h4>Your README Is Doing Half the Work (Or It Should Be)</h4><p>Most READMEs are install instructions and a badge collection. That’s wasted potential.</p><p>The section that pays off most for Copilot? <strong>Key Concepts.</strong> This is where you explain your domain model — and Copilot will use it to reason about your code.</p><pre># RestaurantOS Inventory API<br><br>## Quick Start<br>```bash<br>cp .env.example .env &amp;&amp; npm install<br>npx prisma migrate dev<br>npm run dev<br>```<br><br>## Key Concepts — Read This First<br><br>**Tenant Isolation**: Every database query is scoped by `tenantId`.<br>If you forget this, you expose one restaurant&#39;s data to another.<br>There are no exceptions.<br><br>**Soft Deletes**: Records are never hard-deleted.<br>Always filter by `deletedAt: null` in queries.<br>The `deletedAt` field is your &quot;is this gone?&quot; check.<br><br>**Audit Trail**: Every mutation automatically writes to `audit_logs`.<br>You don&#39;t call this manually — the Prisma middleware handles it.<br><br>**The Service Contract**: Routes call services. Services call the DB.<br>Routes never touch Prisma directly. This keeps logic testable.</pre><p>Now when you’re in a route file and type const result = await, Copilot suggests calling a service function — not a Prisma query. Because it read your README.</p><h4>Architecture Decision Records: The Underrated Power Move</h4><p>ADRs are short docs that explain <em>why</em> you made a technical decision. They live in docs/decisions/.</p><p>Most developers skip them. That’s a mistake — for humans <em>and</em> for Copilot.</p><pre># ADR 002: REST over GraphQL<br><br>## Status: Accepted<br><br>## Why We Chose This<br>Our client is a mobile app with fixed, well-defined data requirements.<br>GraphQL&#39;s flexibility adds complexity without benefit for our use case.<br>Our team has deep REST experience; GraphQL would slow us down.<br><br>## Consequences<br>- All APIs follow `/api/v1/resource/:id` conventions<br>- Do NOT introduce GraphQL resolvers or schema files<br>- Response shape is always `{ data, error, meta }`<br>- Pagination uses cursor-based approach (not offset)</pre><p>The next time Copilot thinks about suggesting a GraphQL resolver, it won’t. Because you told it why that door is closed.</p><h4>The Comment That Saves You 10 Minutes Per Function</h4><p>File-level context is powerful. Function-level context is <em>immediate</em>. A good JSDoc comment is Copilot telling itself what to write next.</p><pre>/**<br> * Fetches inventory items for a tenant with optional filtering.<br> *<br> * IMPORTANT: Always scoped to tenantId. Never returns cross-tenant data.<br> *<br> * @param tenantId - UUID of the tenant (mandatory, enforced at query level)<br> * @param options.lowStockOnly - Filter to items below reorder threshold<br> * @param options.categoryId - Optional category UUID filter<br> * @returns Paginated inventory items with current stock levels<br> * @throws {AppError} 404 if tenant does not exist<br> *<br> * @example<br> * // Get all low-stock items for a tenant<br> * const result = await getInventoryItems(&#39;tenant-abc&#39;, { lowStockOnly: true });<br> */<br>export async function getInventoryItems(<br>  tenantId: string,<br>  options: InventoryQueryOptions = {}<br>): Promise&lt;PaginatedResult&lt;InventoryItem&gt;&gt; {<br>  // Copilot now writes the entire body correctly — tenantId scoped, paginated, typed</pre><p>Write the JSDoc first. Then let Copilot write the function body. This workflow is faster than writing the function and then the docs.</p><h4>The Priority Ladder: What Copilot Weighs Most</h4><p>Not all context is equal. Here’s how to think about it:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/682/1*eeGPSVFsIm6O-SzGVRWWlw.png" /></figure><p>The top three are free wins. Most developers have none of them configured.</p><h4>The 15-Minute Setup That Unlocks Everything</h4><p>If you take nothing else from this article, do this:</p><p><strong>Step 1</strong> — Create .github/copilot-instructions.md with:</p><ul><li>Your tech stack (versions matter)</li><li>Two or three architectural rules</li><li>Two or three things Copilot should never do</li></ul><p><strong>Step 2</strong> — Add a “Key Concepts” section to your README that explains your domain in plain English — not installation steps.</p><p><strong>Step 3</strong> — Write JSDoc <em>before</em> you write functions. Let Copilot fill in the body.</p><p>That’s it. That’s the 80% most developers skip.</p><h4>The Honest Truth About Copilot</h4><p>Copilot isn’t going to replace you. But a developer who configures it well will consistently outproduce one who doesn’t — not because they type faster, but because they spend less time fixing suggestions that missed the point.</p><p>The developers winning with AI tools right now aren’t the ones with the best prompts. They’re the ones who built the best context.</p><p>Your markdown files are that context.</p><p>Start with .github/copilot-instructions.md. Do it today. The tab key is about to get a lot smarter.</p><p><em>If this helped you, follow for more on AI-assisted development, TypeScript architecture, and building software that doesn’t fight you back.</em></p><p><em>Share this with the developer on your team who said “Copilot isn’t that useful.” They haven’t seen it set up right yet.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b1423e64ffac" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Hands-On Implementation of Model Context Protocol (MCP) with Spring AI]]></title>
            <link>https://apurvsheth.medium.com/hands-on-implementation-of-model-context-protocol-mcp-with-spring-ai-106b9e4023d9?source=rss-a27130eabf4a------2</link>
            <guid isPermaLink="false">https://medium.com/p/106b9e4023d9</guid>
            <category><![CDATA[agentic-ai]]></category>
            <category><![CDATA[spring-ai]]></category>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[spring-boot]]></category>
            <category><![CDATA[mcps]]></category>
            <dc:creator><![CDATA[Apurv Sheth]]></dc:creator>
            <pubDate>Tue, 03 Mar 2026 13:31:00 GMT</pubDate>
            <atom:updated>2026-03-03T14:01:17.127Z</atom:updated>
            <content:encoded><![CDATA[<p>Building with Model Context Protocol (MCP): Practical Implementation Using Spring Boot &amp; Spring AI</p><p>In the <a href="https://medium.com/@apurvsheth/understanding-the-model-context-protocol-mcp-the-concept-315b6014f5c2">previous</a> post, we covered <strong>why</strong> the Model Context Protocol (MCP) exists and what problem it solves. Now let’s roll up our sleeves and build real working examples — no prior MCP knowledge required. We’ll use <strong>Spring Boot</strong> and <strong>Spring AI</strong>, which offer excellent, production-ready support for MCP servers and clients.</p><h3>Quick Recap: MCP Architecture</h3><p><strong>MCP Client </strong>— the AI application (e.g., your chat app powered by Claude or OpenAI).<br><strong>MCP Server </strong>— exposes tools, resources, or prompts.</p><p>Communication is standardized (JSON-RPC), secure, and supports multiple transports.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/711/1*uR3_qvT9kivuL_O-nEvn8w.png" /><figcaption>spring-ai + MCP</figcaption></figure><p>Spring AI simplifies this with Boot starters and annotations — you barely write protocol code.</p><h3>Example 1: Building a Simple MCP Server (Expose Tools)</h3><p><strong>Goal</strong>: Create a server that lets an AI query author information from a fictional blog database.</p><p>1. <strong>Create a Spring Boot project</strong> (use start.spring.io or your IDE).</p><p>2. <strong>Add dependencies</strong> (Maven/Gradle):</p><pre>xml<br>&lt;dependency&gt;<br> &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;<br> &lt;artifactId&gt;spring-boot-starter-web&lt;/artifactId&gt;<br>&lt;/dependency&gt;<br>&lt;dependency&gt;<br> &lt;groupId&gt;org.springframework.ai&lt;/groupId&gt;<br> &lt;artifactId&gt;spring-ai-starter-mcp-server-webmvc&lt;/artifactId&gt;<br> &lt;! — Check latest version on Maven Central →<br>&lt;/dependency&gt;</pre><p>3. <strong>Define tools</strong> with `<a href="http://twitter.com/Tool">@Tool</a>` annotation:</p><pre><br>import org.springframework.ai.mcp.annotation.Tool;<br>import org.springframework.stereotype.Service;<br>import java.util.List;<br><br>@Service<br>public class AuthorService {<br>@Tool(description = &quot;Get author details by article title&quot;)<br> public Author getAuthorByArticleTitle(String articleTitle) {<br> // In real app: query DB<br> return new Author(&quot;John Doe&quot;, &quot;john@baeldung.com&quot;, &quot;Senior Writer&quot;);<br> }<br>@Tool(description = &quot;Get list of top-rated authors&quot;)<br> public List&lt;Author&gt; getTopAuthors() {<br> return List.of(<br> new Author(&quot;John Doe&quot;, &quot;john@baeldung.com&quot;, &quot;Senior Writer&quot;),<br> new Author(&quot;Jane Smith&quot;, &quot;jane@baeldung.com&quot;, &quot;Tech Lead&quot;)<br> );<br> }<br>public record Author(String name, String email, String role) {}<br>}</pre><p>4. <strong>Register tools</strong> as a bean:</p><pre><br>import org.springframework.ai.mcp.tool.MethodToolCallbackProvider;<br>import org.springframework.context.annotation.Bean;<br>import org.springframework.context.annotation.Configuration;<br><br>@Configuration<br>public class McpServerConfig {<br>@Bean<br> public MethodToolCallbackProvider authorTools(AuthorService authorService) {<br> return MethodToolCallbackProvider.builder()<br> .toolObjects(authorService)<br> .build();<br> }<br>}</pre><p>Run the app — Spring AI starts an MCP server (default: <a href="http://localhost:8080/">http://localhost:8080</a>). The AI can now discover and call these tools automatically.</p><h3>Example 2: Building an MCP Client &amp; Integrating with AI</h3><p>Goal: Let an AI-powered endpoint use the server above.</p><p>1. <strong>Add client starter</strong>:</p><pre><br>&lt;dependency&gt;<br> &lt;groupId&gt;org.springframework.ai&lt;/groupId&gt;<br> &lt;artifactId&gt;spring-ai-starter-mcp-client-sse&lt;/artifactId&gt;<br>&lt;/dependency&gt;</pre><p>2. <strong>Configure</strong> (application.yml):</p><pre><br>spring:<br> ai:<br>   mcp:<br>    client:<br>      sse:<br>        connections:<br>         blog-server:<br>           url: http://localhost:8080</pre><p>3. <strong>Use with ChatClient</strong> (e.g., OpenAI or Ollama):</p><pre><br>import org.springframework.ai.chat.client.ChatClient;<br>import org.springframework.web.bind.annotation.GetMapping;<br>import org.springframework.web.bind.annotation.RestController;<br><br>@RestController<br>public class AiQueryController {<br>private final ChatClient chatClient;<br>public AiQueryController(ChatClient.Builder builder) {<br> this.chatClient = builder.build();<br> }<br>@GetMapping(&quot;/ask&quot;)<br> public String askWhoWroteTutorial() {<br> return chatClient.prompt()<br> .user(&quot;Who wrote the Spring AI MCP tutorial?&quot;)<br> .call()<br> .content();<br> // AI auto-discovers &amp; calls getAuthorByArticleTitle()<br> }<br>}</pre><p>When the AI needs info, it uses the MCP connection — no manual tool schemas required.</p><h3>Summary &amp; Next Steps</h3><p>With just a few annotations and starters, Spring AI makes MCP feel like magic: expose tools once, and any compatible AI can use them. Scale this to real databases, file systems, or enterprise APIs — the protocol handles security and transport.</p><p>Try it yourself:<br> — Start with the official Spring AI MCP docs.<br> — Experiment with transports (HTTP → SSE → WebSocket for real-time)<br> — Combine multiple servers for powerful agents.</p><p>MCP + Spring AI is one of the cleanest ways to build production AI integrations today. Questions or want to extend this example? Let me know in the comments.</p><p>Happy coding!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=106b9e4023d9" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>