The synthesis coding framework: building production software with AI

After my earlier article on professional practice with AI, several CTOs reached out describing their approaches. An engineering director sent me their internal documentation. A startup founder asked how to implement this with a five-person team. They were working through similar questions: who makes the design decisions, how do we review the output, and how does a useful individual practice become something a team can rely on?

I use synthesis coding for the hands-on craft of developing software with AI assistance, and synthesis engineering for the broader discipline, including architecture, quality, operations, and team practice. The framework rests on five connected pillars: architectural authority, quality standards, active understanding, a self-improving system, and transferable knowledge.1

Terminology update prepared October 1, 2026: Synthesis work is now the umbrella for these practices. Synthesis engineering covers engineering work; synthesis coding names the software-development craft.

A project that grew through deliberate versions

I built an agentic workflow system: software that coordinates AI-assisted tasks, including work distributed among several agents. It evolved through versions v0.4 to v0.12, with each of the following releases adding a major capability.

VersionDecision I ownedImplementation and result
v0.4: user experienceEstablish quality expectations for status indicators, settings, and user feedback early.AI implemented UI components following the design system.
v0.8: prompt libraryMake prompts version-controlled, composable components, treating them as part of the system's intellectual property.The composition engine was 400 lines across nine task templates, with no breaking changes.
v0.9: authenticationUse Google OAuth, JWTs, PostgreSQL-backed sessions, and domain-restricted access.AI implemented routes, models, and middleware within those choices.
v0.10: PostgreSQL and concurrent workDiagnose a synchronous client blocking the event loop despite async syntax; specify an async client, bounded concurrency, and a database pool of 20 connections plus 10 overflow.The refactor updated six files. The workflow went from 90 seconds to 30 seconds, a threefold speedup in that case.
v0.11: orchestrationUse LangGraph for multi-agent workflows, stateful orchestration, and conditional routing.AI implemented the orchestration patterns within the existing system.
v0.12: model selectionGive users control over model cost and quality choices.AI implemented the configuration UI and backend model switching.

A semaphore limits concurrent work; provider request and token quotas need separate controls. The database pool bounds connection use. The technical case study explains how those controls fit together.

By v0.11, the project contained reusable code, documented architectural decisions, test patterns, and quality standards from earlier versions. Each version took less time while adding substantial capabilities. Accumulated context made the AI assistance more effective: each version could build on decisions and patterns we had already worked through.

Responsibility while working with AI

The human directs; the AI executes. The human verifies; the AI iterates.

AI can help investigate a design, compare alternatives, inspect code, find errors, and generate tests. A human owner remains responsible for the decisions and the release.

Think of it like managing a team of superpowered beings with vast knowledge and tireless work capacity. A skilled leader knows how to tap into each team member’s expertise, learn from their knowledge, delegate effectively, and course-correct when needed, while remaining in charge and accountable.

WorkHuman responsibilityUseful AI assistance
DesignDefine requirements and constraints; choose and explain consequential tradeoffs.Research alternatives, inspect existing code, propose designs, and challenge assumptions.
ImplementationSet the task and review its integration with the system.Write and revise code, migrations, and supporting documentation.
VerificationDecide what must be checked and evaluate the actual results.Propose tests, run permitted checks, inspect failures, and identify gaps.
CorrectionDetermine whether the diagnosis explains the failure and approve the repair.Reproduce a bounded failure, implement a repair, and rerun relevant checks.
ReleaseOwn the decision to expose the change to users.Prepare release evidence and carry out authorized steps.

Questions for design and review

  • Probe assumptions: “What assumptions are you making here?” “What could go wrong with this approach?” Follow the answer into the design and its failure tests.
  • Challenge the obvious approach: “What are three different approaches to this problem?” “What’s the unconventional solution you’d hesitate to suggest?” Use these when the choice is open. If the constraints determine the answer, implement it without manufacturing alternatives.
  • Compare tradeoffs: “Present the top three options with pros and cons for each.” “Which option optimizes for maintainability vs speed vs simplicity?” Require the comparison to refer to this system.
  • Learn from other work: “How have others solved this problem?” “Are there patterns from adjacent domains that apply?” Follow the answer to primary documentation or code and inspect whether the approach fits.
  • Improve the collaboration: “What context would help you give a better answer?” “What am I not asking that I should be asking?” Supply the relevant interface, decision record, data shape, or failure report before asking for another implementation.

1. Human architectural authority

A person must own the consequential design decisions and be able to explain their reasons. AI can contribute analysis throughout that process.

Those decisions include the technology stack, component boundaries, data model, integration patterns, security and authentication model, and performance requirements. The owner also decides which choices are fixed for the current task and which remain open to investigation. An exploratory implementation can inform a decision; it should not silently become the architecture because it was the first code generated.

I watched a team apply this to a recommendation engine. The engineer chose PostgreSQL for transactional data and Redis for the real-time cache, separate read and write paths with different scaling requirements, batch processing for model updates, streaming for real-time serving, and specific service communication protocols.

AI then helped implement the components within that design. The result was a coherent system that multiple engineers could understand and extend, built 50% faster than the team’s traditional approach.

Project records carry architectural decisions across conversations. The human owner keeps the design coherent as requirements change, resolves conflicting information, and checks that implementation follows the accepted decisions. That continuity lets several engineers work on the same system without accumulating incompatible patterns.

For consequential choices, I want a short record of the problem, constraints, chosen approach, alternatives considered, and consequences. Michael Nygard's architecture decision record proposal gives this practice a useful form. An ADR is an architecture decision record. Its value is the reason for a decision, including when that reason may no longer hold.

2. Systematic quality standards

Apply the same quality standards to AI-assisted code as to other code serving the same users: correctness, security, performance, maintainability, and documentation. AI gives engineers the capacity to pursue those standards more systematically.

An engineer specifies the failure scenarios that matter: authentication failures, throttling, concurrent access, invalid data, interrupted work, and recovery. AI can help turn that strategy into candidate tests and search for scenarios the engineer missed. The engineer then checks the tests' setup and assertions, including whether a test fails for the defect it claims to detect.

Inspect the tests as carefully as the implementation. A test can execute a line without checking its result, and statement coverage can miss an untested branch. Check that the suite reaches the important failures and makes assertions that would detect a broken implementation. Google’s code review guidance makes that test-validity question explicit.

One engineering director told me: “Our test quality improved dramatically when we shifted from ‘AI writes some tests’ to ‘engineers design testing strategy, AI implements it comprehensively.’ We find bugs in code review now instead of production.”

Making the testing strategy explicit gives the whole team a quality standard it can inspect, challenge, and use. New engineers inherit a working practice. Testing becomes part of how the team builds software, reducing its dependence on each individual remembering every failure case.

Use AI to investigate potential vulnerabilities, optimize performance against the required workload, and keep documentation aligned with code changes. Engineers review the security analysis, compare performance measurements, and check the documentation against the implementation. Humans design the quality strategy; AI helps implement it systematically.

3. Active system understanding

The engineer responsible for a change should understand how it fits into the system, the assumptions it relies on, and how to investigate a failure.

Systems nobody understands are the most dangerous failure mode of this practice. When complex code accumulates faster than the team can understand it, each later change becomes harder to assess and maintain. Six months later, nobody can modify it safely; a year later, the team is facing a rewrite. Active understanding prevents that technical bankruptcy.

A senior engineer on one of our teams described their approach: “When AI generates a solution, I always ask myself: Could I debug this at 2 AM if it fails in production? If not, either I need to understand it better, or it needs to be simpler.”

Can you follow the data through the changed code? Explain the algorithm and its cost? Identify the access-control boundary? Describe what happens when a dependency times out or returns unexpected data? Name the components that will be affected if the interface changes?

Reading and testing support different parts of the answer. A passing test establishes behavior under its conditions; reading helps expose an assumption the tests never exercised. An explanation from AI can help you navigate the code, but it still needs to match the implementation.

When an implementation is difficult to understand, request a clearer explanation, inspect the relevant dependencies, or simplify the code. Prefer a standard pattern when it makes the behavior easier to reason about without compromising the requirement. The depth of review should follow the risk, including interactions that make an otherwise routine change consequential.

A teammate should not need the original AI conversation to understand why an unusual design exists. Preserve that reasoning with the code or its decision record.

4. A self-improving system

Synthesis engineering treats both the project and the practice as evolving systems. The team improves its accumulated context, reusable skills, instructions, and shared craft as it learns from the work.

Project context. Keep decisions, constraints, rejected approaches, and current status in files the project owns. Instructions may live in CLAUDE.md or AGENTS.md; project records may include CONTEXT.md, REFERENCE.md, and session archives. That memory can survive conversations, tool changes, and changes in the team.

One team I worked with records architectural decisions in ADRs. When starting a feature, its engineers ask the AI to read the relevant records. That gives the tool reasons it may not be able to infer from the code. The resulting implementation still needs review against those decisions.

Documentation update prepared October 1, 2026: Loading rules differ by tool. Codex assembles an instruction chain when a run starts. Claude Code loads ancestor instructions at launch and nested instructions as it reaches their directories; direct AGENTS.md support depends on version, settings, and which other instruction files are present. Inspect the context loaded by the tool doing the work.

Reusable skills. A useful procedure can become a maintained prompt or skill with inputs, steps, references, and a way to check the result. Another team maintains prompts for database patterns, API conventions, testing, and deployment. A separate prompt for starting a service covers its template, communication patterns, and observability requirements.

Keep these resources versioned and review changes. Skills documentation update prepared October 1, 2026: OpenAI and Claude Code load a skill’s full instructions when it is selected for use. A shared format makes a procedure easier to distribute; check discovery, permissions, and required tools in each environment.

Instructions. Treat a repeated failure as a defect in the working system. Check whether the requirement was clear, loaded, and consistent with the other instructions. Then inspect the tools, permissions, dependencies, and model behavior that affected the result.

Repair the part that failed. Clarify an instruction gap, use a formatter for formatting rules, and write an executable check for an invariant when possible. Exercise the failing case again so the next session benefits from the repair.

Practice. Improve at four scales: the current project, the team’s shared playbook, the practitioner’s craft, and the discipline as a whole. A prompt that took repeated corrections may need a clearer task, a different tool, better source material, or a different division of work. Encode the lesson so colleagues and later projects can use it.

A team I worked with tracked its progress informally. Its first AI-assisted feature took about 80% as long as its traditional approach, its fifth 50%, and its tenth 30%. The context it accumulated made each subsequent feature faster to build correctly. I describe that progression in the context-building account.

That is the compounding advantage of improving the practice along with the project. Capture useful decisions and procedures so the next feature starts with what the team has learned.

5. Transferable knowledge

Code produced through synthesis coding must be comprehensible, maintainable, and extensible by engineers who were not present when it was generated. Transfer learning in machine learning applies knowledge from one problem to related problems. Here the analogy is to people: the understanding from one engineer’s AI-assisted work should transfer to the next person who touches that code.

Preserve three things: decisions and their reasons, shared conventions and procedures, and code written for its next reader. A clever one-liner that hides the business rule may cost more in review and maintenance than a readable sequence of statements.

Make the handover test practical. Give a teammate the repository and the normal project records. Ask them to explain the affected behavior, run the relevant checks, and make or plan a bounded change. Their questions reveal missing context. If they cannot locate the interface contract or understand a critical assumption, fix the handover material. If the feature depends on knowledge only its original engineer holds, it is not done to this standard, even if the tests pass and the code is deployed.

When changing tools, check that the new tool finds the project records and can perform the workflow they describe. The team keeps ownership of the knowledge across that change.

How the five pillars reinforce each other

The pillars form a loop. Neglect one and the others suffer: a sound architecture needs engineers who understand it, and understanding depends on work the team can inspect, explain, and carry forward.

Human architectural authority becomes ceremonial when a person announces decisions they cannot explain. Active understanding gives that authority substance: the engineer can defend a choice under pressure and recognize when a changed requirement invalidates it.

Quality standards keep the system legible. Sloppy, undocumented, or untested code makes understanding harder even for its author. Raising the quality of the code is a better response than asking engineers to memorize an incomprehensible system.

Quality also depends on transferable knowledge. A standard held only in one senior engineer’s head is difficult for a teammate to apply or challenge. Put the standard and the reasons for it in records the project owns, so another person or a future version of the team can assess the work.

Transfer lets improvements travel. A lesson from one project can become a tested procedure or reusable skill in the next. Writing down the reasoning gives other engineers and tools something they can inspect and adapt, rather than leaving the benefit confined to one person’s experience.

Those lessons strengthen architectural judgment. A painful production incident becomes a design constraint or check the next project can start with. Each turn of this loop improves the team’s ability to build software it understands and can teach others to maintain.

Consider adding a background export job to a reporting service.

The design owner decides who may request an export, what records it may contain, and how long generated files should remain available. The quality strategy specifies cases such as revoked access, a retry after partial completion, and an expired download. Understanding the implementation requires following the job from request through storage and retrieval.

A second engineer reviews that chain. If the review exposes an undocumented assumption about retries, the team records the decision and adds a check for it. The next export feature can use that knowledge, after confirming that the assumption still applies.

The export work has improved the design, the tests, the team’s understanding, and the material a colleague will use for the next feature. The five pillars reinforce one another through ordinary engineering work.

A development cycle with visible results

For a new feature, I recommend planning around four ranges: 15–30% for architecture and acceptance conditions, 40–50% for implementation and inspection, 20–30% for verification, and 10–15% for integration and learning. These are starting allocations to adapt to the work. A feature extending a familiar design needs a different balance from a new service.

For example, allocate 20% to design, 45% to implementation, 25% to verification, and 10% to integration and learning: 100% in total. Choose within the ranges to fit the work, and revisit the plan when implementation or testing exposes a new constraint.

Establish the design and acceptance conditions

Define the relevant data model, interface contracts, authentication and authorization requirements, integration boundaries, performance expectations, and failure behavior. Record consequential choices in an ADR or comparable design note. Identify the tests and reviews needed to accept the result.

For an existing feature, the task may be to confirm that the current design applies. A new service may require substantial investigation before its interfaces and failure behavior are ready to specify.

Implement and inspect

Give the AI a bounded task with the relevant records. A request such as “Implement authentication following the security model in ADR-005” should include the interface and required failure cases. Referencing a document is useful only if the tool can read it and the implementation is checked against it.

Review the code in increments that you can understand. Investigate unexpected dependencies or design changes before building further work on them. Revise the design record if the accepted decision changes.

Verify the behavior

Run the appropriate unit, integration, and end-to-end checks. Review their assertions. Examine security findings for actual reachability, performance results for the workload they measure, and documentation for consistency with the code.

Reviewers need to know the limits of each result. A local mock does not exercise a remote service. A unit test of a helper does not establish that the real route uses it. Preserve failures as well as successful reruns so the repair can be evaluated.

Integrate, release, and retain the lesson

Check the feature with the surrounding system. Follow the team's deployment and authorization process, including monitoring and recovery requirements.

Afterward, retain the decision or procedure that will help with later work. Distinguish what was demonstrated from what remains uncertain. Update a stale record or remove a misleading instruction; adding documentation is not always the right repair.

Scaling from a pilot to organizational practice

Assess the team’s readiness before the pilot. Frequent incidents from poorly tested code, inconsistent architecture, missing documentation, resistance to review, and “ship fast and break things” as unquestioned dogma are red flags. Strengthen those fundamentals as part of preparing the team.

Consistent architecture, strong review habits, active knowledge sharing, a learning mindset, and attention to both speed and sustainability are green lights. AI amplifies the practices already in place.

Choose work whose behavior can be evaluated and whose rollout can be controlled. Assign an owner and reviewer. Set the acceptance conditions before the implementation begins. A five-person team may use two or three experienced engineers across those roles without creating a separate process organization.

Use the pilot to develop practices the whole team can adopt. Expand as completed work demonstrates the quality, understanding, and delivery gains you need:

StageWorkEvidence for the next decision
Weeks 1–2: initial pilotAssign two or three engineers, choose a project away from a critical production path, and record time, quality, and team feedback.Completed changes with review findings, actual checks, rework, tool costs, and unresolved issues recorded.
Weeks 3–4: develop practicesCompare useful and unsuccessful approaches; refine task guidance and share it with the wider team.A procedure another engineer can use, plus examples showing where it fails or requires judgment.
Weeks 5–8: controlled expansionAdd participants or a more complex task when the earlier evidence supports it.Evidence that the review process still works as the participants and work change.
Months 3–6: full team rolloutIncorporate successful practices into ordinary development, train the remaining engineers, and keep refining the approach.Sustained quality, understandable code, useful handovers, and delivery benefits that justify the total cost.

Keep elapsed delivery time, engineering effort, and tool expense separate. Count review and rework in the effort. Record changes in task difficulty and scope. Code volume alone cannot show whether the team is delivering more useful software.

One organization I work with uses a scorecard covering correctness, security, performance, testability, maintainability, and documentation. Those dimensions make a useful starting point, provided each has evidence the team can inspect.

DimensionEvidence to request
CorrectnessResults for the required behavior, including important failures and boundary cases.
SecurityReview of the trust boundaries and reachable risks for this change.
PerformanceMeasurements against the workload and service expectations that matter.
TestabilityTests that can distinguish an intended result from a plausible defect.
MaintainabilityAn engineer other than the author can explain and change the relevant code.
DocumentationInterfaces, operating procedures, and consequential decisions agree with the implementation.

Set the applicable thresholds before evaluating the work. Apply them equally to human-written and AI-assisted code. If it does not meet the quality bar, it does not ship.

Build the practices into the team’s ordinary work: architecture review before implementation, code review that tests the author’s understanding, documentation review alongside code, and regular sessions to share useful techniques and failures. Measure delivery speed and quality together.

When the pilot exposes a problem

Engineers are unsure where AI helps. Compare tasks, not job titles. Standard implementation patterns, test generation, and documentation can be useful places to start, but each output needs review. AI can also help investigate a novel algorithm or a domain-specific rule when an engineer has enough expertise to evaluate the result. Use the pilot to identify where the assistance improves the work and where it adds review burden.

Quality declines. Inspect actual defects and their path through review. A weak specification, ineffective tests, missing integration checks, a tool fault, or an unsuitable implementation can all contribute. Reaffirm the acceptance criteria and repair the failed check. “More review” is too vague unless someone can say what the review missed.

Junior engineers can ship a feature but cannot explain it. Pair them with experienced reviewers. Ask them to trace the implementation, predict an edge case, and explain a test's assertion. Include exercises without AI assistance when those exercises teach a missing skill; use assisted work to practice evaluation as well as implementation.

The team uses inconsistent approaches. Share a worked task, its decision record, and the evidence needed to accept it. Maintain the relevant project instructions and review changes to them. Permit different tools and techniques when they meet the same requirements.

Tool spending rises without a useful delivery gain. Examine the whole task, including setup, failed attempts, review, rework, and handover. Check whether the tool fits the work and whether the task was specified well enough to evaluate. Change or stop an approach whose total cost exceeds its value.

Experienced engineers hesitate to adopt the tool. Ask which specific task or failure they are concerned about. Their concerns may identify an integration, security, or comprehension problem the pilot has not tested. Have them help define the experiment and its acceptance criteria; do not treat adoption itself as proof of success.

The engineering leader owns the pilot decision and its quality criteria. Participating engineers own the designs, reviews, and records. Product leaders help choose valuable work and interpret delivery results without turning one favorable case into a new staffing assumption.

Expand when those people can point to accepted work, explain what improved, and show that another engineer can continue it. Change the approach when the evidence shows a gap. Stop the particular use when its costs or risks remain unacceptable.

The strategic opportunity

Forecast from November 2025. In the next six to twelve months, I expect more sophisticated AI-assisted code review and security analysis, better integration with existing development workflows, organizational standards, and tool ecosystems designed for synthesis engineering. Over one to three years, I expect stronger architectural analysis and recommendations, new architecture patterns for human–AI collaboration, and educational programs and certifications for the practice.

I expect the gap to widen between organizations that develop this capability systematically and those relying on ad hoc AI use. The opportunity is faster feature delivery while maintaining quality, attracting engineers who want to develop the craft, making previously unaffordable features practical, and building organizational knowledge that compounds over time.

That ambition requires investment in people as well as tools. Engineering leaders need to give teams time to learn, document useful practices, and examine failures. Individual engineers can develop the craft on a side project, practice architectural judgment, and bring their lessons back to colleagues. Product and business leaders should fund training and process development, then adjust planning as the team demonstrates what it can deliver. Quality, security, and understanding remain part of the result being bought.

I want synthesis engineering to grow from isolated discoveries into a shared discipline that organizations can teach and improve. The framework gives teams a way to pursue better software faster while strengthening the knowledge needed to maintain it.

Terminology and use

I offer the terms synthesis engineering and synthesis coding, and my accompanying visual identity, under CC0 1.0 Universal to the extent I hold the relevant rights. You can use, adapt, and build on them without permission or an attribution requirement.

I documented these practices because teams needed vocabulary for what they were already doing. Use synthesis engineering for the broader discipline and organizational practices, and synthesis coding for the hands-on craft. If the terms help your organization distinguish an exploratory prototype from systematic production development, use them. If they help you hire, train, or structure your engineering practices, even better.

This article is part of the synthesis engineering series.

Footnotes

  1. The fifth pillar, Transferable Knowledge, was added in April 2026 as the framework evolved from practice. In May 2026, Pillar 4 was reframed from "Iterative Context Building" to the broader "Self-Improving System" (iterative context building is now one of four sub-elements), and the section "How the Pillars Reinforce Each Other" was added to make the loop structure explicit. ↩

Originally published at rajiv.com.