Principles for AI-native engineering

Last updated July 2026. I expect this to evolve rapidly.

In my current workflow, AI is a tool for leverage. Agents help plan, implement, review, run the application, and maintain recurring workflows. Humans remain responsible for intent, taste, and judgment.

TL;DR

• Keep context versioned beside the code and update it as the system changes.
• Write a checked-in execution plan for every substantial feature or multi-repository change.
• Give each task its own worktree.
• Before human review, have agents review the code, run it locally, capture screenshots, and look for missing tests.
• Use the smartest model available at xhigh reasoning for important implementation and review work.
• Automate repeated work, including the work you would do if you had more time.
• Keep testing and updating your assumptions about what agents can do.

Keep context beside the code

Use Harness Engineering or another approach that treats context as part of the codebase. Keep architecture, product intent, constraints, plans, and operational knowledge versioned beside the code. This gives agents the context to work and gives human reviewers the intended outcome, constraints, decisions, and evidence.

Keep AGENTS.md short. Use it as an index to deeper documents and a home for durable rules. Add a rule when review exposes a recurring problem. Prune stale or redundant guidance.

Use execution plans for substantial work

Any large feature or substantial body of work benefits from a checked-in execution plan. I also use one whenever work spans repositories.

The plan should define:

• The desired outcome, scope, and non-goals
• Relevant architecture and file paths
• Decisions and constraints
• Implementation steps and progress
• Validation, recovery, and cross-repository order

Keep one canonical plan in the primary repository, even if the implementation touches several. Anyone should be able to resume the work from that plan without reconstructing the history from chat.

Update the plan as the work changes.

Use a worktree for every task

Use one Git worktree per change. Each task gets its own branch, filesystem, running application, logs, and test state. Agents can work without interfering with one another, and a failed experiment is easy to abandon.

While one agent implements a feature, others can investigate bugs, review a pull request, update documentation, or try a refactor.

Make agents review their own work

The smartest model should write important code. It should also be the first reviewer.

Before a human reviews a pull request, ask the agent to:

1. Review its complete diff against the execution plan, architecture, and requirements.
2. Fix anything it finds.
3. Run the full test and lint commands defined in AGENTS.md.
4. Smoke test the running application locally.
5. Capture screenshots when the change is visible in the UI.
6. Review the final diff again for bugs, missed requirements, and unnecessary complexity.

Use additional agent review passes for substantial changes. Put strict, current rules in AGENTS.md: architectural boundaries, security requirements, expected tests, file-size limits, and other invariants. Add recurring findings and prune rules that stop being useful.

Run the application

Tests alone do not prove the change works. Agents should boot the application inside the worktree and exercise the affected path. Automate local smoke tests wherever possible.

For UI work, capture screenshots of the live result. They make review faster and catch missing states, broken layouts, stale data, incorrect copy, and interactions that never complete.

At the end, ask one more question:

Are there any tests missing that would give us more confidence in these changes?

Then add the simple, high-value tests it finds.

Use the smartest model and let it think

I generally use the smartest model available at xhigh reasoning for implementation and review. The wait is usually worth it because there is less rework.

While it thinks, start another task, review completed work, talk to a customer, or improve the harness.

Automate the work you would do if you had time

Automate repeated manual work and valuable work that is easy to skip when nobody has time.

I use Codex scheduled tasks to run three workflows automatically, each in its own daily Slack thread:

1. Pull request status: Group PRs into approved, changes requested, needs review, and draft. Summarize risk and flag anything that needs attention.
2. Sentry investigation: Investigate recent errors to find the root cause. Open a fix or record why an error can be ignored.
3. Feedback analysis: Summarize customer sentiment, pull out likely bugs, investigate their root causes, and fix them.

Other scheduled tasks keep internal microsites, API documentation, changelogs, and other references current.

Constantly update your priors

Every day or week, give an agent a real task you think it probably cannot do—something with a low chance of success. The goal is to learn where its current boundary actually is and update your priors.

It might drive a complicated UI flow, coordinate a change across repositories, investigate production telemetry, refactor a large subsystem, or maintain an operational workflow.

When it succeeds, update your workflow. When it fails, find out whether it lacked context, a tool, access to the running application, a validation signal, or a clear definition of done. Update the harness and try again.

AI-native engineering is a new way to do engineering work. Done well, it helps us deliver value to customers faster, with fewer bugs.