The truth about working with LLMs

Ask an LLM the same question several times and you may get several different answers. One response might be correct, another subtly wrong, and a third unusable. That variation is a normal part of sampling from a language model.

This might be okay when you are getting started. But at some point , you must start asking the hard questions. How much can you trust your model? Will your model actually get to an answer? Can you reliably run the agent automation and expect it to the right thing?

All these questions imply the need of a mental model to check how good is your model/agent performace. This bring us to pass@k and passˆk scores.

In its simplest form, for an agent that repeats a task k times, pass@k asks: Did at least one of the k attempts succeed?
pass^k asks: Did every one of the k attempts succeed?

At k = 1, they are the same measurement. As k grows, they reveal different properties.

• pass@k measures capability. Can repeated sampling uncover a correct answer?

• pass^k measures reliability. Can the model produce a correct answer consistently?
  

🚨 Super important point 🚨

Pass@K and PassˆK must NOT be the only metrics you use for evals.
These are only introductory heuristics.

Lets take an example.

Lets say you gave a coding model some problem to solve.
The first answer you got fails the tests. The second one does not compile. The third one handles the happy path but forgets that empty arrays exist. The fourth answer works.

Will you say that the model successfully completed the task?
If you are exploring what the model can do, the answer is yes. It found a valid solution. However if this model is running an unattended production workflow, the answer is a nervous no. Three out of four runs failed is not a production friendly metric. 🥵

Pass metrcis answer these two differnt questions. In our case of 4 answers,

pass@4 records the one working answer and says the model demonstrated the capability.
pass^4 records the three failures and says the model was not reliable across all four attempts.

pass@k measures the probability that at least one of k attempts is correct.
For k = 1 (pass@1), the model gets one attempt. Either it works or it does not.
For k = 10 (pass@10), the model gets ten attempts. Nine can fail spectacularly. If one passes, the task counts as a success.

This may sounf very simple but is quite useful. It tells you whether the model has the solution somewhere inside its distribution. If you have tests, a verifier, a human reviewer, or another system that can select the good answer, then generating several candidates is a legitimate way to get output.

It is also why pass@k rises as k grows. More attempts create more opportunities to get lucky. A models chance of getting an answer right once across 1000 attempts is obviously greater than 10 attempts.

Mathematically, it is easy to express this score.
Assume one attempt has probability p of succeeding and each attempt is independent.
The chance that any given attempt fails is (1 - p)
The chance that all k attempts fail is (1 - p)^k, so
The chance that at least 1 attempt passed becomes 1 - (1 - p)^k

pass@k = 1 - (1 - p)^k  

If a model succeeds 70% of the time:

pass@1 = 70%  
pass@3 = 1 - (1 - 0.70)^3 = 97.3%  

That looks excellent. Give the model three attempts and it will produce at least one correct answer 97.3% of the time.

⚠️ Someone still has to identify which answer is correct.

pass@k quietly assumes there is a selection mechanism after generation. A test suite can do that for code. A symbolic checker can do it for maths. A human can do it for a draft. Without a reliable judge, ten answers may just give you ten confidently written things to inspect.

Pass^k

pass^k asks the opposite question: what is the probability that all k attempts are correct?

Under the same independent-attempt assumption:

pass^k = p^k  

For the same model with a 70% single-attempt success rate:

pass^1 = 70%  
pass^3 = 0.70^3 = 34.3%  

Same model. Same task. Same three attempts.

• pass@3 says 97.3%

• pass^3 says 34.3%

That is not a rounding error. That is a completely different story.

pass@3 tells us the model is highly capable when retries and selection are available.
pass^3 tells us that only about one-third of three-run groups are flawless. If every run can send
an email, modify a database, approve a refund, or merge code, that distinction matters a lot.

Correlation between the two metrics

For an imperfect model, increasing k makes the metrics separate:

For a model with a 70% single-attempt success rate, the separation looks like this:

This creates a fun benchmark trick.

If a model has a 20% chance of solving a difficult problem in one attempt, its pass@1 is only 20%. But its theoretical pass@20 is about 98.8%.

The model obvoisly did not suddenly become five times smarter. Search, retries, and verification are real system components. The mistake is presenting pass@20 as if it describes the experience of a user who asks once and accepts the first answer.

But how do I already know the success rate?

The previous formulas assume we already know the model’s true success probability p. In an evaluation, we do not know it. We generate samples and estimate it.

Suppose we setup a benchmark that generates:

• n total answers for one problem

• out of that c are correct answers

• we want to evaluate groups of k answers

The standard estimator introduced with HumanEval and used by its
reference implementation for pass@k is:

pass@k = 1 - C(n - c, k) / C(n, k)  

C(a, b) means “the number of ways to choose b items from a items.”

The fraction calculates how many groups of k contain only failures. Subtracting it from 1 gives the fraction containing at least one success.

The matching estimator for pass^k is:

pass^k = C(c, k) / C(n, k)  

Here we count only groups where all k selected answers come from the correct answers.

If you are like me and have trouble parsing permutations and combinations, the below example should clarify the maths.
For example, imagine we generated 10 answers and 7 out of 10 passed:

n = 10  
c = 7  
k = 3  
  
pass@3 = 1 - C(3, 3) / C(10, 3)  
       = 119 / 120  
       = 99.2%  
  
pass^3 = C(7, 3) / C(10, 3)  
       = 35 / 120  
       = 29.2%  

The numbers differ slightly from the earlier 97.3% and 34.3% because this calculation operates on the ten samples we actually observed, without replacement. The earlier calculation assumed an underlying 70% success probability and independent attempts.

Pass@k may feel inflated but is quite useful

It is tempting to look at the gap and declare pass@k a misleading metric.

However, pass@k is excellent at measuring coverage:

• Can the model solve this problem at all?

• Does sampling reveal atleast one correct reasoning path?

• If I have a verifier-backed system, can I find a good candidate?

• Does the model produce diverse solutions rather than repeating one mistake?

For a coding assistant, this can match reality. Generate several implementations, run tests, and show the developer the one that passes. The retries are then part of the product.

“The model gets 95% on pass@10” does not mean “the model is correct 95% of the time.” It means that, under that benchmark’s prompt, sampling settings, tests, and candidate count, at least one of ten generated answers passed for 95% of tasks.

That is valuable information.

pass^k becomes important as we move from augmentation to automation. This distinction also appears in recent agent reliability research: We as humans are okay with some inconsistency in augmentation tools. However autonomous systems turn unreliable output directly into unreliable action.

With augmentation, a human remains in the loop:

• A developer reviews generated code

• An analyst checks a generated query

• A writer edits a generated draft

• An operator approves the proposed action

One bad attempt is inconvenient. The humans are the safeguard.

With automation, the output becomes the action:

• The agent changes production configuration

• The workflow sends messages to customers

• The system updates financial records

• The bot closes incidents or deletes resources

Now one bad attempt can bring down production systems.

There is also a componding problem. An agent that succeeds nine times out of ten may sound production-ready. But when we run it through a 20-step workflow where every step must succeed, and the probability of a flawless run is:

0.9^20 = 12.2%  

This is why long agent workflows feel more fragile than their individual demos. Small failure rates compound.

What should you report?

There is no single perfect number. Report the metric that matches how the system will be used.

Report pass@1

This is the clean baseline. What happens when the user asks once and accepts one answer?

Report pass@k when retries are expected and part of the system

Use it when your actual system generates k candidates and has a credible way to select one:

• Tests

• A formal verifier

• A deterministic constraint checker

• A human reviewer

• A separately evaluated reranker

Do not report pass@100 for a product that only generates one answer.

Report pass^k when consistency matters

Use it when repeated runs should remain correct, or when a sequence contains several opportunities for failure. For examples, agent workflow chaining, regression testing, safety-sensitive actions, and workflows without a human backstop.

Why not report both!

The gap between the metrics is itself useful.
At k = 1, they are the same measurement. As k grows, they reveal different properties.

• High pass@k, low pass^k: capable but inconsistent

• Low pass@k, low pass^k: the task is beyond the model

• High pass@k, high pass^k: capable and dependable

That tells a much richer story than any one of them.

A few traps before you calculate either

Attempts are not always independent

Models can repeat the same reasoning pattern, especially at low temperature. Agent runs may share the same retrieved documents, tools, cached state, or environmental failure. The simple p formulas are intuition, not a guarantee that real runs behave independently.

Correctness is only as good as the judge

A code sample “passes” because it passed the available tests. Missing tests can turn a wrong answer into a benchmark success. A non reliable evaluator can mess up your evalutions.

Sampling settings are part of the metric

Temperature, prompts, tool access, token limits, and model versions all change the result. Comparing two pass@k numbers with different evaluation setups is not a clean model comparison.

Reliability has more than one dimension

pass^k captures repeated correctness. It does not measure calibration, safety, robustness to prompt changes, recovery from tool failures, or behavior under a changing environment.

Key takeaways

1. pass@k measures capability - at least one of k attempts must succeed.

2. pass^k measures consistency - all k attempts must succeed.

3. More retries make pass@k rise - capability becomes easier to discover.

4. More required successes make pass^k fall - unreliability compounds.

5. Retries need a judge - multiple candidates help only if you can identify the good one.

6. Automation raises the bar - a human can absorb inconsistency; an unattended workflow cannot.

7. Report both when trust matters - one tells you what the model can do, the other how often you can depend on it.

Conclusions.

If you are building a demo, exploring the edge of model capability, or using a strong verifier, pass@k is exactly the question you want to ask.

If you are giving an agent tools, permissions, and the ability to act without approval, ask the other question too:

It succeeded once. Will it succeed again?

References

• Evaluating Large Language Models Trained on Code - the HumanEval paper that introduced the pass@k estimator.

• OpenAI HumanEval pass@k implementation - the reference code for the unbiased estimator used above.

• Towards a Science of AI Agent Reliability - recent work on why consistency matters as models move from augmentation to automation.

  Originally posted on Shaswat Rungta | Personal Blog

  Hope this was a useful read for you! Would you like to subscribe to keep in touch? 🙏🏻 🫶🏻 🥰

Chapter 1: A brief history of world knowledge

The need for communication and passing on knowledge is one of the most essential human traits. We have evolved from sign languages and cave paintings to using leaves and stones for the written word. We sped through the whole paper era (in a short couple of centuries ) and landed in the information age where everything went digital.

In the beginning, computers had a small vocabulary. We were so busy getting the word out about the internet, we had little time to consider if the word was understood. As the internet grew from a mostly English-speaking network into a place for the whole world, text had to evolve with it. Every step made online communication richer, but it also quietly broke another assumption programmers had made about what a “character” really is.

🧐 Are emojis modern day cave paintings?? 😯

ASCII (The Simple Days)

A = 65
B = 66
...
Z = 90

128 characters total. All English letters, numbers, basic punctuation. 7 bits. Life was simple.

🌎 Then the internet happened.

Unicode (The Complicated Now)

A = U+0041 (Latin Capital Letter A)
Á = U+00C1 (Latin Capital Letter A with Acute)
А = U+0410 (Cyrillic Capital Letter A)
Α = U+0391 (Greek Capital Letter Alpha)
𝐀 = U+1D400 (Mathematical Bold Capital A)

140,000+ characters. Multiple ways to represent the same thing. Combining characters. Emoji. Emoji with skin tones. Emoji combined with other emoji.

Unicode went from “character set” to “every written symbol in human history plus emoji”.

Chapter 2: The Many Ways Characters Lie About Their Size

Traditional knowledge tells us that the size of a string should be equal to the number of character you see in it. And traditionally all characters used to take a fixed 1 byte memory. So if i wanted to store a Name of 100 characters, I would allocate 100 length to my database column.
But unfortunately modern unicode breaks these assumption in many ways, most commonly due to the way the size of a character is calculated.

Size Lie #1: UTF-8 Variable Length

Single characters in print can often need more space to store.

'A'.length;        // 1 UTF-16 code unit (1 byte in UTF-8)
'€'.length;        // 1 UTF-16 code unit (3 bytes in UTF-8)
'💩'.length;       // 2 UTF-16 code units (4 bytes in UTF-8)

If you had a 100-byte limit thinking it should store 100 characters, what fits is actually:

• 100 ASCII characters ✅

• 33 Euro signs (3 bytes each)

• 25 emoji (4 bytes each)

Size Lie #2: Combined Characters

Sometime single characters may not be single characters at all. Depending on how you process them they can be of different lengths,

'é'.length;  // Could be 1 or 2!

// Option 1: Single character (NFC - composed)
'é' = U+00E9 (1 character)

// Option 2: Base + combining accent (NFD - decomposed)  
'e' + '́' = U+0065 + U+0301 (2 characters)

The characters look identical. But they’re different in memory. This also leads to an interesting comparison problem.
‘é’ === ‘é’ can sometimes be false! Which means your database indexes them as different values and your lookups fail mysteriously.

Usually most languages have an equivalent of normalise() function for strings. In that case ‘é’.normalize() === ‘é’.normalize() gives a True result.

Size Lie #3: Emoji Combiners

Emojis revolutionised the way humans communicate. However emojis follow an interesting composition pattern.

'👨‍👩‍👧‍👦'.length;  // 11

// Actually:
'👨' + ZWJ + '👩' + ZWJ + '👧' + ZWJ + '👦'
// Man + Zero Width Joiner + Woman + ZWJ + Girl + ZWJ + Boy
// = Family emoji (displays as 1)

Your JavaScript counter reports “This is 11 UTF-16 code units,” while the user sees just 1 emoji. Your validation thinks “That’s fine,” but a byte-limited field can reject it: this sequence is 25 UTF-8 bytes.

Chapter 3: Real-World Horror Stories

All this information is not just theoritical. It happens in production system day-in day-out. Below are some ways in which they can happen trivially.

Story 1: The Name That Broke Authentication

A user named José creates an account. Your system normalizes and stores it as “José” using NFC normalization. When José logs in the next day and types their name, their keyboard or input method produces the NFD normalized version: “José”. Your system tries to look up “José” in the database but finds nothing, because it’s searching for the NFD form against the stored NFC form. The user sees “Who’s José? I don’t know that user.”

NFD - Normalization Form Decomposed. Breaks characters into base character + combining marks. Example: é = e + ´ (separate bytes) NFC - Normalization Form Composed. Combines base character + marks into single precomposed character. Example: é = é (single byte)

Fix: Normalize all input before comparison

function normalizeText(str) {
  return str.normalize('NFC');
}

username === savedUsername  // ❌ Can fail
normalizeText(username) === normalizeText(savedUsername)  // ✅ Works

Story 2: The Email That Traveled Through Time

A User in Japan sends email with kanji characters.
Email server 1 (UTF-8): Passes it along fine
Email server 2 (ISO-8859-1): Can’t handle kanji, converts to ?
Email server 3 (UTF-8): Sees ? and assumes that’s the data
Recipient: Gets email full of ? characters

This is mojibake. Text corrupted by charset mismatches.

The fix: Always specify charset in Content-Type headers

Content-Type: text/html; charset=UTF-8

This is also one of the reasons why old smartphones could not render emojis in SMS and showed a string of ? or black boxed question marks.

Story 3: The Tweet That Was Too Long

On Twitter (I refuse to call it X! ), tweets are limited to 280 characters.

User tweets: “🏴󠁧󠁢󠁥󠁮󠁧󠁿🏴󠁧󠁢󠁳󠁣󠁴󠁿🏴󠁧󠁢󠁷󠁬󠁳󠁿 (3 flag emoji).
Intuition: “This is 3 characters”
Reality: This is 42 code points (14 per flag)

Result: The twitter character counter disagrees with you and shows you are using much more than 3 characters.

Platform reality: X uses its own weighted counting rules, not JavaScript’s built-in string length.

You can read about there actual computation on their developer site.

Grapheme clusters are the user-perceived characters. A single emoji flag (like 🏴󠁧󠁢󠁥󠁮󠁧󠁿) is one grapheme cluster even though it’s 14 code points. A code point is Unicode’s assigned number for a unit of text, such as a letter, emoji component, or invisible joiner.

Story 4: The Database Migration That Deleted Data

When migrating database, your primary focus is that tables should not get dropped, there should be no downtime, the columns should get mapped correctly. However managing migrations of character set has its own set of challengers.

Scenario: Migrating from MySQL with latin1 to utf8mb4

-- Old table
CREATE TABLE users (
  name VARCHAR(100) CHARACTER SET latin1
);

-- New table
CREATE TABLE users (
  name VARCHAR(100) CHARACTER SET utf8mb4
);

The trap:

• latin1: VARCHAR(100) stores up to 100 characters, using up to 100 bytes for the value

• utf8mb4: VARCHAR(100) still stores up to 100 characters, using up to 400 bytes for the value

But MySQL also has row and index-size limits, depending on the storage engine, row format, and indexes.

If you have 200 VARCHAR(100) columns:

• latin1: 200 × 100 = 20,000 bytes ✅

• utf8mb4: 200 × 400 = 80,000 bytes at the theoretical maximum

your migration could hit an engine-specific limit, or your data could get truncated if the migration is not planned carefully. The fix would usually be to reduce VARCHAR sizes or split across tables.

Story 5: The Search That Found Nothing

Since we are talking databses, searching for an existing value is often the most popular use case. Lets take an example.
User searches for: “café”
Database has: “cafe”, “café”, “café” (composed), “café” (decomposed)

Your search:

SELECT * FROM places WHERE name = 'café';

Results: DB would usually return only exact matches and misses variations which in this case you obviously wanted.

The fix: Normalize before storing, normalize before searching

-- PostgreSQL example
SELECT * FROM places WHERE unaccent(name) = unaccent('café');

Story 6: The URL That Broke Routing

Unicode also turns up in places where you assume some default behaviour. One of the common ways sites create persistent readable links is to have text in the URL path. However browsers have been built to handle unicode by default when routing.

User creates profile: https://site.com/users/José.
Browser URL-encodes: https://site.com/users/Jos%C3%A9

Your router:

app.get('/users/:name', (req, res) => {
  const user = getUser(req.params.name);
  // req.params.name is "Jos%C3%A9" or "José" depending on framework
});

Some frameworks would decode automatically but it is always good to check. Anyway, a better way to create permalinks is not to have user input in the URL.

The fix: Always use IDs in URLs, not names

// ❌  Bad
/users/José

// ✅ Good
/users/123

Chapter 4: The Emoji Special Cases

We talk about compositional emojis. However the composition itself has many different variation.

Skin Tone Modifiers

Emojis have additive modifiers. You take a base emoji and add an inflextion on it. This is how you get a hand wave sign in your own skin tone.

'👋'.length;      // 2 (base emoji)
'👋🏻'.length;     // 4 (base emoji + skin tone modifier)

Your emoji picker now shows 5 skin tone options. But in your database each takes different space. So beware of these additions.

Flags

Flags are a fun variation of composition. For example, If you look at the US flag emoji.

'🇺🇸'.length;     // 4

// Actually two "Regional Indicator" characters:
// U+1F1FA (Regional Indicator U) + U+1F1F8 (Regional Indicator S)
// = US flag

Your database may not recognize this as one flag
Your rendering might show “U” “S” instead of 🇺🇸

Gender and Profession Variations

Similar variations arise for gender and profession emojis.

'👨'              // Man
'👨‍⚕️'             // Man + ZWJ + Medical symbol = Male doctor
'👩‍⚕️'             // Woman + ZWJ + Medical symbol = Female doctor
'🧑‍⚕️'             // Person + ZWJ + Medical symbol = Doctor (gender neutral)

Each variation has a different byte count

Chapter 5: The Database Encoding Trap

I have spent years working with databases without caring about caracter sets. In most case, databases come with good defaults, or their onboarding guides give examples of most defensive settings. However it is good to know how they affect storage in the context of what we discussed thus far.

MySQL Character Sets (A History of Mistakes)

latin1 (default for ancient MySQL)

• 1 byte per character

• Only Western European languages

• Can’t store emoji

utf8 (MySQL’s version, not real UTF-8)

• Max 3 bytes per character

• Can store most characters

• Cannot store emoji (emoji need 4 bytes)

utf8mb4 (actual UTF-8)

• Max 4 bytes per character

• Can store emoji

• This is what you want

The trap:

-- Your table uses default charset (latin1)
CREATE TABLE users (name VARCHAR(100));

-- User tries to save emoji
INSERT INTO users (name) VALUES ('Alice 😀');

-- MySQL:
-- ❌ Error: Incorrect string value
-- OR
-- ⚠️ Silently truncates emoji

The fix:

-- Specify utf8mb4 explicitly
CREATE TABLE users (
  name VARCHAR(100) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci
);

-- Or set database default
ALTER DATABASE mydb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

PostgreSQL (Mostly Gets It Right)

PostgreSQL uses UTF-8 by default. Emoji just work. But CHAR(n) is still usually the wrong type for user input:

CREATE TABLE users (name CHAR(10));
INSERT INTO users (name) VALUES ('Hello 👋');

-- This fits, but CHAR pads values with spaces.

The fix: Use VARCHAR(n) when you need a character limit, or TEXT when you do not. Avoid CHAR(n) for variable-length user input.

Chapter 6: The Application Layer Traps

We talked a lot about database level storage till now. However at some point you also have to show the stored text to the users, or atlest process it somehow in your application code. There are many traps there as well.

Trap 1: String Length Validation

// User enters: "Hello 👨‍👩‍👧‍👦"
const input = "Hello 👨‍👩‍👧‍👦";

// Wrong
if (input.length > 20) {
  throw new Error('Too long');
}
// input.length = 17 (11 for emoji + 6 for "Hello ")

// Right
const segmenter = new Intl.Segmenter('en', { granularity: 'grapheme' });
const graphemes = Array.from(segmenter.segment(input));
if (graphemes.length > 20) {
  throw new Error('Too long');
}
// graphemes.length = 7 (1 for emoji + 6 for "Hello ")

The choice of using graphemes or actual char count depends on how you want to impose limits on user input.

Trap 2: Substring Operations

If we are having trouble deterministically finding how long a string is, it falls to reason that splitting it would also be hard.

const text = "Hello 👨‍👩‍👧‍👦 World";

// Wrong
text.substring(0, 10);  // "Hello 👨‍ " (cuts emoji in half!)

The solution usually is to use grapheme-aware libraries or avoid substring with emoji 😜

Trap 3: Regex Matching

Regex match is string processing final boss. If you thought splitting string was hard, matching it against a pattern can be a whole new box of wonders. s

// Match any single character
const regex = /^.$/;

'A'.match(regex);           // ✅ Match
'💩'.match(regex);          // ❌ No match (2 UTF-16 units)
'👨‍👩‍👧‍👦'.match(regex);      // ❌ No match (11 UTF-16 units)

// Better
const regex = /^.$/u;  // Unicode flag
'💩'.match(regex);          // ✅ Match

// But still won't match combined emoji
'👨‍👩‍👧‍👦'.match(regex);      // ❌ Still no match

Chapter 7: The Fixes

Despite all the above, the world continues to communicate in emojis, accented characters, regional languages; So there must be some way all of it continues to work. Here are some tips.

Fix 1: Use UTF-8 Everywhere

Database: utf8mb4.
API responses: Content-Type: application/json; charset=UTF-8.
HTML: <meta charset="UTF-8">
Files: Save as UTF-8.
Environment: Set LANG=en_US.UTF-8.

Fix 2: Normalize User Input

function normalizeInput(str) {
  return str
    .normalize('NFC') // Normalize to composed form
    .trim(); // Remove whitespace
}

Fix 3: Count Graphemes, Not Code Points

function countGraphemes(str) {
  const segmenter = new Intl.Segmenter('en', { granularity: 'grapheme' });
  return Array.from(segmenter.segment(str)).length;
}

Fix 4: Validate Before Storing

function validateText(str, maxGraphemes, maxBytes) {
  const graphemes = countGraphemes(str);
  const bytes = new TextEncoder().encode(str).length;
  
  if (graphemes > maxGraphemes) {
    throw new Error(`Too many characters (max ${maxGraphemes})`);
  }
  
  if (bytes > maxBytes) {
    throw new Error('Text too long in bytes');
  }
}

Fix 5: Use TEXT Columns, Not VARCHAR

-- Instead of guessing VARCHAR size
CREATE TABLE posts (
  content VARCHAR(10000)  -- Might not be enough for emoji-heavy text
);

-- Use TEXT when there is no application-level character limit
CREATE TABLE posts (
  content TEXT
);

In PostgreSQL, TEXT and VARCHAR have the same storage characteristics; VARCHAR(n) adds a character limit.

Fix 6: Test With Emoji

// Add these to your test suite
const testStrings = [
  'Simple ASCII',
  'Café',                    // Accented characters
  'Hello 世界',              // CJK characters
  'مرحبا',                   // RTL text
  'Hello 👋',               // Basic emoji
  '👨‍👩‍👧‍👦',                    // Combined emoji
  '🏴󠁧󠁢󠁥󠁮󠁧󠁿',                        // Flag emoji
  '👋🏻👋🏿',                   // Emoji with skin tones
  'ℌ𝔢𝔩𝔩𝔬',                // Mathematical alphanumeric symbols
];

Key Takeaways

1. Use UTF-8 (utf8mb4 in MySQL) everywhere - No exceptions

2. Normalize text on input - NFC is usually the right choice

3. Count graphemes, not code points - Use Intl.Segmenter

4. Test with emoji - They will break your assumptions

5. Never use CHAR for user input - Use VARCHAR or TEXT

6. Validate both length and byte size - They’re different

7. Normalize before comparing - ‘é’ has multiple representations

8. Don’t use names in URLs - Use IDs instead

Conclusion

Unicode is humanity’s attempt to represent every written symbol in a computer. Emoji are humanity’s attempt to communicate without words. Together, they create a perfect storm of edge cases.

Remember: If your system can’t handle 💩, it’s not ready for production.

📚 Companion post:

Explains why worktrees are useful when people or coding agents work on several branches at once.

Development in an agentic world

Most local development setups assume that only one copy of the application is running. The frontend always uses one port, the API always uses another, and every branch connects to the same local database. That assumption is invisible while you work on one branch at a time.

Git worktrees change the equation. They give each branch a separate directory, but they do not isolate anything the application uses at runtime. Start the app from a second worktree and both copies compete for the same ports. Change one copy to use different ports and its frontend still needs to find the matching API. Even after both copies start, they can write to the same database.

This is more than inconvenient bookkeeping. You can open the frontend from one branch while it silently calls the API from another, or test a data change against records created by a different worktree. Two developers or coding agents can interfere with each other even though their source files are isolated.

What we want is one independently addressable application copy per worktree, with isolated data, without starting another copy of every heavyweight dependency.

This post builds that model with development slots and Caddy. A slot is a name for one running copy of the application and its data boundary. The sample derives that name from the current Git branch, so each worktree naturally gets its own slot. Caddy acts as a shared reverse proxy, giving every slot stable URLs while its frontend and API run on separate high-numbered ports. You can also provide a slot name explicitly.

Each slot gets:

• A stable frontend URL such as http://feature-search.multi-agent-wt.localhost:8088

• A stable API URL such as http://api-feature-search.multi-agent-wt.localhost:8088

• Its own frontend and API ports behind those URLs.

• Its own Cosmos DB database, such as multi-agent-wt-feature-search.

All slots share one Caddy proxy and one Cosmos DB emulator.

🧪 Try the complete sample

Direct Link : https://github.com/srungta/samples/tree/main/MultiAgentWorktrees

The working sample is in MultiAgentWorktrees Github repo. It contains a React frontend, a .NET API, Docker Compose infrastructure, and the slot script used in this post.

You need:

• Docker Desktop or Docker Engine with Compose

• .NET 10 SDK

• Node.js and pnpm

• Bash and curl (macOS, Linux, or WSL for multi-slot mode)

From the sample directory, run:

./start-multislot.sh infra-up
./start-multislot.sh up

The first command starts the shared Cosmos DB emulator and Caddy. The second command:

1. Gets the slot name from your current git branch.

2. Assigns stable frontend and API ports.

3. Chooses a database name for the slot; the API creates it on startup.

4. Starts the API and frontend.

5. Adds both hostnames to Caddy.

On the main branch, it prints:

Slot 'main' is ready.
  Frontend: http://main.multi-agent-wt.localhost:8088
  API:      http://api-main.multi-agent-wt.localhost:8088
  Database: multi-agent-wt-main
  Logs:     /Users/you/.config/multi-agent-wt/slots/main

Open the frontend URL and add a note. That note is stored only in this slot’s database.

If you are not in a git branch, or want a specific name, pass one:

./start-multislot.sh up demo

That is the entire daily startup flow.

🌿 Run a second branch

Create a worktree from your main clone:

git worktree add ../samples-feature-search -b feature/search

Enter that worktree and start its slot:

cd ../samples-feature-search/MultiAgentWorktrees
./start-multislot.sh up

Now both copies run at the same time:

BranchFrontendDatabase
main
- Frontend: http://main.multi-agent-wt.localhost:8088
- Database: multi-agent-wt-main

feature/search
- Frontend: http://feature-search.multi-agent-wt.localhost:8088
- Database: multi-agent-wt-feature-search

Adding a note in one frontend does not make it appear in the other.

🧭 How the pieces fit together

At a high level, Caddy sends each hostname to the matching slot. Each slot has its own frontend, API, and database name, while the proxy and database server are shared.

Here are the request routes in more detail:

There are two kinds of resources:

🏗️ Shared infrastructure, started once:

• Caddy listens on port 8088 and routes requests by hostname.

• The Cosmos DB emulator listens on port 8081 and hosts many databases.

📦 Per-slot processes, started in each worktree:

• One Vite dev server.

• One .NET API process.

• One Cosmos database name.

🔀 What Caddy and a reverse proxy do

A proxy receives a request on behalf of another server. A reverse proxy sits in front of application servers: the browser connects to the proxy, and the proxy chooses which application process should receive the request. The application port stays hidden behind the proxy’s stable address.

In this sample, Caddy is the reverse proxy. Every frontend and API URL reaches Caddy on port 8088. Caddy reads the HTTP Host header, matches it against a route, and forwards the request to the corresponding process running on a high-numbered host port. The response returns through Caddy to the browser.

Caddy only handles routing. The worktree isolates source files, while the slot script starts the processes and chooses a database name.

🌐 Why the local hostnames work

Names ending in .localhost resolve to the loopback address in modern browsers. You do not need to add every slot to /etc/hosts.

Caddy receives all traffic on port 8088. It uses the request hostname to choose an upstream:

http://feature-search.multi-agent-wt.localhost:8088 {
	reverse_proxy host.docker.internal:40123
}

http://api-feature-search.multi-agent-wt.localhost:8088 {
	reverse_proxy host.docker.internal:20123
}

The actual port numbers do not matter to the person using the app. Caddy hides them behind readable, predictable URLs.

The Caddy container reaches host-run processes through host.docker.internal. The Compose file adds a host-gateway mapping for Docker Engine on Linux; Docker Desktop provides the same hostname on macOS and Windows.

The browser calls the frontend hostname to load the UI. The frontend then calls its own API hostname, which also goes through Caddy. Caddy does not forward traffic to Cosmos DB: each API connects directly to the shared emulator.

🔒 Why the data stays isolated

Running one Cosmos emulator per worktree would use unnecessary memory. Instead, every API connects to the same endpoint but uses a different database name:

Cosmos__Endpoint="https://localhost:8081"
Cosmos__Database="multi-agent-wt-feature-search"

.NET maps the double underscore in Cosmos__Database to the configuration key Cosmos:Database.

The sample API uses the current Linux-based Cosmos DB emulator image in HTTPS mode:

cosmos:
  image: mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest
  command: ["--protocol", "https"]
  ports:
    - "8080:8080" # readiness endpoint
    - "8081:8081" # Cosmos endpoint
    - "1234:1234" # Data Explorer

The vNext emulator supports the API for NoSQL in gateway mode, so the .NET client sets it explicitly:

var cosmos = new CosmosClient(endpoint, key, new CosmosClientOptions
{
    ConnectionMode = ConnectionMode.Gateway,
    ServerCertificateCustomValidationCallback = (_, _, _) => true,
});

The certificate bypass is for the local emulator only. Do not use it with a production Cosmos DB account.

🗂️ What the slot script records

Each slot has a small state directory under ~/.config/multi-agent-wt/slots:

~/.config/multi-agent-wt/slots/feature-search/
├── env
├── Caddyfile
├── api.pid
├── api.log
├── frontend.pid
└── frontend.log

The script lowercases the slot name and replaces non-alphanumeric runs with hyphens. It then hashes that sanitized name into a stable numeric offset, adds the offset to base ports 20000 and 40000, and checks known slots and listening ports for a collision before starting anything.

The script injects the matching API URL into the Vite process:

VITE_API_BASE=http://api-feature-search.multi-agent-wt.localhost:8088

Vite listens on all host interfaces so Caddy’s container can reach it:

pnpm exec vite --host 0.0.0.0 --port "$frontend_port" --strictPort

You do not need to copy the full orchestration script from this article. Use the tested start-multislot.sh from the sample.

🚀 What happens when a slot starts

Starting a slot does five things:

1. Pick a name and two free ports for the slot.

2. Start the API and create the slot’s database if needed.

3. Start the frontend and point it to the slot’s API.

4. Tell Caddy which URLs belong to the new slot.

5. Check that the frontend and API work. If they do not, stop the slot and remove its Caddy routes.

Caddy and the Cosmos emulator are already running. A new slot adds only a frontend, an API, a database name, and two Caddy routes.

🛑 Stop and inspect slots

List all known slots:

./start-multislot.sh status

Stop only the current branch’s slot:

./start-multislot.sh down

Stop a named slot:

./start-multislot.sh down feature-search

When no slots remain, stop shared infrastructure:

./start-multislot.sh infra-down

The script refuses to stop shared infrastructure while known slots still exist. Normal shutdown also preserves the Cosmos Docker volume, so your local data survives a restart.

♻️ The pattern to reuse

You can adapt the sample to another project by changing four things:

1. Replace multi-agent-wt.localhost with your local domain.

2. Replace the commands that start the frontend and API.

3. Pass a slot-specific database, schema, or tenant name to your backend.

4. Keep shared services in the infrastructure Compose file and lightweight app processes per slot.

The important idea is not the exact script. It is the separation of concerns:

• Git worktrees isolate files and branches.

• Caddy gives changing processes stable names.

• Per-slot database names isolate data.

• Shared infrastructure keeps the setup light enough to run many copies.

With those boundaries in place, running another branch becomes one command instead of another round of port and configuration bookkeeping.

✅ Prerequisites for adapting this pattern

The orchestration script cannot create isolation if the application has fixed addresses or hidden shared state. Before applying this pattern to another project, make sure it supports the following capabilities.

⚙️ Runtime configuration

The frontend must read its API base URL from configuration rather than embedding it in the source. The backend must do the same for its database endpoint, credentials, and database name. In this sample, the relevant values are:

VITE_API_BASE=http://api-feature-search.multi-agent-wt.localhost:8088
Cosmos__Endpoint=https://localhost:8081
Cosmos__Database=multi-agent-wt-feature-search

The frontend and API must also accept a port at startup. Each slot needs different listening ports, even though Caddy hides those ports from the browser.

🧱 A per-slot data boundary

The shared data service must provide a namespace that can be selected through configuration. That boundary is a Cosmos database in this sample, but it could be a PostgreSQL database or schema, a storage prefix, or a tenant identifier. Every read, write, migration, and background job must use the selected namespace; one hard-coded database or globally shared queue can break slot isolation.

🗄️ Repeatable database creation and migration

A new slot starts with a new database name, so the application needs an initialization path. The sample API uses CreateDatabaseIfNotExistsAsync and CreateContainerIfNotExistsAsync during startup. A larger application might run a separate provisioning or migration command instead.

Whichever approach you use, it should:

• Accept the slot-specific database or schema name as input.

• Be idempotent, so restarting a slot is safe.

• Apply all schema migrations required by the branch being started.

• Fail before the slot is advertised as ready if provisioning does not succeed.

Be deliberate about incompatible migrations. Slots isolate database names, but they still share the same database server or emulator version.

🔌 Reachable services and allowed origins

Caddy must be able to reach the frontend and API processes. In the sample they bind to 0.0.0.0 because Caddy runs in Docker and connects through host.docker.internal. If Caddy runs directly on the host, binding to loopback may be enough.

The API must also allow requests from each slot’s frontend origin. The sample allows every CORS origin for local development. A real project should generate an allowlist or safely validate the local slot domain instead of carrying that permissive policy into production.

🩺 Readiness and lifecycle commands

The slot manager needs a lightweight API health endpoint and a frontend URL it can probe before it reports success. It also needs reliable commands for starting and stopping both processes, plus a place to record their PIDs, logs, assigned ports, and proxy routes.

Finally, decide what down means for data. This sample stops the processes and removes the Caddy route but preserves the slot’s Cosmos database. Projects that need disposable slots should add an explicit database cleanup command rather than deleting data as a side effect of ordinary shutdown.

🏁 Conclusion

Remember the last time you switched branches mid-feature, forgot to change a port, and spent twenty minutes wondering why your “new” UI was showing old data? That was not a skill issue. That was an invisible assumption biting you. Fix it for yourslef and your agents today 😎

Use Git worktrees to run agents in parallel without sharing working files or duplicating history.

The problem agents create

Most development workflows assume that one developer is doing one thing at a time: check out a branch, make changes, run tests, commit, and move on. In that model, one working directory is plenty.

AI coding agents break that assumption. The whole point of an agent is that you can run many at once: one fixing a bug, one writing tests, one refactoring a module, one exploring a risky idea you’re not sure about. Suddenly, the working directory becomes a shared resource, and the obvious workarounds start to break down:

• Sharing one checkout — agents overwrite each other’s uncommitted files. Agent A’s half-finished refactor corrupts Agent B’s test run. git checkout by one agent yanks the ground out from under another.

• Full git clone per agent — every clone re-downloads the entire history. For a large repo that can mean gigabytes and minutes per agent, plus multiple copies of .git consuming disk.

• Stash juggling — git stash to swap contexts is fragile, serial, and impossible to parallelize.

What agents actually need is isolation without duplication: many independent working directories that don’t interfere, but that share one history so branches, commits, and fetches are instant and cheap.

Branches alone do not solve this. A branch identifies an independent line of history, but creating one does not create another working directory. For that, each agent needs a worktree of its own.

That primitive already ships with Git. It is called a worktree.

What a worktree actually is

git worktree lets one repository have multiple working directories checked out at the same time, each on its own branch, all backed by a single shared .git object store.

# In your main clone (on `main`):
git worktree add -b feature/search ../repo-agent-a main
git worktree add -b bugfix/crash ../repo-agent-b main
git worktree add -b chore/deps ../repo-agent-c main

You now have four directories on disk:

~/code/repo              (main)              ← the primary worktree
~/code/repo-agent-a      (feature/search)
~/code/repo-agent-b      (bugfix/crash)
~/code/repo-agent-c      (chore/deps)

Each directory has its own working files, index, and HEAD. But there is only one copy of the repository’s history: the objects, refs, and packfiles are shared through the repository’s common Git directory. Creating a worktree does not re-download or duplicate that history, so it is typically fast even for a large repository.

The result is the useful combination: shared history, independent files. That is exactly the isolation parallel agents need.

Why worktrees fit agentic development so well

1. True parallelism with no cross-talk

Each agent operates in its own directory. Agent A can run a failing build, rewrite ten files, and run tests — while Agent B does something completely different — and neither sees the other’s uncommitted work. No lockstep, no “please wait, someone else is building.”

2. Cheap to create and destroy

Because history is shared, spinning up a worktree is near-instant and costs only the checked-out files, not another copy of .git. That makes worktrees disposable: create one per task, throw it away when the task merges. Perfect for an orchestrator that launches and reaps agents on demand.

git worktree add ../repo-task-1234 -b agent/task-1234   # create + new branch in one step
# ... agent works, commits, opens a PR ...
git worktree remove ../repo-task-1234                    # reap when done

3. One branch per agent, enforced by construction

Git refuses to check out the same branch in two worktrees at once. That guardrail maps perfectly onto “one agent owns one branch”: you literally cannot have two agents accidentally sharing a branch’s working state.

4. Instant context switching for the orchestrator

A supervising process (or a human reviewing agent output) can cd between worktrees to inspect each agent’s in-progress state, run its tests, or diff its changes — without disturbing any agent. No stashing, no branch swapping, no rebuild-from-scratch.

5. Shared fetches and reusable caches

git fetch in any worktree updates the shared object store, so every worktree sees new upstream commits without separate downloads. Dependency directories remain independent, but package-manager caches can also be shared across worktrees. Together, those two choices keep new agent workspaces cheap to start.

Sharp edges (and how to handle them)

Worktrees are powerful but a few things surprise newcomers:

• A branch can only be checked out in one worktree. This is a feature, not a bug — it prevents two agents from corrupting the same branch. If you need two views of one branch, create a second branch from it (git worktree add ../view -b copy-of-x x) or use a detached checkout (git worktree add --detach ../view x).

• Untracked files are NOT shared. node_modules, build outputs, .env files, and other gitignored artifacts exist independently in each worktree. Each agent must install dependencies and generate build artifacts in its own directory — or you point them at a shared cache (package-manager stores, NuGet, Go, or pip caches, for example) to avoid downloading everything again.

• Reap orphaned worktrees. If a directory is deleted without git worktree remove, Git keeps a dangling administrative record. Run git worktree prune (or git worktree remove --force) periodically. git worktree list shows everything currently registered.

• Submodules need care. Repos with submodules require git worktree add plus submodule init inside each worktree; plan for it if you use them.

• Long-lived worktrees drift. Fetch and rebase/merge in each worktree just like any branch; the shared object store means the fetch is cheap, but the merge is still per-worktree work.

git worktree list           # see all worktrees and their branches
git worktree prune          # clean up records for manually-deleted worktrees
git worktree remove <path>  # the correct way to delete a worktree

Wrapping up

For agentic development, git worktree is the quiet workhorse:

1. Isolation without duplication — many working directories, one shared history.

2. Cheap and disposable — spawn a worktree per task, reap it on merge.

3. Safe by construction — one branch per worktree keeps agents from corrupting each other.

4. Orchestrator-friendly — inspect, test, and diff any agent’s state without disturbing it.

The important shift is simple: stop treating the repository checkout as shared agent infrastructure. Give every agent its own worktree, and parallel development becomes a set of independent, reproducible workspaces.

Meeting Your Cache

Therapist: Tell me about your cache.

Developer: Well, it’s… complicated. Sometimes it works great. Sometimes it serves stale data and users get mad. Sometimes it invalidates too aggressively and my database dies.

Therapist: It sounds like your cache has trust issues.

Developer: …is that a thing?

Therapist: Oh yes. Very common. Let’s start from the beginning.

The Problem

Cache Doesn’t Know What’s True Anymore

Your cache has a simple job:
Remember things so you don’t have to ask the database every time.

But here’s the existential crisis:
How does the cache know if the data it remembers is still true?

// Cache: "User 123's email is alice@example.com"
// Reality: Alice just changed her email to alice@newdomain.com
// Cache: "But I remember it being alice@example.com?"
// Reality: "That was 5 minutes ago. Things change."
// Cache: 😱😱😱 **existential panic**

This is cache invalidation. It’s one of the two hard problems in computer science, along with naming things and off-by-one errors.

Cache Personality Types

Type 1: The Optimist (Time-To-Live Cache)

cache.set('user:123', userData, { ttl: 300 }); // 5 minutes

Personality
“I’ll trust this data for 5 minutes. What could go wrong?”

Strengths:

• Simple

• Predictable

• Doesn’t overthink things

Weaknesses:

• Serves stale data for up to 5 minutes

• Doesn’t know when data actually changed

• Lives in blissful ignorance

When it breaks down:

// User changes their email
updateEmail(userId, newEmail);

// Cache doesn't know for 5 minutes
cache.get('user:123'); // Still returns old email

Therapist: How do you feel about serving stale data?

Developer: I don’t like it, but I can’t check the database every time. That defeats the purpose of caching.

Therapist: What if the data is critical? Like a password change?

Developer: nervous sweating I… I just hope 5 minutes isn’t too long?

Therapist: That’s avoidance behavior.

Type 2: The Paranoid (Cache-Aside with Validation)

const cached = cache.get('user:123');
if (cached && cached.version === db.getVersion('user:123')) {
  return cached;
}
// Version changed, data is stale
const fresh = db.get('user:123');
cache.set('user:123', fresh);
return fresh;

Personality:
“Trust but verify. Actually, mostly verify.”

Strengths:

• Never serves truly stale data

• Knows exactly when data changes

• Catches problems early

Weaknesses:

• Still hits the database to check versions

• If version checking is expensive, you’ve defeated the purpose

• Constant anxiety about being wrong

Therapist: You check the version every single time?

Developer: What if it changed?

Therapist: But you’re hitting the database anyway. Why cache at all?

Developer: Because checking the version is cheaper than fetching all the data! …right?

Therapist: Is it though?

Developer: existential crisis intensifies

Type 3: The Control Freak (Write-Through Cache)

function updateUser(userId, newData) {
  // Update database
  db.update('users', userId, newData);
  
  // Immediately update cache
  cache.set(`user:${userId}`, newData);
}

Personality:
“I control everything. If data changes, I’ll know because I’m the one changing it.”

Strengths:

• Cache is always consistent with writes

• No stale data for writes you control

• Clear ownership

Weaknesses:

• What about writes from other servers?

• What about manual database updates?

• What about data that changes from external systems?

Therapist: What happens if someone updates the database directly?

Cache: That’s not allowed. All writes go through me.

Therapist: But what if they do anyway?

Cache: THEY CAN’T. I CONTROL THE DATA.

Therapist: This is concerning. You’re exhibiting control issues.

Type 4: The Anxious Overthinker (Event-Driven Invalidation)

// When data changes, publish an event
eventBus.publish('user.updated', { userId: 123 });

// Cache listens for events
eventBus.subscribe('user.updated', (event) => {
  cache.delete(`user:${event.userId}`);
});

Personality:
“I need to know the moment ANYTHING changes ANYWHERE.”

Strengths:

• Invalidates immediately when data changes

• No TTL guessing

• Proactive, not reactive

Weaknesses:

• What if the event gets lost?

• What if events arrive out of order?

• What if the event system is down?

• Constant monitoring of event streams

Therapist: You’re subscribed to 47 different event topics?

Cache: I need to know when things change!

Therapist: But you’re spending all your time processing events instead of actually caching.

Cache: What if I miss an update?

Therapist: This is anxiety. You’re catastrophizing.

Common Cache Anxieties

Anxiety 1: “What if I invalidate too early?”

cache.set('user:123', data, { ttl: 10 }); // 10 seconds

// 5 seconds later
cache.delete('user:123'); // Oops, data was still fresh

// Now every request hits the database 🚨

Symptom: Over-invalidation. Cache has no confidence in its own data.

Treatment: Use longer TTLs with selective invalidation for critical paths.

Anxiety 2: “What if I invalidate too late?”

cache.set('user:123', data, { ttl: 3600 }); // 1 hour

// User changes password
updatePassword(userId, newPassword);

// Cache still serves old password hash for up to 1 hour
// User can't log in with new password

Symptom: Stale data causes user-facing bugs.

Treatment: Invalidate explicitly on writes. Don’t rely solely on TTL for critical data.

Anxiety 3: “What if multiple servers invalidate at different times?”

// Server A
cache.delete('user:123');

// Server B (didn't get the memo)
cache.get('user:123'); // Still has stale data

Symptom: Distributed cache inconsistency. Different servers see different reality.

Treatment: Use a centralized cache (Redis) or cache invalidation events.

Anxiety 4: “What if the database and cache disagree?”

// Database says: email = alice@new.com
// Cache says: email = alice@old.com

// Who's right? Cache doesn't know.

Symptom: Split-brain. Truth has diverged.

Treatment: Database is always the source of truth. When in doubt, invalidate and refetch.

The Cache Invalidation Patterns

Pattern 1: Lazy Invalidation (TTL)

How it works: Set a timer. When timer expires, delete from cache.

Pros: Simple. Works everywhere.

Cons: Serves stale data until expiration.

Best for: Non-critical data that doesn’t change often (user profiles, settings).

Cache personality: Optimistic.

Pattern 2: Eager Invalidation (Write-Through)

How it works: Every write updates both database and cache.

Pros: Cache is always fresh after writes.

Cons: Doesn’t catch external updates. Adds latency to writes.

Best for: Write-heavy workloads where you control all writes.

Cache personality: Control freak.

Pattern 3: Event-Driven Invalidation

How it works: Publish events when data changes. Cache subscribes and invalidates.

Pros: Near-instant invalidation. Works across servers.

Cons: Complex. Event system becomes a dependency. Eventual consistency.

Best for: Distributed systems with multiple writers.

Cache personality: Anxious overthinker.

Pattern 4: Versioned Data

How it works: Store version number with data. Check version before using cache.

Pros: Catches all changes. Works with any write pattern.

Cons: Extra database query to check version.

Best for: Critical data where staleness is unacceptable.

Cache personality: Paranoid.

Pattern 5: No Cache (The Nuclear Option)

How it works: Don’t cache. Just hit the database every time.

Pros: Never stale. Simple. No invalidation needed.

Cons: Slower. Database load increases.

Best for: Data that changes constantly or is queried rarely.

Cache personality: Has given up on therapy.

Real-World Scenarios

Scenario 1: User Profile

Data: Name, email, profile picture
Change frequency: Rarely
Staleness tolerance: High (users understand profile changes take a moment)
Solution: TTL cache with 5-minute expiration + eager invalidation on profile updates

function updateProfile(userId, newData) {
  db.update('users', userId, newData);
  cache.set(`user:${userId}`, newData, { ttl: 300 });
}

function getProfile(userId) {
  const cached = cache.get(`user:${userId}`);
  if (cached) return cached;
  
  const data = db.get('users', userId);
  cache.set(`user:${userId}`, data, { ttl: 300 });
  return data;
}

Scenario 2: Inventory Count

Data: Number of items in stock
Change frequency: Often (every purchase)
Staleness tolerance: Low (can’t oversell)
Solution: Don’t cache. Or cache with very short TTL + aggressive invalidation.

function getInventory(productId) {
  // Don't cache. Always get fresh count.
  return db.get('inventory', productId);
}

// OR cache for 10 seconds max
function getInventory(productId) {
  const cached = cache.get(`inventory:${productId}`);
  if (cached) return cached;
  
  const data = db.get('inventory', productId);
  cache.set(`inventory:${productId}`, data, { ttl: 10 });
  return data;
}

function purchaseItem(productId) {
  db.decrementInventory(productId);
  cache.delete(`inventory:${productId}`); // Invalidate immediately
}

Scenario 3: Session Data

Data: User’s login session, preferences
Change frequency: Rare (only when user logs in/out)
Staleness tolerance: None (security-critical)
Solution: Cache with no TTL + explicit invalidation on logout

function createSession(userId, sessionData) {
  const sessionId = generateId();
  cache.set(`session:${sessionId}`, sessionData); // No TTL
  return sessionId;
}

function logout(sessionId) {
  cache.delete(`session:${sessionId}`); // Explicit invalidation
}

The Two Rules of Cache Therapy

Rule 1: Cache is a Hint, Not Truth

The database is the source of truth. Cache is a guess about what the database says.

If cache and database disagree, database wins. Always.

Rule 2: Design for Staleness

Don’t build systems that break when cache is stale. Build systems that gracefully handle stale data.

Bad: User changes password. Old password works for 5 minutes because cache.

Good: User changes password. Old password stops working immediately (password check always hits database). Profile picture might be stale for 5 minutes (that’s fine).

Key Takeaways

1. All caches serve stale data eventually - The question is how long you can tolerate

2. TTL is a guess - You’re guessing how long data stays valid

3. Invalidation is hard in distributed systems - Multiple servers, eventual consistency, event ordering

4. Cache the read path, not the write path - Writes should invalidate, not update cache

5. Critical data shouldn’t be cached - Or cache with very short TTLs and explicit invalidation

6. Monitor your cache hit rate - If it’s too low, you’re over-invalidating

7. Trust issues are normal - Cache invalidation is legitimately difficult

Conclusion

Your cache has trust issues because the world is untrustworthy. Data changes. Networks fail. Events get lost. Clocks drift.

The best you can do is:

1. Accept that cache will occasionally be stale

2. Design systems that tolerate staleness

3. Invalidate aggressively for critical data

4. Monitor and adjust TTLs based on real behavior

And maybe, just maybe, your cache will learn to trust again.

Remember:

The only thing worse than a stale cache is no cache at all.
And the only thing worse than no cache is a cache that lies to you.

The tech debt of the Internet

The internet is a miracle of engineering. It is also held together by hacks, workarounds, and solutions that made everyone say “this is temporary until we fix it properly.”

Some of these we use everyday without noticing. Lets see how they came to be.

Hack 1: JSONP (JavaScript Object Notation with Padding)

The Problem

You want to fetch data from a different domain. The browser says no:

fetch("https://api.example.com/data")
  .then((r) => r.json())
  .then((data) => console.log(data));

// ❌ Error: No 'Access-Control-Allow-Origin' header

Same-origin policy blocks you. In the mid 2000s, CORS doesn’t exist yet. What do you do?

The Terrible Solution

Observation: <script> tags can load JavaScript from anywhere.

Terrible idea: What if we put JSON data inside a JavaScript file?

// Your page
function handleData(data) {
  console.log(data);
}

// Their server returns this:
handleData({ user: "Alice", email: "alice@example.com" });

// You load it with a script tag:
<script src="https://api.example.com/data?callback=handleData"></script>;

It works! The server wraps JSON in a function call. Your page defines the function. Script tag loads and executes. You have your data.

Why it’s terrible:

• The server can execute arbitrary JavaScript in your page

• No error handling

• URL length limits

• Can only do GET requests

• The word “padding” is a euphemism for “wrapping JSON in a function call like savages”

Why it lasted so long:
Because it worked. And CORS took years to standardize and implement everywhere.

Status in 2026: Officially dead. Unofficially, someone somewhere is still using it and their code will break when browsers finally remove support.

Hack 2: CORS Preflight (The OPTIONS Request Nobody Wanted)

The Problem

It is 2005 and CORS exists now! You can make cross-origin requests! Except… sometimes the browser sends TWO requests:

fetch("https://api.example.com/data", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ data: "hi" }),
});

// Browser sends:
// 1. OPTIONS request (preflight)
// 2. POST request (your actual request)

Why two requests? Because the browser doesn’t trust you (and rightly so!).

The Terrible Solution

The OPTIONS request is a “pre-flight” check. The browser asks the server: “Is it okay if I send a POST request with this header?”

OPTIONS /data HTTP/1.1
Host: api.example.com
Origin: https://yoursite.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: Content-Type

// Server responds:
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://yoursite.com
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: Content-Type
Access-Control-Max-Age: 86400

Only then does the browser send your actual POST request.

Why it’s terrible:

• Doubles the number of requests

• Adds latency

• Server has to handle OPTIONS requests for every endpoint

• Access-Control-Max-Age is supposed to cache the preflight, but browsers cap it (Chrome ~2 hours, Firefox ~24 hours)

• Many developers don’t know why OPTIONS requests exist and misconfigure their servers

Why it exists:
Security. The browser wants to protect the server from dangerous requests. But also backward compatibility - old servers that don’t understand CORS shouldn’t accidentally accept dangerous requests.

Status in 2026: Still here. Still annoying. Still necessary. Will outlive us all.

Hack 3: HTTP Polling (Asking “Are We There Yet?” Every Second)

The Problem (2005)

You want real-time updates. WebSockets don’t exist. How do you get the server to push data to the client?

The Terrible Solution

Just ask the server for updates every second:

setInterval(() => {
  fetch("/updates")
    .then((r) => r.json())
    .then((data) => {
      if (data.newMessages) {
        showMessages(data.newMessages);
      }
    });
}, 1000); // Ask every second

Why it’s terrible:

• Makes 60 requests per minute even when nothing happens

• Wastes bandwidth

• Wastes server resources

• Wastes battery on mobile devices

• Still has latency (updates only every second)

Variations:

Long polling: Keep the connection open until there’s data

function poll() {
  fetch("/updates")
    .then((r) => r.json())
    .then((data) => {
      handleData(data);
      poll(); // Immediately poll again
    });
}

Server holds the request open until there’s data, then responds. Client immediately polls again.

Why it’s also terrible: Keeps connections open forever. But at least it doesn’t waste requests when nothing happens.

Status in 2026: WebSockets exist now. But polling still lives on in:

• Systems that can’t use WebSockets (restrictive firewalls)

• “Enterprise” systems that haven’t been updated since 2008

• Systems that consider Server Sent Events and WebSockets too complex a solution for their use case.

Hack 4: Base64 Images in CSS

The Problem

HTTP/1.1 has a limit on concurrent connections. Every image is a separate request. Loading 50 icons = 50 requests = slow.

The Terrible Solution

Encode images as base64 strings and embed them directly in CSS as data URLs:

.icon {
  background-image: url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA
AAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL
0Y4OHwAAAABJRU5ErkJggg==);
}

Why it’s terrible:

• Base64 is 33% larger than binary

• Can’t be cached separately from CSS

• Makes CSS files huge

• Can’t lazy-load images

• Makes CSS unreadable

Why it was used:

• Reduces HTTP requests (important in HTTP/1.1)

• Entire CSS file can be cached

• No FOUC (Flash of Unstyled Content) waiting for images

Status in 2026: HTTP/2 fixed the connection limit problem. But you still see base64 images in:

• Old codebases

• Email HTML (email clients block external images)

• Single-file HTML apps (everything in one file)

• Systems where image hosting over CDNs is relatively expensive.

• The image is small enough, what’s the harm?(!)

Hack 5: User-Agent Sniffing

The Problem

Different browsers support different features. You need to know which browser the user has.

The Terrible Solution

Check the User-Agent string:

const ua = navigator.userAgent;

if (ua.includes("MSIE") || ua.includes("Trident")) {
  // Internet Explorer detected
  loadIEPolyfills();
}

if (ua.includes("Chrome")) {
  // Use Chrome-specific features
}

Why it’s terrible:

• User-Agent strings lie

• Browsers spoof each other to avoid being blocked

• User-Agent strings are ridiculously long and complicated

• Feature detection is better than browser detection

Example User-Agent:

Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36
(KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36 Edg/91.0.864.59

This is Edge pretending to be Chrome pretending to be Safari pretending to be Mozilla. Why? Because if a website blocked Edge, this partially circumvents the ban.

Feature detection

A much better approach is to use [Feature detection][feature-detection]. Check for presence of the feature in your JS Example:

if ("geolocation" in navigator) {
  // Use geolocation
}

if (typeof Promise !== "undefined") {
  // Use promises
}

Status in 2026: User-Agent sniffing is officially discouraged. But it’s still everywhere because old code never dies.

Hack 6: Cookies for Everything

The Problem (1994)

HTTP is stateless. You need to remember who the user is between requests.

The Terrible Solution

Cookies! A small piece of data sent with every request:

Set-Cookie: sessionId=abc123; Path=/; HttpOnly; Secure

Why it’s terrible:

• Sent with EVERY request, even for images/CSS/JS

• Limited to 4 KB per cookie

• No structured data format

• Global scope by default (every subdomain can read it)

• Security nightmare (XSS can steal cookies, CSRF exploits them)

Why it lasted:
Because nothing better existed. We needed some way to do sessions.

What cookies are used for:

• Authentication (session tokens)

• Tracking (ads, analytics)

• User preferences

• Shopping carts

• CSRF tokens (ironically, to protect against CSRF)

Status in 2026: We have localStorage, sessionStorage, IndexedDB. But cookies persist because:

• They’re automatically sent with requests (good for auth)

• They work across tabs

• Old code depends on them

Hack 7: document.write() (The Original Sin)

The Problem

You want to add content to a page dynamically.

The Terrible Solution

document.write("<div>Hello World</div>");

Why it’s terrible:

• If called after page load, it WIPES THE ENTIRE PAGE

• Blocks page parsing

• Can’t be used in async scripts

• Messes with the DOM

• Everyone who has used it has a horror story

Why it existed:
In 1995, there was no DOM API. document.write() was the only way to generate HTML from JavaScript.

Status in 2026: Not officially deprecated in the spec, but strongly discouraged. (See the mozilla document page on this and you will realize how red it is with warnings.) Chrome actively blocks it in some scenarios. Still in millions of ad scripts because ad tech is where code goes to die.

It was a reliable way to ensure the ad script executed and rendered its content across a variety of older browser environments without needing more complex DOM manipulation methods. Ad scripts often use document.write() to inject further

Hack 8: eval() (The Devil’s Function)

The Problem

You need to execute dynamically constructed code. Maybe you’re parsing a data format (before JSON.parse() existed), maybe you’re building a template engine, or maybe you’re just making questionable life choices.

The Terrible Solution

const code = 'console.log("Hello")';
eval(code); // Executes the string as JavaScript

Why it’s terrible:

• Executes arbitrary code

• Security nightmare

• Performance nightmare (can’t be optimized)

• Debugging nightmare

• Makes code review impossible

Why it exists:
Sometimes you legitimately need to execute dynamic code. JSONP used eval() before JSON.parse() existed.

Status in 2026: Still exists. Still dangerous. Still used in:

• Code playgrounds

• Template engines

• Dynamic query builders

• Bad decisions

Hack 9: The <table> Layout Era

The Problem (1995)

You want to create a layout with columns. CSS layout support barely exists.

The Terrible Solution

Use HTML tables for everything:

<table>
  <tr>
    <td>Sidebar</td>
    <td>Main Content</td>
  </tr>
</table>

Why it’s terrible:

• Semantically wrong (tables are for data, not layout)

• Accessibility nightmare

• Inflexible

• Nested tables everywhere

• Screen readers think everything is tabular data

Status in 2026: Finally dead. If you see table layouts in 2026, the website is either:

• Very old

• Generated by an ancient CMS

• An email (email clients still use table layouts)

Please just use flexbox or css grids for your layouting.

Hack 10: !important (The CSS Nuclear Option)

The Problem

Your CSS rule isn’t being applied. Something else is overriding it. You don’t know what, and you don’t have time to figure it out.

The Terrible Solution

.button {
  color: red !important;
  background: blue !important;
  margin: 10px !important;
  /* I don't understand the cascade and at this point I'm afraid to ask */
}

Why it’s terrible:

• Breaks the natural cascade that makes CSS work

• The only way to override !important is with another !important

• Leads to specificity wars that nobody wins

• Makes CSS unmaintainable — you can’t tell what’s overriding what

• Commonly a sign that the real problem is poorly structured selectors

Why it’s used:

• Third-party widgets inject styles you can’t control

• Legacy CSS is too tangled to refactor safely

• Deadline pressure: “just slap !important on it and ship”

• It always works (that’s the dangerous part)

Status in 2026: Alive and thriving. Every codebase has at least one !important. Most have hundreds. CSS-in-JS and utility frameworks like Tailwind reduce the need, but whenever CSS gets complicated, !important is the first thing developers reach for.

Why These Hacks Matter

Lesson 1: Temporary Solutions Become Permanent

JSONP was a hack. It was supposed to be replaced by CORS. It lasted 15+ years.

Lesson 2: Backward Compatibility is Forever

We can’t remove old features because someone, somewhere, depends on them.

Lesson 3: Constraints Breed Creativity

These hacks exist because smart people solved real problems with limited tools.

Lesson 4: The Perfect Solution Never Comes

CORS is “better” than JSONP, but it’s also more complex, has preflight requests, and still frustrates developers daily.

Key Takeaways

1. Every hack was once a clever solution - JSONP was genius in 2005

2. Temporary hacks become permanent - Plan accordingly

3. Backward compatibility preserves terrible ideas - The web can never fully break old sites

4. Standards take years - Hacks fill the gap

5. Your clever hack will haunt you - Future you will curse past you

Conclusion

The internet works. Millions of websites, billions of users, trillions of requests per day. And it’s all held together by solutions that were supposed to be temporary.

JSONP. CORS preflight. HTTP polling. Base64 images. Cookies for everything. These are the duct tape and baling wire of the web.

And you know what? It works. Not elegantly. Not beautifully. But it works.

Next time you’re tempted to call something a “hack,” remember: the entire internet is a hack. Your hack is in good company.

What Does “LLM Friendly” Really Mean?

Think about the last time someone new joined your team. What did they struggle with?

• Finding where things are

• Understanding why things work a certain way

• Figuring out what patterns to follow

• Knowing what’s okay to change and what isn’t

LLMs face the exact same challenges. An “LLM friendly” codebase is simply one where these answers are easy to find.

The trick is to write code that anyone (or anything 😉) can understand.

Why This Matters Now

LLMs are already writing code in production systems. Tools like GitHub Copilot, Codex, and Claude are generating pull requests, fixing bugs, and adding features. The question isn’t whether to use them - it’s how to use them effectively.

I have been using most of the new coding models on a daily basis for fun and for production code. Here are some of my findings that helped me reduce iterations with my agents.

Core Insight

To get the best out of your LLM agents:

1. Make it easy to write good code

2. Make it hard to write bad code

Let’s explore what this means in practice.

Making It Easy to Write Good Code

1. Write Code in Predictable Ways

LLMs are pattern-matching machines. When your codebase has consistent patterns, LLMs can accurately replicate them.

What this means in practice:

• The way you write logs should be standardized across the codebase

• Configuration handling should follow the same pattern everywhere

• API endpoint naming should be predictable

• Folder structures should be consistent

• File naming should match what’s inside

Example Scenario:
If you have 10 controllers that all follow the same structure - constructor, private methods, public methods, error handling - when an LLM creates the 11th controller, it will naturally follow the same pattern.

Why it works:
LLMs learn from the code they see. Consistent patterns mean the LLM has strong signals about how to write new code. Inconsistent patterns mean the LLM has to guess, and guesses lead to errors.

2. Have Reference Files for Coding Styles

One good example is worth a thousand words of explanation.

What to include:

• A well-written test file that shows your testing patterns

• A reference controller that demonstrates your preferred structure

• Example configuration files that show the right way to set things up

• Sample pipeline definitions if you use CI/CD

Make sure the reference file is of high quality. A bad reference file is worse than no reference file.
The LLM will replicate the problems.

3. Create Base Documentation for Project Structure

LLMs need to understand the big picture before they can work on specific pieces.

Create a document that answers:

• What does this project do?

• How is the code organized? (What goes where?)

• What are the key conventions we follow?

• What external systems do we integrate with?

• What’s our approach to error handling?

This doesn’t need to be elaborate. A simple README or ARCHITECTURE.md file that gives the 30,000-foot view is enough.

Why it matters:
Without this context, LLMs either load a lot of context by scanning through files or make assumptions. With this context, they make informed decisions.

4. Make Similar Things Look Similar

If two things do similar jobs, they should look similar in code.

This is especially powerful for:

• Pipeline definitions - Infrastructure-as-code files like Bicep, ARM templates, GitHub Actions, or Azure DevOps YAML should follow templates

• API endpoints - If you have 20 REST endpoints, they should all follow the same pattern for routing, validation, and error handling

• Database queries - Query patterns should be consistent (parameterized, error handling, connection management)

What happens when you do this:
LLMs become extremely good at replicating well-defined patterns. If your pipeline files all look alike, the LLM can create new ones with high accuracy.

5. Provide Examples in Requirements

Task descriptions with examples produce better results than task descriptions with just text.

❌ Instead of:

Add validation for the email field

✅ Write:

Add validation for the email field.

Example of how we validate in UserController.cs:
- Check if email is not null
- Check if email matches regex pattern
- Return ValidationError if check fails

Follow the same pattern we use for phone number validation in the same file.

Why it works:
LLMs are one-shot generators for most PR tools. They don’t get to iterate with you. More context upfront = better first attempt.

6. Keep Changes Small and Focused

One change per PR works better than multiple changes in one PR.

LLMs are getting exceedingly good at making large changes in one shot. However, the more changes that are made, the more you have to review. This applies to both human-written and LLM-written code, but it’s especially important for LLMs because:

• Larger scope has more chances of deviations from objective.

• Small, hard-to-catch bugs can seep in when a lot of files are changed.

What to avoid:
“Refactor the entire service layer and add three new features” is too much for one task.

What works better:
“Add email validation to UserController following the pattern in UserValidator.cs”

It also works fine if you give a structured list of changes in multiple files to steer the direction of changes.

Making It Hard to Write Bad Code

These are guardrails that prevent LLMs (and humans) from making common mistakes.

1. Use Linters and Code Analysis Rules

Most LLM-based coding agents use builds as a way to validate their changes. If the build fails, they fix and retry.

This means linters are incredibly powerful for steering LLM behavior.

What to enforce:

• Code style rules (consistent formatting, naming conventions)

• Code analysis rules (potential bugs, security issues)

• Static analysis (unused variables, unreachable code)

• Custom rules specific to your domain

💡Tip

If something is important enough that you comment on it during code reviews, make it a linter rule instead.

Why this is powerful:
Linters give immediate feedback. LLMs see the error, understand what’s wrong, and fix it automatically. This creates a tight feedback loop that improves code quality without human intervention.

2. Break Builds on Violations (Not Just Warnings)

Some LLMs ignore warnings. They only fix errors that break the build. If something is important, make it an error, not a warning.

Example:

• Security rule violations → Break the build

• Required documentation missing → Break the build

• Code coverage below threshold → Break the build

• Naming convention violations → Break the build

The tradeoff:
This might seem strict, but it’s actually liberating. It makes the rules explicit and automatic. Nobody has to remember to check; the build checks automatically.

3. Avoid Suppression Files, Use Inline Suppressions

Some LLMs use global suppression files as an escape hatch when problems become complex.

What happens with suppression files:
Sometimes, when the LLM can’t fix a code analysis error, it adds a suppression to a global file and moves on. This accumulates technical debt.

Better approach:
Require inline suppressions with justification:

#pragma warning disable CA1031 // Do not catch general exception types
// We need to catch all exceptions here because this is the top-level error handler
catch (Exception ex)
{
    // handle
}
#pragma warning restore CA1031

Why this works:
Inline suppressions are visible during code review. They force the developer (human or AI) to justify why the rule doesn’t apply in this specific case.

4. Have Tests that LLMs Can Follow

If you have one well-written test, LLMs can generate more tests following the same pattern.

What makes a good reference test:

• Clear arrange-act-assert structure

• Descriptive test names that explain what’s being tested

• Good use of test helpers and fixtures

• Appropriate assertions

Instruction that works well:

Add tests for the new validation logic.
Follow the pattern in UserValidationTests.cs.
Use the same helper methods and assertion style.

What to avoid:
Don’t let LLMs add unnecessary tests just to increase coverage. Specify “add relevant tests only” in your requirements.

Practical Tips for Faster Iterations

1. Set Up Quick Validation Builds

If your build takes 20 minutes and the LLM runs 5 iterations, the time just adds up.

The Solution: Create a lightweight “quick validation” build specifically for LLM iterations:

• Skip time-consuming steps that aren’t relevant (deployment, packaging, slow integration tests)

• Run only linters, unit tests, and fast validations

• For agent-based PRs, save the full build for final PR validation and use the simpler build before agents publish the PR.

2. Add Instructions to Avoid Common Issues

LLMs sometimes add things you don’t want. Be explicit about what NOT to do.

Examples of useful negative instructions:

- Don't add suppression files unless absolutely necessary
- Don't add markdown files for explanation
- Don't add unnecessary comments
- Don't add tests that just verify implementation details

Why this matters:
LLMs often try to be “helpful” by adding extra documentation or comments. If you don’t want that, say so explicitly.

Continuous Improvement Strategy

You don’t need to fix everything at once. Here’s a gradual approach based on what has the highest impact:

Phase 1: Foundation (Week 1-2)

1. ✅ Create a README with project structure and conventions

2. ✅ Identify and document your most common patterns (logging, error handling, configuration)

3. ✅ Create reference files for common tasks (tests, controllers, services)

Phase 2: Guardrails (Week 3-4)

1. ✅ Enable linters and code analysis rules

2. ✅ Make important rules break the build (not just warnings)

3. ✅ Remove global suppression files; require inline suppressions

Phase 3: Optimization (Ongoing)

1. ✅ Set up quick validation builds for faster iterations

2. ✅ Test with LLMs and refine based on results

3. ✅ Add instructions files like copilot-instructions and claude skills to avoid common issues

Start with the area of your codebase that changes most frequently. That’s where you’ll see the biggest return on investment.

Hacks and Tricks from the Field

Use Voice Typing for Task Descriptions

Adding context is important, but typing detailed task descriptions is tedious. Use voice typing to:

• Add more detail without typing fatigue

• Provide richer context naturally

• Explain examples and patterns verbally

Why it works: People naturally provide more context when speaking than when typing.

Have a Copilot Instructions File

Create a .github/copilot-instructions.md file (or similar) that tells LLMs:

• What patterns to follow in your codebase

• What to avoid

• How to structure code

• What good looks like

This file is picked up by Copilot and other tools, reducing the need to repeat instructions in every task.

Key Takeaways

1. Treat LLMs like new team members - The same things that help humans also help AI

2. Consistency beats perfection - A consistent mediocre pattern is better than inconsistent excellent patterns

3. Make good code easy - Clear patterns guide LLMs toward quality

4. Make bad code hard - Linters and build rules prevent common mistakes

5. Provide examples - One good reference file beats long written instructions

6. Be explicit - Say what you want AND what you don’t want

7. Iterate based on results - Learn what prompts work and refine your approach

8. Start small - Fix high-change areas first, then expand gradually

Conclusion

Making your codebase LLM-friendly isn’t about writing code for robots. It’s about writing clearer, more maintainable code that communicates its intent effectively to anyone reading it - human or AI.

The practices in this post are fundamentally about good software engineering: consistent patterns, clear documentation, automated quality checks, and explicit conventions. These practices have always made codebases better for humans. LLMs just make the benefits more obvious and immediate.