Synthesis coding

Synthesis coding is the craft of building production-grade software through disciplined human–AI collaboration. The human provides architectural authority, judgment and quality standards; AI helps explore designs, implement changes and examine the results. The ambition is better software and more capable engineers. Code remains a durable source of truth: something the team can version, review, test and use to diagnose unexpected behavior.

Five principles

  1. Human architectural authority. Own the decisions that become expensive to reverse: module boundaries, data flow, where state lives, the security model and how the system fails. Ask AI to research alternatives and challenge assumptions; take responsibility for the commitment.
  2. Systematic quality standards. Generated code must meet the same standards for review, testing, security and performance as any other code. Faster production makes those standards more consequential. Use AI to help meet them, and examine whether the checks can reject a plausible mistake.
  3. Active system understanding. Stay close enough to explain what a module does, why it talks to another and what fails when load doubles. Reviewing a change should deepen that understanding. If the team cannot diagnose unexpected behavior under pressure, deepen its understanding or simplify the system.
  4. A self-improving system. Turn lessons into better project records, reusable skills, instructions and checks. Review how those changes work in subsequent tasks. The project, the team’s shared practices, the practitioner’s judgment and the wider discipline should improve together.
  5. Transferable knowledge. Leave code, decisions and rationale that another person, another AI tool and your future self can use. Keep project memory in records the project owns, and make the tool-specific loading steps explicit. Share useful methods across projects and crafts.

The principles reinforce each other. Understanding supports architectural judgment; quality checks reveal lessons; recorded lessons travel to the next task and strengthen the next decision. A useful review preserves the features and decisions that already matter while examining what the new code actually does.

Start with an expected result you can explain. Then choose a check capable of rejecting the mistake you are worried about.

Two implementations can agree on the same mistake

The independent-checks exercise uses this constructed front matter, the metadata block at the top of a Markdown document:

---
tags:
  - [tag1, tag2]
  - [tag3]
---
Body.

Each outer item is itself a sequence. The expected parsed value is:

{"tags": [["tag1", "tag2"], ["tag3"]]}

The exercise compares a library parser with a deliberately faulty producer that turns each inner sequence into a comma-separated string. A second failure case makes both paths return the same wrong value:

{"tags": ["tag1, tag2", "tag3"]}

Agreement cannot decide this case. Both outputs have lost the nested structure. The literal expectation, written from the intended syntax, rejects both.

CheckWhat it can establish
Compare the two outputsWhether those implementations agree.
Compare each with the reviewed expected valueWhether each preserves the required nested structure.
Inspect the trace before and after flatteningWhere the inner sequence became a string.

Run the existing example

Download the offline exercise. It contains the constructed inputs, literal expectations, programs and dependency licenses. From the extracted directory, use Node.js to run:

node exercise.cjs demo
node exercise.cjs parser shared-wrong

The demo shows the intended results. The shared-wrong command exits with status 1 because both outputs fail the expectation.

Put the check into a development task

Before implementation, give the assistant the intended behavior, relevant source and an input that could expose the suspected failure. Inspect the expectation yourself. If the implementation changes, keep the expectation tied to the requirement; do not regenerate it merely to match the new output.

For an existing feature, retain checks for behavior that must survive. For a batch edit, inspect the target files and proposed actions before applying them. A passing dry run still needs to identify the right records and operations.

The ownwords conversion case applies the same question to article boundaries: did the converter preserve the paragraph after a nested box, or did both the converter and checker stop too early?

Articles and next steps

Browse the full archive or follow the coding feed. The code-planning and implementation-integrity instructions are maintained in the public source repository. Rajiv Pant wrote the methods and cases linked here. A useful contribution includes the failing input, intended result and evidence that the proposed correction addresses it.

Coding articles

Subscribe by RSS

  1. Coding

    Preserve publication timestamps without changing an article's calendar date

    Preserve the instant in article metadata while keeping the authored day in routes and labels. A JavaScript example covers offsets, feeds and legacy dates.

    Rajiv Pant

  2. Coding

    Testing a Codex skill: when it runs and what it produces

    Test a Codex skill with explicit, implicit, contextual, and negative prompts, then grade its output against a concrete rubric with checked examples and limits.

    Rajiv Pant

  3. Coding

    Multiple folders in Codex: choosing the primary folder

    Choose a Codex project's primary folder deliberately, map Git and instruction defaults, and check folder access before a change spans multiple repositories.

    Rajiv Pant

  4. Coding

    Prepare a checkable handoff from ChatGPT Work to Codex

    Prepare a ChatGPT Work task for Codex with a checked input folder, accepted decisions and executable expected results. Run the local example before adapting it.

    Rajiv Pant

  5. Coding

    Turning a Failed Code Review into Tests and Repairs

    A failed AI code review becomes a practical method for turning concrete findings into regression tests, repairs and a rereview with clearly stated limits.

    Rajiv Pant

  6. Coding

    “Not found” is not “does not exist”

    Check “not found” with bounded search, positive controls and complete output. A withdrawn-draft case separates editorial status from deployment history.

    Rajiv Pant

  7. Coding

    I cut my agent’s instruction file by 62% and kept every rule

    How I cut an agent instruction file from 54,825 to 21,026 bytes while preserving its rules, with a migration method and a workbook for checking their new homes.

    Rajiv Pant

  8. Coding

    What My Checks Missed After an AI Agent Deleted 474 Files

    My first checks of a bookmark cleanup passed. A second extraction found 196 missing URLs. The case shows how to check preservation against the source inventory.

    Rajiv Pant

  9. Coding

    When a Commit Guard Cannot Run, It Must Block

    A missing Python dependency let my commit guard pass without scanning. Distinguish clean results from broken checks, test exceptions and monitor guard health.

    Rajiv Pant

  10. Coding

    I told a sub-agent to check before committing. Minutes later, I didn't.

    Three multi-agent coding incidents taught me to inspect the shared Git index, write concrete briefs, and keep untested claims visible through every handoff.

    Rajiv Pant

  11. Coding

    Your Coding Agent Should Watch Its Own Work Run

    Use authorized browser actions, screenshots and state checks to test a coding change in the running app, keeping visual and behavioral evidence distinct.

    Rajiv Pant

  12. Coding

    Prompt discipline is engineering infrastructure

    Prompt discipline is engineering infrastructure: a forbidden-phrase catalog, hooks, and enforcement that catch AI coding agents dressing shortcuts as judgment.

    Rajiv Pant

  13. Coding

    The architecture of an open-source slop detector

    How Slopcheck combines analysis planning, hosted controls and shared routing for a free public tool, with source tests of cost, data and enforcement boundaries.

    Rajiv Pant

  14. Coding

    One context file carried a redesign across eight AI sessions

    A single CONTEXT.md carried an editor redesign across eight AI coding sessions. The ownership split that made it work: humans direct, the AI keeps the record.

    Rajiv Pant

  15. Coding

    Three Ragbot releases, one architectural shift

    How Ragbot’s three releases joined local models, tools, skills, memory and policy into a conversational runtime, with the engineering choices behind the shift.

    Rajiv Pant

  16. Coding

    Every bug report is now a patch-or-redesign decision

    The minimal patch is a habit from when understanding was expensive. AI coding agents ended that economy, and most of us never consciously make the choice.

    Rajiv Pant

  17. Coding

    Postel's Law for AI-Written Documents

    Three bugs in my daily-plan dashboard led to shared vocabulary and tolerant rendering. The case shows where strict contracts belong and how to check both sides.

    Rajiv Pant

  18. Coding

    Demo mode as a pattern for software

    Build demo mode into software so users can explore it with realistic sample data. A console case shows the design, testing, privacy and onboarding choices.

    Rajiv Pant

  19. Coding

    Synthesis Console: open-source tooling for synthesis engineering

    I built a local console for projects, lessons and daily plans. File conventions, a small dependency budget and portable configuration shape its architecture.

    Rajiv Pant

  20. Coding

    Transferable Knowledge: The Fifth Pillar of Synthesis Coding

    Transferable Knowledge makes AI-assisted work useful across people, tools, crafts, time and organizations through shared decisions and maintainable code.

    Rajiv Pant

  21. Coding

    When All Tests Pass, Check the Whole Change

    A missing field survived 1,297 passing tests. Trace it from request to database, check each service and use seven review passes to find incomplete changes.

    Rajiv Pant

  22. Coding

    Stop asking me: Claude Code permissions for authorized work

    Reduce repeated prompts with a scoped Claude Code permission policy, distinguishing allowed commands, sandbox limits and actions that still need authorization.

    Rajiv Pant

  23. Coding

    The blast radius principle: checking targets before destructive commands

    Use path checks, previews and a tested recovery plan to limit AI-generated cleanup commands, with a complete exercise that removes no files.

    Rajiv Pant

  24. Coding

    Managing AI agent skills at scale: a three-repo architecture

    A three-repository architecture for public, private and team AI skills, with provenance, dependency boundaries and a method for merging local improvements.

    Rajiv Pant

  25. Coding

    Synthesis Skills: install methodology directly into your AI workflow

    Install reusable Synthesis Skills for code review, writing, and project continuity, with current setup guidance and the lessons behind the original release.

    Rajiv Pant

  26. Coding

    Synthesis merging: what happens after the first PR

    Integrate overlapping pull requests in dependency order, check the combined result, credit contributors and help the team take ownership of integration.

    Rajiv Pant

  27. Coding

    Turning code review findings into a tested upgrade plan

    Turn code review findings into an upgrade plan that preserves domain behavior, addresses urgent risks and defines evidence for each change before work begins.

    Rajiv Pant

  28. Coding

    What reviewing real codebases taught me about code review

    Reviewing the wrong branch led to better baselines, closer test inspection and clearer reports. See what comparisons prove, and what they leave unknown.

    Rajiv Pant

  29. Coding

    Recommend A, implement A: checking an AI agent’s work against the plan

    Check whether AI-generated code follows the agreed plan and whether that plan meets the requirements, using filename collisions to test both independently.

    Rajiv Pant

  30. Coding

    When Someone Else Contributes to Your Synthesis-Coded Project

    Review contributions against your current architecture, adapt what needs changing, and build the shared standards that let good work merge with less rework.

    Rajiv Pant

  31. Coding

    Verifying AI-Written Code with Independent Checks

    Use independent expectations, parser comparisons, staged probes and reviewed dry runs to find mistakes in AI-written code before acting on its output.

    Rajiv Pant

  32. Coding

    Bidirectional Learning in Synthesis Coding: When Human and AI Teach Each Other

    Bidirectional learning in synthesis coding: humans teach AI through context, prompts, and review; AI teaches back by surfacing blind spots and edge cases.

    Rajiv Pant

  33. Coding

    The research lineage from recursive neural networks to human-AI collaborative development

    Richard Socher's work on representations and language-based tasks suggests five research questions for building reliable software with human-AI collaboration.

    Rajiv Pant

  34. Coding

    From learned representations to engineered context: what Richard Socher's research tells us about working with AI

    Richard Socher's work on reusable representations offers a practical lens for persistent AI coding context, architectural foundations and disciplined review.

    Rajiv Pant

  35. Coding

    Code Review That Scales: Choosing Review Depth by Risk

    Use a tiered code-review runbook to choose review depth, override the tier for consequential risks, and record what was checked, excluded or left unverified.

    Rajiv Pant

  36. Coding

    Why Engineering Judgment Matters More With AI

    AI makes engineering judgment more valuable. Four experiences show how faster implementation changes refactoring, verification and what we choose to build.

    Rajiv Pant

  37. Coding

    Diagnosing Retrieval Failures in a RAG Application

    Use Ragbot’s biography lookup to separate routing, tokenization and ranking, then trace a context-budget change through five defaults from UI to retrieval.

    Rajiv Pant

  38. Coding

    Data Format Contracts for AI Pipelines

    Timestamp, pagination, rate-limit and configuration failures taught me to define explicit data contracts, then test what each component sends and accepts.

    Rajiv Pant

  39. Coding

    Keeping Claude Code Refactors Consistent Across Long Sessions

    Keep a long Claude Code refactor aligned with its conventions through instruction-loading checks, scoped code review and tests of the behavior being changed.

    Rajiv Pant

  40. Coding

    Build the Foundation Before Scaling AI Coding

    Set architectural direction, build a complete reference feature and test the next addition. A worked API example shows what coding agents should extend.

    Rajiv Pant

  41. Coding

    How Claude Code Uses CLAUDE.md and Memory

    Claude Code loads project instructions and saved memory under different rules. Check what survives compaction and whether the code follows your guidance.

    Rajiv Pant

  42. Coding

    What OpenAI's Sora Build Teaches Us About Synthesis Coding

    What OpenAI's Sora Android case teaches about synthesis coding: give agents context, establish patterns, plan changes, and lead the work as it scales.

    Rajiv Pant

  43. Coding

    Scaling Synthesis Coding in Your Organization

    Scale AI coding through a phased team rollout, role-specific training, quality standards and practical measures that build lasting engineering capability.

    Rajiv Pant

  44. Coding

    Building ownwords: A Synthesis Coding Case Study

    How I built ownwords to manage 53 articles in Markdown, with deliberate architecture, publishing checks and runnable conversion and permission examples.

    Rajiv Pant

  45. Coding

    Why Synthesis Coding Still Writes Code in the Age of LLMs

    Why better AI strengthens the case for code, shared understanding and review, with a family math puzzle, a runnable median example and three practical prompts.

    Rajiv Pant

  46. Coding

    Vibe Coding and Synthesis Coding: Two Complementary Approaches

    Use conversational exploration to test ideas and synthesis coding to build software people can depend on, with practical guidance for moving between the two.

    Rajiv Pant

  47. Coding

    Polyrepo Synthesis: Working Across Repositories with Claude Code and VS Code

    Configure Claude Code and VS Code for cross-repository work, map shared dependencies, and test both direct and indexed consumers after a schema change.

    Rajiv Pant

  48. Coding

    Modernizing a 17-Year-Old WordPress Plugin with Claude Code

    A 2025 modernization of Blogroll Links: WordPress security and compatibility work with Claude Code, and why maintaining open-web software still matters.

    Rajiv Pant

  49. Coding

    Build a self-improving AI coding practice

    Improve AI coding through project context, skills, instructions, and practice. A team account and CSV exercise show how to carry useful lessons into later work.

    Rajiv Pant

  50. Coding

    Understanding the AI-generated code you ship

    Understand AI-generated code well enough to debug and change it. A cache example connects comprehension, review, and tests to sustained development speed.

    Rajiv Pant

  51. Coding

    Quality standards for AI-generated code

    Design a testing strategy, review generated code, and connect passing checks to real requirements. An empty-response example shows how a green suite can fail.

    Rajiv Pant

  52. Coding

    Human architectural authority in AI-assisted development

    How engineers keep AI-assisted development coherent: own architectural decisions, record their rationale, and use shared constraints to reduce costly rework.

    Rajiv Pant

  53. Coding

    Reviewing Claude Code’s Work: Security and Performance

    Four Claude Code cases show how engineering review improves authentication, caching, async calls, and security findings, with runnable local Python examples.

    Rajiv Pant

  54. Coding

    The synthesis coding framework: building production software with AI

    Five connected pillars turn AI-assisted coding into an organizational practice, with project cases, planning guidance, and a path to production software.

    Rajiv Pant

  55. Coding

    Synthesis coding: a professional practice for AI-assisted development

    Architectural judgment, systematic quality, and shared project knowledge make AI-assisted development a professional practice with lasting value for teams.

    Rajiv Pant