Field notes — the blog

Notes from inside the system.

Specific write-ups on decisions that moved the needle: architecture trade-offs, delivery pipelines, and leading engineers who are better than you at their part of it.

              {{ totalPosts }} notes
              {{ totalMinutes }} min total
              Monthly
            

/

                Latest
                {{ featured.date }}
                {{ featured.cat }}
                {{ featured.read }}
              

{{ featured.title }}

{{ featured.excerpt }}

Read the note →

// before → after
{{ row.text }}

{{ listHeading }}

{{ resultCount }}

                {{ post.cat }}
                {{ post.date }}
              

{{ post.title }}

{{ post.excerpt }}

{{ post.read }}

Nothing matches that.

Try a different term, or clear the filters.

The architect's dispatch

One note a month. Nothing else.

A single deep write-up on a system I worked on: the trade-off, the numbers, what I'd do differently.

            {{ article.cat }}
            {{ article.date }}
            {{ article.read }}
          

{{ article.title }}

{{ article.excerpt }}

{{ part.text }}{{ part.text }}{{ part.text }}

{{ b.alt }} — {{ b.caption }}

{{ b.label }}

{{ h.text }}

{{ cell.text }}

{{ b.label }}

{{ link.label }} {{ link.note }} {{ link.host }}

{{ b.caption }}

{{ b.text }}

{{ b.text }}

{{ b.label }}

{{ line.text }}

{{ item.no }}

{{ part.text }}

{{ part.text }}

{{ part.text }}

Takeaways

▖ {{ t }}

Tags

{{ tag }}

← Newer

{{ prevPost.title }}

Older →

{{ nextPost.title }}

Related notes

{{ post.cat }}

{{ post.title }}

{{ post.read }}

Context is the job now

AI · Aug 2026 · 7 min read

The useful work happens before the question. Three minutes of assembling context is the difference between a suggestion I merge and a suggestion I argue with.

The most valuable thing I do with an AI assistant happens before I ask it anything. I spend two or three minutes assembling context, and that is reliably the difference between an answer I merge and an answer I spend twenty minutes arguing with.

This is not a prompting trick. It is the same discipline that makes a design document useful, applied under time pressure to a smaller decision. The tool just made the cost of skipping it immediate and visible.

The four things I supply before the question

The constraint I am actually under: the deadline, the team size, the thing I am not permitted to change.
The shape of the code around it — one representative file, not the whole module.
What I have already ruled out, and why. This alone kills most of the generic answers.
The failure I am trying to prevent, stated as a scenario rather than as a quality.

That last one does more work than the other three combined. Asking for code that is resilient produces a lecture about resilience. Telling it that this consumer will see the same message twice when the broker redelivers after a partition produces an idempotency key and a unique constraint.

A vague question gets a confident, average answer. The averageness is the tell.

Context belongs in the repo, not in your chat history

For a while I was retyping the same six facts into every session. Now they live in a file next to the code, and every session — mine or anyone else's — starts from the same footing. It reads like the onboarding note we should have written for humans years ago, which is not a coincidence.

# what this codebase assumes
stack:      Laravel 11, MySQL 8, RabbitMQ
we do:      repositories, form requests, feature tests over unit
we do not:  facades in domain code, raw SQL outside repositories
deploys:    immutable SHA tags, migrations gated before rollout

open risk:  legacy billing module has no test coverage
            treat every change there as unverified

The file has a second effect I did not plan for. Writing down what we do not do forced three conventions out of tribal memory and into an argument, and two of them did not survive the argument. That was worth the afternoon on its own.

What actually changed in my day

The headline number is unglamorous: on non-trivial changes, roughly one in four first attempts used to be usable without rework. With the context assembled up front it is comfortably better than one in two. The rest of the gain is that the failures fail obviously instead of plausibly.

The skill this rewards is not prompt engineering. It is the ability to state a problem precisely, including the parts you were hoping to leave implicit — which is the same skill that separates an architecture document people can act on from one they nod at. The tool did not create that skill. It just started paying it out weekly instead of quarterly.

Takeaways

State the failure you are preventing as a scenario, not as an adjective.
Put your conventions in a file beside the code so every session starts from the same footing.
The scarce skill is precise problem statement — the same one good design docs have always required.

All notes · Shehzad Aslam