Build a self-improving AI coding practice

The first time you use AI on a new codebase, the results are decent but generic. You spend time explaining your conventions, your architecture, your constraints. By the tenth session, the AI should start with those decisions already in its context: the naming conventions, the established database access patterns, the team's approach to tests. Each session can build on what the team learned in the last.

Expanded May 21, 2026: this pillar originally focused on iterative context building, as the article's URL records. The expansion added skills, instructions and practice to that framework.

In the synthesis coding framework, I call this fourth pillar the self-improving system. Synthesis coding treats both the project and the practice as evolving systems. Context, skills, instructions and practice improve together; a better way of working becomes part of how the next task gets done.

Context: retain the reason

One team I worked with documents every architectural decision in a standard architectural decision record (ADR) format: the decision, the context that led to it, the alternatives considered, and the rationale for the choice. When starting work on a feature, engineers load the relevant ADRs into the AI conversation. They can reuse the team's decisions without reconstructing the reasoning in every prompt.

An ADR explains a choice that may be difficult to recover from code alone. A background-job queue shows where work is handed off for later processing. It may not tell you which latency requirement, failure condition or operational constraint led the team to choose it. That context helps a reviewer decide whether a proposed change still fits.

Michael Nygard's original ADR explanation also preserves consequences and decision status. When a decision changes, keep the earlier record and mark it superseded with a link to its replacement. Otherwise, someone reading an old implementation can lose the reason it exists.

Project files such as CONTEXT.md, REFERENCE.md and session archives can hold the current state, supporting detail and history. Instructions in CLAUDE.md or AGENTS.md can tell an assistant which records matter for a task. Choose a clear home for each fact and link to it; duplicated decisions become difficult to maintain when one copy changes. Keep these records with the project so later conversations, other AI tools and new team members can use the accumulated knowledge.

Recording and loading are separate steps. A custom context filename alone does not establish that a particular session read it. For work that depends on an ADR, explicitly supply or request that record and inspect the proposed implementation against its decision.

Skills: retain the procedure

Another team maintains a collection of prompts that establish their project context. Starting a new feature? There is a context prompt that loads the database patterns, API conventions, testing approach, and deployment requirements in a single message. Starting a new service? A different prompt loads the service template, inter-service communication patterns, and observability standards.

These prompts are maintained like code: version controlled, reviewed when they change, updated when the patterns evolve. Sharing them gives engineers a common starting point and a place to improve the procedure when they discover a missing step. As the collection grows, package the successful procedures into skills the team can reuse.

A recurring procedure can become an agent skill: a package of instructions, supporting material and optional scripts for a defined task. For example, a service-creation skill might identify the template to use, the checks to run and the evidence a reviewer should receive. Its scope should also say when it does not apply.

Before sharing a skill across a team, exercise its relevant workflow in each supported environment. Keep the expected output and failed cases with it. A useful procedure needs enough evidence that another engineer can judge where it applies.

Instructions: repair the demonstrated cause

A repeated mistake deserves diagnosis. The instruction may be missing, ambiguous, contradicted or absent from the session's context. The task may also lack a necessary tool or permission, the code may contain a fault, or the model may fail despite clear guidance. Adding another rule before identifying the cause can leave the original problem intact.

Take the recurring tabs-versus-spaces mistake. State the convention where the client will read it, and configure the formatter to produce the required indentation. If generated changes omit tests, make the expected checks explicit and enforce the checks in the development workflow. Text can explain the requirement; the formatter or test command can check the behavior.

Treat CLAUDE.md and AGENTS.md as living project guidance. Each resolved failure should leave the team with a better way to handle that class of problem. Remove stale or conflicting instructions, move lengthy procedures into appropriate workflow documents or skills, and keep enforceable rules close to the code that must satisfy them. Over time, the guidance and checks encode the team's hard-won understanding of how to make AI productive on this codebase.

Practice: improve at four scales

Improvement happens at four scales: the current project, the team's shared playbook, the practitioner's craft, and the discipline as a whole. A lesson from one feature can improve a shared skill; using that skill on another project can expose an assumption worth revising. Sharing the result gives other practitioners something they can use and improve.

A team I worked with tracked its experience informally. The first feature they built with AI took about 80% as long as their traditional approach. Some of the savings were eaten by the learning curve. The fifth feature took 50% as long. The tenth feature took 30%. The context they had accumulated — documented conventions, established patterns, refined prompts and sharper instructions — made each subsequent feature faster to build correctly.

When tracking your own progress, include review time and rework alongside implementation time. Compare similar tasks and record the changes to the workflow that helped. That gives the team a way to decide which practices to keep developing.

The habit I want teams to break is starting every conversation from scratch. They re-explain their architecture, correct the same convention violations and lose the useful patterns from the previous session. Repeated cold starts leave the team paying for knowledge it has already acquired.

Keep the lessons usable as the project changes. A workaround for one dependency version should carry its conditions. Revise or remove a workflow that keeps failing, and replace stale instructions when the underlying decision changes.

Keep raising the baseline

If a team is 20–30% faster at routine code generation, boilerplate and test scaffolding, I would treat that as an opening gain. Reusing architectural decisions, improving the skills library and closing recurring failure modes can change the cost of whole features. The next improvement may come from a better review procedure or a simpler architecture, as well as from a better prompt.

I want teams to keep compounding those gains for as long as they practice. That takes deliberate investment in all four threads. Every project should leave the team better equipped for the next one.

How current tools load project guidance

Product documentation checked October 1, 2026.

OpenAI documents an instruction chain for Codex assembled at startup from global guidance and project files along the path to the working directory, subject to precedence and a size limit. Anthropic documents ancestor and subdirectory loading for Claude Code, along with version and configuration conditions for reading AGENTS.md. Use these rules to put guidance where your client will find it.

Both Claude Code's skills and OpenAI's skills use the Agent Skills format. Their documentation describes loading skill content when a skill is used; OpenAI distinguishes an initial listing of names and descriptions from the full instructions. Check client extensions, discovery rules, tools and permissions when sharing a skill across environments.

Anthropic's memory documentation also explains that instructions provide context rather than enforced configuration. For a change that depends on particular guidance, check that the session received it and that the resulting code follows it.

A lesson that reaches the code

Example prepared September 27, 2026. The CSV export below has internal ticket records containing ticket_id, status and internal_note. The public file should contain only the first two. A serializer that writes every key in the record exposes the internal note, and a later internal field can create the same problem again.

An explicit public field list makes the intended output visible:

PUBLIC_FIELDS = ("ticket_id", "status")


def export_public(records: Iterable[Mapping[str, object]]) -> str:
    rows = validate_records(records)
    output = io.StringIO(newline="")
    writer = csv.DictWriter(output, fieldnames=PUBLIC_FIELDS, lineterminator="\n")
    writer.writeheader()
    for record in rows:
        writer.writerow({field: record[field] for field in PUBLIC_FIELDS})
    return output.getvalue()

The downloadable example includes the imports, input validation, tests and three documents that retain the lesson. It uses Python 3.12's standard library and synthetic records. The fixture accepts only ticket identifiers such as T-001 and statuses open or closed; it does not implement general text export or an application's access controls.

The decision record explains why the public schema is explicit, records the rejected alternatives and acknowledges the cost of maintaining the field list. Removing only internal_note would leave future internal fields exposed. The workflow note directs a later reviewer to the decision, exporter and checks. The lesson record describes the observed local failure and the boundary of what was tested.

The regression test adds a new internal field and compares the actual CSV with an independent expected result:

    def test_new_internal_field_does_not_expand_contract(self):
        rows = example_records()
        rows[0]["debug_trace"] = "SYNTHETIC-DEBUG"
        self.assertEqual(
            parse(EXPORT(rows)),
            [["ticket_id", "status"], ["T-001", "open"], ["T-002", "closed"]],
        )

The expected header is written in the test rather than imported from PUBLIC_FIELDS. If a later change adds an internal column to the implementation's field list, the expectation should not silently change with it.

From the extracted directory, run:

python3 -m unittest -v
python3 export_report.py check
python3 export_report.py check --implementation all-fields
C07_EXPORT_IMPL=all-fields python3 -m unittest -v

In the September 27, 2026 local execution, the default implementation passed all 18 tests and its output check. The deliberately wrong all-fields version failed the check and three of those same tests: exact public output, omission of the internal note and exclusion of the newly added field. The last two commands therefore exit with status 1. The extracted ZIP produced the same results.

The archive contains ordinary Markdown documents and installs no agent instructions. It gives a reviewer the reason for the rule, a procedure for applying it and tests that distinguish the correct implementation from the faulty one.

For a real task, make the relevant decision and workflow available to the session, check that it read them, then inspect and test the changed export. A passing example does not cover another endpoint, a storage path or a broader set of input values.

Decide what the next session needs

After a productive session, ask: what did the AI get right that we should codify? What did it get wrong that reveals a gap in our documented conventions? A successful solution can become a reusable pattern or skill. A correction can improve an instruction, test or workflow. Both outcomes should make the next session more productive.

For a recurring mistake, also ask what evidence identifies its cause. Then choose where the repair belongs. In the CSV example, the reason belongs in a decision record, the review steps in a workflow, the public field selection in code and the expected output in a test. A project instruction can point to those artifacts without repeating them all.

Record how the next session will encounter the lesson and what check will reveal a regression. Review that path when the project changes. If a decision becomes obsolete, preserve its history while making the replacement clear.

Carry better judgment into the next project

Expanded May 21, 2026.

This is one way to make transferable knowledge usable beyond the engineer who learned it. Conversation and mentoring also transfer knowledge; maintained artifacts let a later person recover details after the original participants have moved on. They support human architectural authority by preserving the evidence and trade-offs behind a decision. The next architect can see why a rule exists and judge whether the conditions still justify it.

The architectural decisions you make on your next project are sharper because the lessons from this one got carried forward. Patterns learned through a painful production incident can become guardrails for the next project. The human at the center keeps getting better at the part that is hardest to automate: judgment.