{"id":2201,"date":"2026-04-25T06:35:40","date_gmt":"2026-04-25T06:35:40","guid":{"rendered":"https:\/\/www.rajeshkumar.xyz\/blog\/?p=2201"},"modified":"2026-04-25T06:35:40","modified_gmt":"2026-04-25T06:35:40","slug":"migrating-sdlc-from-human-to-ai-claude-codex","status":"publish","type":"post","link":"https:\/\/www.rajeshkumar.xyz\/blog\/migrating-sdlc-from-human-to-ai-claude-codex\/","title":{"rendered":"Migrating SDLC from Human to AI (Claude + Codex)"},"content":{"rendered":"\n<p><\/p>\n\n\n\n<p>This is a meaningful transition, and the good news is you don&#8217;t need to do it all at once. Here&#8217;s a pragmatic, phased approach that works well for an existing multi-microservice system.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Phase 0: Foundation (Before Any AI Work)<\/h2>\n\n\n\n<p>Before handing anything to AI, your codebase needs to be <strong>AI-readable<\/strong>. This is the single biggest predictor of success.<\/p>\n\n\n\n<p>Create a <code>\/docs<\/code> directory at the repo root (or per service) containing:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><code>ARCHITECTURE.md<\/code> \u2014 service boundaries, data flow, sync vs async communication, tech stack per service<\/li>\n\n\n\n<li><code>CLAUDE.md<\/code> (or <code>AGENTS.md<\/code> for Codex) \u2014 coding conventions, build\/test commands, do&#8217;s and don&#8217;ts, repo layout<\/li>\n\n\n\n<li><code>DOMAIN.md<\/code> \u2014 business glossary, entities, invariants<\/li>\n\n\n\n<li>ADRs (Architecture Decision Records) for past major decisions<\/li>\n\n\n\n<li>API contracts (OpenAPI\/Protobuf) checked into the repo<\/li>\n\n\n\n<li>Per-service <code>README.md<\/code> with run\/test\/deploy steps<\/li>\n<\/ul>\n\n\n\n<p>Without these, AI agents will hallucinate context. With these, they perform like a senior engineer who&#8217;s been onboarded.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Phase 1: Map Your Current SDLC Stages<\/h2>\n\n\n\n<p>For each stage, identify the inputs, outputs, and humans involved today:<\/p>\n\n\n\n<figure class=\"wp-block-table\"><table class=\"has-fixed-layout\"><thead><tr><th>Stage<\/th><th>Current Output<\/th><th>Owner<\/th><\/tr><\/thead><tbody><tr><td>Plan<\/td><td>Roadmap, epics<\/td><td>PM<\/td><\/tr><tr><td>Architecture<\/td><td>C4 diagrams, ADRs<\/td><td>Architect<\/td><\/tr><tr><td>HLD<\/td><td>Service-level design doc<\/td><td>Tech Lead<\/td><\/tr><tr><td>LLD<\/td><td>Class\/sequence diagrams, API specs<\/td><td>Senior Dev<\/td><\/tr><tr><td>Development<\/td><td>Code + PR<\/td><td>Dev<\/td><\/tr><tr><td>Testing<\/td><td>Unit\/integration\/E2E<\/td><td>Dev + QA<\/td><\/tr><tr><td>Security<\/td><td>SAST\/DAST\/dependency scan<\/td><td>SecOps<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n<p>This table becomes your migration checklist.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Phase 2: Tool Assignment<\/h2>\n\n\n\n<p>A reasonable split based on each tool&#8217;s strengths:<\/p>\n\n\n\n<p><strong>Claude (claude.ai, Claude Code, API)<\/strong> \u2014 better for ambiguous, document-heavy, reasoning-heavy work:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Plan refinement, requirement decomposition<\/li>\n\n\n\n<li>Architecture and HLD\/LLD generation<\/li>\n\n\n\n<li>ADR drafting, threat modeling<\/li>\n\n\n\n<li>Code review, security review of diffs<\/li>\n\n\n\n<li>Test strategy and test case generation<\/li>\n<\/ul>\n\n\n\n<p><strong>Codex (OpenAI&#8217;s coding agent)<\/strong> \u2014 better for in-IDE, repo-bound code generation:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Implementation tasks against tickets<\/li>\n\n\n\n<li>Refactors, boilerplate, scaffolding<\/li>\n\n\n\n<li>Writing the actual unit\/integration tests<\/li>\n<\/ul>\n\n\n\n<p>You don&#8217;t have to pick one \u2014 many teams run both and let each do what it&#8217;s best at.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Phase 3: Migrate Stage-by-Stage (Don&#8217;t Big-Bang It)<\/h2>\n\n\n\n<p>Start with the <strong>lowest-risk, highest-leverage<\/strong> stage and expand. Suggested order:<\/p>\n\n\n\n<p><strong>Step 1 \u2014 Testing &amp; Security Scanning first.<\/strong> These have objective pass\/fail criteria, so AI mistakes are caught automatically. Have Claude generate test cases from your API specs; have Codex implement them. Wire SAST (Semgrep, Snyk) into CI and have Claude triage findings.<\/p>\n\n\n\n<p><strong>Step 2 \u2014 LLD generation.<\/strong> Feed Claude an HLD + the relevant service code and ask for sequence diagrams, API contracts, and data models. Human reviews. Low blast radius if wrong.<\/p>\n\n\n\n<p><strong>Step 3 \u2014 Development on small tickets.<\/strong> Pick well-scoped tickets (bug fixes, small features in one service). Use Codex or Claude Code with your <code>CLAUDE.md<\/code>\/<code>AGENTS.md<\/code> in place. Require human PR review.<\/p>\n\n\n\n<p><strong>Step 4 \u2014 HLD and Architecture.<\/strong> Higher stakes. Use Claude to draft, but keep a human architect as final approver. Always produce ADRs.<\/p>\n\n\n\n<p><strong>Step 5 \u2014 Planning.<\/strong> Last, because it requires the most business context. AI assists with breakdown and estimation, humans set direction.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Phase 4: Guardrails (Non-Negotiable)<\/h2>\n\n\n\n<p>Regardless of stage, put these in place before going live:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Branch protection + mandatory human PR review<\/strong> on <code>main<\/code>. AI proposes, human disposes.<\/li>\n\n\n\n<li><strong>CI must pass<\/strong>: lint, unit tests, integration tests, SAST, dependency scan, container scan.<\/li>\n\n\n\n<li><strong>Sandbox execution<\/strong>: Claude Code and Codex should run in isolated environments, not against prod.<\/li>\n\n\n\n<li><strong>Secrets hygiene<\/strong>: never put live credentials in prompts or context. Use vault references.<\/li>\n\n\n\n<li><strong>Audit trail<\/strong>: log every AI-generated PR with the prompt and model used.<\/li>\n\n\n\n<li><strong>Rollback plan<\/strong>: per-service feature flags so AI-authored changes can be killed fast.<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">Phase 5: Define the Workflow<\/h2>\n\n\n\n<p>A typical end-to-end loop once mature:<\/p>\n\n\n\n<p>A ticket is filed, Claude reads it plus the relevant service docs and produces an LLD with API changes, data migrations, and a test plan. A human tech lead approves the LLD. Codex picks up the LLD and implements the change in a feature branch, generating tests as it goes. CI runs SAST, dependency scanning, and the full test suite. Claude reviews the resulting diff against the LLD and the security checklist, leaving comments on the PR. A human engineer does final review and merges.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Phase 6: Measure and Iterate<\/h2>\n\n\n\n<p>Track these from day one so you know if it&#8217;s working:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>PR cycle time (ticket \u2192 merge)<\/li>\n\n\n\n<li>Defect escape rate to staging\/prod<\/li>\n\n\n\n<li>Percentage of AI PRs merged without rework<\/li>\n\n\n\n<li>Security findings caught pre-merge vs post-merge<\/li>\n\n\n\n<li>Cost per ticket (token spend)<\/li>\n<\/ul>\n\n\n\n<p>If escape rate goes up, pull back scope. If cycle time and quality both improve, expand.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Practical Starting Point This Week<\/h2>\n\n\n\n<p>Pick <strong>one microservice<\/strong>, ideally one with decent test coverage and clear boundaries. Write its <code>CLAUDE.md<\/code> and <code>ARCHITECTURE.md<\/code>. Migrate just the testing and security-scanning stages for that one service. Run it for two sprints. Then expand.<\/p>\n\n\n\n<p>Trying to migrate all stages across all services simultaneously is the most common failure mode \u2014 the context burden becomes unmanageable and the team loses trust in the output.<\/p>\n\n\n\n<p><\/p>\n","protected":false},"excerpt":{"rendered":"<p>This is a meaningful transition, and the good news is you don&#8217;t need to do it all at once. Here&#8217;s [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-2201","post","type-post","status-publish","format-standard","hentry","category-uncategorized"],"_links":{"self":[{"href":"https:\/\/www.rajeshkumar.xyz\/blog\/wp-json\/wp\/v2\/posts\/2201","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.rajeshkumar.xyz\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.rajeshkumar.xyz\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.rajeshkumar.xyz\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.rajeshkumar.xyz\/blog\/wp-json\/wp\/v2\/comments?post=2201"}],"version-history":[{"count":1,"href":"https:\/\/www.rajeshkumar.xyz\/blog\/wp-json\/wp\/v2\/posts\/2201\/revisions"}],"predecessor-version":[{"id":2202,"href":"https:\/\/www.rajeshkumar.xyz\/blog\/wp-json\/wp\/v2\/posts\/2201\/revisions\/2202"}],"wp:attachment":[{"href":"https:\/\/www.rajeshkumar.xyz\/blog\/wp-json\/wp\/v2\/media?parent=2201"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.rajeshkumar.xyz\/blog\/wp-json\/wp\/v2\/categories?post=2201"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.rajeshkumar.xyz\/blog\/wp-json\/wp\/v2\/tags?post=2201"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}