DEV Community: Alex Tong

Your auto-generated CLAUDE.md is worse than no file at all

Alex Tong — Tue, 08 Sep 2026 13:10:03 +0000

This is the CLAUDE.md workshop I built and taught to 500+ engineers at The New York Times, rebuilt for YouTube. Part one, eighteen minutes:

Your auto-generated CLAUDE.md is worse than no file at all

If you'd rather read than watch, the cut-down version is below. Everything I built in the video (the fifteen-line template, the prompt, the repo, the grading skill) is linked from the video's description, so go watch it on YouTube.

I built a fake news syndication service called Bulldog. You know when the same article shows up on twenty different websites, word for word the same dang article? Bulldog is the thing that pushes one story out to all of those partners.

Then I baked four traps into it. The kind of trap a coworker who's been at the company for a year catches instantly but a new hire on day one would never guess.

After that I opened a fresh Claude Code session and handed it three tasks.

Claude did all three. It wrote tests for them too. Every single test passed.

And it walked into all four traps.

I did the exact same thing again. Same repo, same prompt, brand new session. The only difference was that this copy of the repo had a fifteen-line CLAUDE.md in it.

Zero traps were triggered.

[

](https://substackcdn.com/image/fetch/$s_!jAz6!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F1d233e25-6de4-4782-a2eb-73d680eecd5a_1000x563.gif)

Why fifteen lines did that

Every Claude session has a hard ceiling on how much it can hold at once. Your files, your prompts, everything it reads. That ceiling is the context window, and the easiest way to picture it is a sponge. It soaks up everything around it, it can only hold so much, and when you overfill it, the OLDEST stuff falls out first.

[

](https://substackcdn.com/image/fetch/$s_!y81q!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F0c3fb6d6-2518-4d16-b49b-ed8016cd2a91_1000x563.gif)

Every new session is a brand new dry sponge. CLAUDE.md is the first liquid that goes in, automatically, before you type a single word. Think of it like the house rules pinned up in a professional kitchen. Every chef who starts there reads them on day one.

Which is why what you put in it matters way way more than how much.

The one principle

Every line in your CLAUDE.md must earn its place. Full stop!

Claude already knows how to code. It can read your whole repo. So don't repeat anything it can figure out on its own. Compare these:

"Run npm test to run the tests." Claude knows this, delete it.
"npm run check exits 1 on a clean checkout on purpose. That's the sample data, not a broken build." THAT earns its place. Claude might work it out after a few turns, but it'd burn valuable tokens figuring it out every single session.
"You are an expert senior engineer. Be thorough." It's already trying its best, I promise. Role prompts like this can be helpful but not when they're this general.
"Our fiscal Q3 starts in February. Every date I give you is fiscal, not calendar." Earns its place.

[

](https://substackcdn.com/image/fetch/$s_!veuK!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2Fea9ddad9-ab0e-4a8e-ac58-eceab40ff4fc_1000x563.gif)

Thariq at Anthropic put it better than I can: focus on information that pushes Claude out of its normal way of thinking.

The test I use: could Claude have figured this out on its own? If no, it goes in. If yes, but it would take a substantial amount of time or tokens to get there, it also goes in. And expensive doesn't just mean tokens. Four minutes of watching Claude dig around your computer is four minutes every time you start a new session.

The five things

1. Name and define your systems. Bulldog talks to another make believe service called Lily. That repo isn't on my machine. Unless I tell Claude what Lily does, it's going to go scan GitHub to find out, every single conversation that touches Lily. One line with the name and a concise description ends that. This applies outside engineering too. If you're a lawyer or a real estate agent with internal jargon only your firm uses, define it.

2. State your non-obvious defaults. Every repo has at least one thing that looks totally standard and isn't. Maybe your tests live somewhere nobody expects, or your main branch isn't really production. Claude makes very calculated guesses based on what the majority of the internet does, so anything your team does differently is a guess it will get wrong.

3. Document the gotchas, and say why. These are the ones you add after somebody gets burned. And most people skip telling Claude the reason. "Never add a field to version one" is fine. "Never add a field to version one, because a partner parses it by position and one extra key crashes their overnight import" is way better, because now Claude knows what it's protecting. Would you hand a junior engineer a rule and not explain it? Don't do it to Claude either.

4. Set behavioral guardrails. These are about how Claude goes about the work. "Never spend more than three attempts per issue, because retry loops waste tokens." Notice the why here again.

5. Define your decision frameworks. When two approaches are both valid, Claude tie-breaks with whatever the internet upvoted. Give it your rubric instead. Mine for Bulldog, most important first: reversibility, testability, readability, consistency.

You don't have to be an engineer for this one. If you use Claude for accounting, yours might be something like: audit defensibility, consistency with last year's return, the client's risk tolerance, and then total tax saved. Look at that last one. Tax saved is DEAD last. When two treatments are both valid I'm picking the one I can defend in an audit, not the biggest refund. But Claude doesn't know that unless I write it down, so it's going to optimize for the refund because it assumes that's what I want.

Remember, Claude is a gambler. A compulsive one. It's gambling with statistics, and your CLAUDE.md is how you can fix the odds.

So why not just run /init

Claude Code ships a /init command that writes a CLAUDE.md for you. A group at ETH Zurich actually tested this. They ran the real /init for every major coding agent against 138 real GitHub issues, and Claude Code's best score was with NO auto-generated file at all.

Hence the title. A file full of things Claude already knows is dirty water the sponge didn't need.

The catch

Everything in CLAUDE.md is advisory. It's not enforced. In a long enough session Claude will drift off from it. Write it anyway, tonight, by hand or with Claude. Give it the five categories and run every line through the one filter.

▶️ Watch the full thing here: Your auto-generated CLAUDE.md is worse than no file at all

Every resource from the video is free inside The AI Kitchen, my Skool community: the fifteen-line CLAUDE.md as a fill-in-the-blank template, the exact prompt I gave Claude, the Bulldog repo with both branches, my one-page digest of the ETH Zurich paper, the five-things checklist, the terminal statusline script from the video, and the skill that grades your CLAUDE.md line by line.

Join my Skool for free: alextong.me/kitchen

One ask. Reply to this email and tell me one thing you never wrote down but probably should have for your team. Give me context, because I have no idea what y'all do all day. That's a line that belongs in your file, and I genuinely want to read yours!

Upwards and onwards, thanks for reading!

40 Engineers, 40 Definitions of Done.

Alex Tong — Thu, 16 Jul 2026 14:30:09 +0000

There’s a difference between hiring people and building a team, and most orgs are relearning it now with AI.

Hiring more gives you more hands. A real team gives you a unit that already knows how to work together, with someone who owns the output. Anyone who’s tried to fix a slow project by throwing more people at it knows how that ends: every new person is one more thing to coordinate, and the coordination cost grows faster than the actual extra output.

Now watch what happens when you hand Cursor or Claude Code to 40 engineers with no shared agreement on how the AI’s output enters your codebase.

You didn’t add 40 units of productivity. You added 40 prompt styles, 40 definitions of what the AI is allowed to own, 40 opinions on what gets reviewed and what gets waved through. The work of merging all that into one coherent system grows faster than the code the tools generate. It’s the oldest team-building mistake there is, just wearing new clothes: you added bodies, not a team.

The fix isn’t more access. It’s the contract first. Run the checklist most orgs skip: is there ONE written review standard every agent-written PR has to clear, or does each reviewer wing it? Does a fresh repo come pre-loaded with your team’s rules and known gotchas (a scaffolded .claude/, a shared PR-review skill), or does every engineer rediscover them? Is review tiered by risk, so a copy tweak and a payments change don’t get the same glance? Decide all of that first, THEN roll out the tools.

Ownership clarity and the right scaffolding beat tool access every time.

If you rolled out AI coding tools in the last six months, does your org have one written agreement for how agent code gets reviewed and merged, or one per team, or one per engineer?

[

](https://substackcdn.com/image/fetch/$s_!L3FC!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2Fc144d04b-d08d-400b-9b79-6113a06d8789_1080x1080.png)

AI Has No Taste: Why Everything Built With It Looks the Same

Alex Tong — Wed, 15 Jul 2026 13:00:00 +0000

🎟️ I walked past 10ish startup booths at Datadog's DASH 2026 last week. By the eighth one, I could basically predict the exact landing page before I got to it.

Same centered hero. Same two big gradient buttons. Same rounded cards with the same soft shadow. Same clean sans-serif font (iykyk). Same dark mode, same single accent color.

I could immediately tell that almost all of these products were built heavily with Claude Code or OpenAI's Codex. I use these tools every single day, so I can spot it the moment I see it. And don't get me wrong, these are super talented people shipping insanely fast. The velocity is real.

One of my managers put me onto a line she heard on Lenny's Newsletter this week: "AI has no taste." Walking that floor at DASH, it clicked.

Velocity !== taste. AI is REALLY good at giving you the "average" answer. The safe layout. The default component. The thing 10,000 repos did. You ask it to build a landing page and it builds you THE landing page, basically the average of everything it ever scraped on the internet.

And that's the trap. When everybody builds from the same model, everybody ships the same product. A product that looks like every other product is a product nobody remembers, I can guarantee it.

And to be clear, I do think it's totally fine for your actual codebase to lack taste. Code has a target: optimal complexity, the simplest thing that solves the problem, and once you hit both, you're done. Design and product though? They have different targets. There's no "optimal" accent color or "optimal" feature. That's where the taste lives, the SPICE: knowing which idea is even worth building (most aren't), killing that default gradient, making the one weird, opinionated call the model would never suggest on its own. That part you still can't automate (at least for now 😭).

So maybe the new senior engineering skill isn't just building fast. We can honestly all build fast now. It's being the one with the eye, for product and design, to spot the median answer and say: nope, not that one.

Genuinely curious where you land: is "taste" the real moat now? Or does good code have taste too, and I'm drawing the line in the wrong place? 🧛

P.S. Evidence this photo wasn't AI-generated: I'm caught mid-sentence asking the photographer to take it in landscape instead. 📸

Related: Building the eye to spot the default answer and steer against it is exactly what I coach, whether you're an engineer or a product manager. More here: alextong.me/services →

Stop Asking Your Engineers to Wear Multiple Hats

Alex Tong — Tue, 14 Jul 2026 14:21:51 +0000

I’ve said this before and I’ll say it again, I never let one AI agent build a feature and check its own work. I have it build the MVP fast, then I bring in fresh agents whose only job is to tear it apart and hunt for bugs. The builder is too deep in it, and too eager to ship, to also be the critic.

That’s always been my workflow, even before the age of AI. But it’s the same mistake I keep seeing eng leaders make at team scale: they hand the shiny, might-not-work AI bets to the same people already on the hook for keeping production alive.

Boris Cherny (who leads Claude Code) put his finger on why. Looking at his own team, he saw five archetypes: prototypers who churn out ideas most of which never ship, builders, sweepers, growers, and maintainers who keep a mature system secure and reliable as it scales.

The prototyper and the maintainer are opposite wiring. One is at their best failing fast on things that might not pan out. The other is at their best making sure absolutely nothing breaks. Ask one person to be both and you get neither, because the “keep it alive” work is always more urgent, so it quietly eats every hour the exploring needed. It’s like asking the line cook in the middle of the dinner rush to also design next season’s menu. That’s a no-no.

So don’t hand your big bet to whoever’s already carrying the pager. Give it to someone whose actual job, this month, is to explore. Even if that’s just one person, or a two-person pod inside the same team, with its own goals and permission to fail. Protect the explorer from the maintenance, and the maintenance from the explorer. It’s time we rethink the way we structure engineering teams.

You’re not hiring different people. You’re pointing the right people at the right mode.

So which is it on your team: does your exploration work have someone who owns exploring it, or is it a side quest for whoever’s also keeping the lights on?

🧛

#EngineeringLeadership #AIStrategy #EngManagement #ClaudeCode

[

](https://substackcdn.com/image/fetch/$s_!51M-!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F17e126ea-8d5d-4bc7-90dc-08e8ae46a28f_1080x1080.png)

You're building on rented land: don't tie your work to a single AI model

Alex Tong — Tue, 14 Jul 2026 13:00:00 +0000

🏚️ What a crazy email to wake up to.

src="/notes/rented-land/fable-suspended-email.jpg"
alt='Email from the Claude team with the subject "Update: Claude Fable 5 access suspended"'
className="mx-auto block w-auto max-h-[40rem] rounded-lg border border-border/10"
/>

If you haven't been following the news: Fable was out for 72 hours before a letter from the US government forced Anthropic to pull the most powerful model it had ever shipped. Talk about a press release. 😬

If you spent this whole week wiring Fable into a new workflow, recording a tutorial on it, or building a side project that leaned on it, first off, sorry to hear that. 🥲

But hopefully this helps all of us realize something: frontier models are not stable primitives. Unlike past versions of software, these models aren't stable releases you can safely build on top of the minute they drop. A model can vanish over a security threat, a price change, a policy shift, or a single letter from the Commerce Department.

So the things you really want to build shouldn't be tied to one specific model or one company. They should be adaptable. The thing worth investing in is the muscle underneath it all: the judgment, the process, your ability to get close to the same result out of any model. And all of that lives in your workflows, not in the model.

As much of a Claude fanboy as I am, this is a great lesson. Whatever you build on top of a single frontier model, you're building on rented land. 🏚️

So don't fall in love with specific models. Work on the skills that let you stay model-agnostic, because those are the ones that survive the next letter from the government.

Related: Building that model-agnostic muscle is exactly what I help engineers and teams (and really anyone) do. If that's useful to you, it's all here: alextong.me/services →

Earn the right to optimize

Alex Tong — Thu, 09 Jul 2026 13:00:00 +0000

Your LinkedIn feed this week: "I built a second brain." "How I run 12 agents at once." "10 MCP servers you need." It's 10:30AM Tuesday and that's the 3rd one I've scrolled past.

I orchestrate agents daily. Use 2-3 MCPs and 10 skills regularly. The second brain on my computer? Gathering dust for months.

Last month I bought a 5-year-old M1 Max MacBook for $1,300 for my music project SUIMA. The latest maxed-out M5 Max next to it was $7,349 with 128GB of RAM. Ten years ago I'd have gone into debt for the M5 Max and only used a third of it.

Here's what I finally learned after 15 years of terrible purchases and too much time spent researching the best of the best: you don't earn the best gear by buying it. You earn it by needing it.

Same goes for Claude.

Half my LinkedIn feed is installing new repos, new frameworks, new wrappers. Trying to make Claude better, faster, smarter. Multi-agent boilerplate before they've tried one agent. Second-brain setups on their computers, but their projects haven't shipped a feature in months. Token-optimization playbooks for context windows they've never come close to filling.

Tuning the bike shed instead of practicing how to actually ride the dang thing.

Here's the thing, installing FEELS like work. It's measurable. It's debatable. It's safer than the actual hard part: shipping features with what Claude already gives you.

So they install.

Look, I'm not saying any of this is bad. Tools matter. Eventually. When the constraint is real and you can feel it in your builds, that's when you reach for sub-agents, custom MCP servers, that dang glorious second brain.

Multi-agent workflows? I earned those by hitting Claude's single-agent ceiling so often I felt it in my sleep. The second brain? I built it before I'd hit any limit at all. It's been gathering dust ever since. An artifact of FOMO, not need.

On your own projects, have you actually hit the ceiling of what Claude can do on its own? If not, you don't have a tooling problem. You have a shipping problem.

You need to earn the right to optimize first.

Third-party tools are a reward for hitting Claude's ceiling. Not a substitute for finding it.

What's something you "optimized" way before you'd earned it?

🎛️

Teaching CLAUDE.md to 500 engineers at EngX

Alex Tong — Wed, 08 Jul 2026 13:00:00 +0000

📣 📰 Just wrapped up EngX — The New York Times' annual engineering conference. Two days, 500 engineers, tons of special guests from the most amazing corners of the industries and workshops where our teams all shipped real work. 🧛

I presented "The Definitive Guide to CLAUDE(dot)md" — a 90-minute talk + workshop on teaching Claude what it can't learn from your code. Sarah Duncan presented it alongside me in a parallel room (500 engineers is a lot for one room in the heart of NYC).

Also may have gone a little overboard with the Game of Thrones references, no ragrets. 😏🐉

👷 Teaching this forced me to crystallize more than half a decade of engineering instincts into something tangible. There's a huge difference between knowing how to do something and being able to explain why it works. And teaching a room full of amazing engineers is the fastest way I've found to find gaps in your own thinking.

🫶 Grateful to the entire team that made EngX happen!

Earlier: Our internal AI training was the first run at this — What teaching AI taught me about my own thinking →.

Claude's session limits accidentally fixed my burnout

Alex Tong — Tue, 07 Jul 2026 13:00:00 +0000

Anthropic made a trade-off with your productivity last month and they didn't ask you first. 😬

I've been noticing two things happening in parallel as I use Claude now.

Number 1 — session limits are way tighter. I'm hitting caps way faster than I used to, especially during peak hours. On weekends I basically get stopped by lunchtime. We know this is true because they publicly announced it.

Number 2 — something about the reasoning feels off to me now? I always use Opus 4.6 with extended thinking on and high effort — but the output seems shallower lately. I find myself correcting more and more mistakes even though I know my internal Claude files have drastically improved over the months. And with the new auto dream mode on, I can only imagine my memories have also drastically improved. So there's no reason why my performance should be degrading out of nowhere... 🤔

We know that publicly, Anthropic quietly dropped the default thinking effort from high to medium back in early March. But what we haven't confirmed is if anything has actually changed with the model. Or at least I haven't personally confirmed — I'm sure somewhere on Reddit or on the interwebs, someone has already figured this out.

Here's where it gets super weird though...

The session limits are actually kind of saving me.

I wrote an entire newsletter a couple weeks ago about Claude Code burning me out. Because I haven't really felt able to stop working — the tool never stopped being available so I'm always available. But now Anthropic built the off-switch that I literally can't turn back on. Unless I upgrade my plan or pay for extra usage (which I don't think I'm gonna do...)

So I'm sitting in this uncomfortable spot where the same company simultaneously made my health better and my work worse? Although I do have them to thank for making my work drastically better to begin with. Didn't sign up for this trade...but I'm also not sure I'd trade it back either?

If you're paying for a Claude subscription and feeling these two new things too — are you feeling relieved or frustrated? Because somehow I'm feelin' both? 🤷

Claude won't kill junior engineering jobs

Alex Tong — Thu, 02 Jul 2026 13:00:00 +0000

"Claude is going to kill junior engineering jobs." 🤔

I keep hearing this and I heavily disagree.

But the juniors who don't adapt to what's ACTUALLY changing? They're going to get left behind.

Will it change the role of junior engineers? Of course. It's changing the role of every engineer.

Maybe it's the old model. Juniors aren't going to get assigned a bug, write the code, and wait for a senior to review it — because Claude is the one writing the implementation now.

Here's the critical problem with that shift. Mid-level and senior engineers spent YEARS building their pattern recognition before AI existed. They wrote bad code for years and had other seniors and staff engineers critique it.

Now that Claude is generating most of our code — how does a junior engineer learn?

Well, by asking Claude of course. Claude Code literally has a Learning mode that drops TODO(human) markers and asks YOU to implement the key pieces.

How?

Activate it using /config
Type "Output Style" in the search bar
Choose "Learning" for the hands-on approach or "Explanatory" for lecture-based.

It's like pair programming with a senior 24/7 who never gets tired (or annoyed at you).

But honestly — the biggest shift isn't even about code anymore. It's about turning vague tickets into crisp specs. Juniors who partner with their product managers and understand things on a high level perspective, instead of waiting for requirements to land in their lap are going to level up the fastest.

So no, I do not think Claude is going to kill junior engineering jobs. If anything, it's just shifting the role to something more like a junior builder. 🔨

Are juniors at your company adapting or still stuck in the old model?

I Hand-Built Liquid Glass to Prove It Was a Waste of Time

Alex Tong — Wed, 01 Jul 2026 14:30:39 +0000

[

](https://substackcdn.com/image/fetch/$s_!KN2y!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F4a975bee-735f-43cc-8765-02972dacc57d_1456x816.png)
Liquid Glass implemented on my website, alextong.me

I called Liquid Glass a waste of engineering time.

Then I spent two hours hand-building it on my own site, just to verify my claims. Then I spent way, way longer than two hours ripping out half of what I built. Turns out I was half right, and building it is what showed me which half.

Here's the whole receipt: what I tried, what I killed, and the rule I'd hand my past self before ever touching it again.

Subscribe now

There are technically _ two _ Liquid Glasses

They cost wildly different things.

The first is basically free: use the platform's own components. In a native app, you rebuild it with Apple's latest developer tools, and your system buttons, tab bars, and sheets turn to glass for almost nothing. Better still, when Apple refines the design later, your app inherits their updates automatically. That's not rent. That's a software update.

The second is building the effect yourself. On web surfaces there's no system layer to inherit, so it's the only option you've got. That's the one I took on alextong.me. And it charges you twice for it.

What I actually built (and tore back out)

First, a description, or none of this lands: my personal portfolio site is dark and moonlit. There's a moon, some drifting fog, and little bats moving around in the background (in Dracula-themed fashion), and the content sits on top in frosted-glass cards you can see all that moving stuff through. Seeing the background move through the glass is the whole effect. It's also where all the rendering cost comes from.

I looked at a few of the open-source recreations floating around. None was a clean drop-in, so I built it in two layers.

The first layer is the cheap one: a plain CSS blur (the backdrop-filter property) with a soft moonlit sheen on the edge. One reusable .glass-card style, and every card on the site uses it. Cheap to run, easy to keep.

The second layer is the real iOS-26 Liquid Glass look: actual refraction, where the glass bends and warps the moon and fog behind it instead of just blurring them. That's the expensive part. It runs on an SVG filter (I adapted nikdelvin's open-source version), heavy enough that I only turned it on for capable desktop browsers and switched it off on phones and low-end devices. Everywhere else, it falls back to the cheap blur. (For the other small effects on the site, I went through 44 components on 21st.dev, picked four, and rebuilt them in plain CSS instead of installing libraries. Extra dependencies are their own kind of rent.)

Then I made my mistake. I switched that expensive refraction on for every card, not just the big ones up top. Suddenly a dozen cards were all bending the moving background at once, and scrolling completely fell apart on the site.

So I tried to claw the cost back, and mostly made it worse:

Hide the whole animated background (the fog, the moon, all of it) while you scroll. Too aggressive, the whole page flickered. Reverted.
Swap the glass for plain solid cards. Killed the cost instantly. But it also killed the entire point of the experiment, so, no. Put the glass back.

(The fix that actually stuck is next, and it's narrower than both of these.)

💵 Bill #1: it's expensive to render

What finally worked was surgical, because the problem was specific: every one of those glass cards has to redraw that expensive refraction from scratch on every single frame while you scroll on web. A dozen of them doing it at once tanked my scroll into a visible stutter. Worst frame: 142ms to draw. That’s not a dropped frame, that’s a hitch you feel in your thumb.

The fix was to stop paying for the effect at the one moment nobody can appreciate it anyway: mid-scroll. I wrote a controller (a ScrollStateController) that, the instant you start scrolling, swaps just the cards down to the cheap plain-frost version and leaves the moving background alone, then brings the full refraction back once you stop.

Getting that last part smooth was the fiddly bit, and where most of the real work went. Restoring all dozen cards at once was its own little hitch, so they come back a few per frame instead of in one lump. And slow scrolling fooled my first version: it has tiny pauses baked into it, so the code kept thinking you’d stopped and slamming the heavy effect back on mid-scroll. The version that actually works waits for a real gap, about a quarter-second of stillness, before it trusts you’re done. Worst frame dropped from 142ms to 33ms. The homepage went from a choppy 16 frames per second while scrolling to a smoother 23 fps.

One bug ate a full hour. My build tool was silently breaking the fix, quietly deleting one line of the effect, so it only worked when I forced it in with inline JavaScript instead of normal CSS. (For the engineers in the room: Lightning CSS was dropping the unprefixed backdrop-filter from a prefixed !important pair.) That’s the kind of thing you only catch staring at the browser’s computed styles at 1am...

And I couldn’t trust the usual performance tools here, because the standard one (Google’s Lighthouse) doesn’t measure scroll smoothness at all. So I built my own little test that actually scrolls the page and clocks the frame rate as it goes (npm run perf:scroll, if you want to copy the idea). Steal it, honestly, if you ship anything that animates while people scroll.

Subscribe now

📞 Bill #2: Apple is dialing it back

Here’s the insane part. Apple is supposedly all-in on this glass look. It’s their biggest redesign in a decade, and everyone and their mom is rushing to copy it. But then look at what they actually did at WWDC 2026: they shipped a slider that literally turns it down, from full glass all the way to fully tinted. Basically a button to opt out of Liquid Glass completely.

And it wasn’t a one-off. The design language is here to stay, reporting is clear on that, but several releases since the initial launch have quietly added another way to tone it back down. iOS 26.1 added a tint toggle. 26.2 added a transparency slider for the lock-screen clock. iOS 27 made a version of that slider system-wide and re-tuned the material for readability, with sharper icons. On the Mac, the toolbars went more solid and uniform.

The people who said the maximal glass hurt legibility? Apple just proved them right. My honest read: the launch look overreached, and every one of these sliders is Apple quietly conceding it. But they’re not scrapping the glass, they’ve tied their whole cross-device design story to it. This is the same move they pulled with iOS 7: ship the bold version, then spend the next year sanding down the parts that hurt. The glass itself isn’t dying. The excess is. And if you hand-rolled that exact excess, you’re now maintaining the part Apple just made optional in early June.

😟 So should you build it?

Honestly, it depends where you are and how much money you have. Four situations, whether you're shipping a weekend project or a product with millions of users:

Native, using the platform's stock UI? Rebuild it with Apple's latest tools and the built-in bars, buttons, and menus turn to Liquid Glass for free, and they inherit Apple's future fixes. Just test it thoroughly, because content now slides under see-through bars and text can get harder to read.
Native, but with your own custom interface? (Most real products have some.) Yes, adopt it, but budget it as a real project. Stock bars, buttons, and menus turn to glass for free on recompile and keep inheriting Apple’s fixes. You don’t have to rip your custom views out either: paint Apple’s real glass material onto them with the system’s glass modifier and you still inherit its re-tuning (like the readability pass), just not the full stock-component behavior. Only what you hand-roll from scratch inherits nothing. So lean on stock where the brand doesn’t really really need custom, use the system glass on the custom parts that carry the brand, and hand-roll only where you’ve got no other option. Don’t leave it half-glass and half-flat, a half-updated app looks more broken than either.
Web, and the look genuinely IS the product? (A brand page, an interactive feature.) You can build it, but use the cheap frosted-blur version, not the heavy realistic refraction, keep it to a few pages, and check it doesn't stutter on a cheap phone. The biggest risk here is introducing severe lag to your web experiences just to implement something that is literally optional now.
Web, normal reading or app screens? Skip it. That's the default at scale. There's no free web version, so you'd pay full price, in scroll lag on your weakest devices.

One trap catches big companies especially. A lot of apps that feel native are really web pages wrapped in a thin native shell (the content is a webview, basically a browser window with no address bar). Those webview screens get none of the free glass. Only the truly native parts around them, like the tab bar, do. So "we have a native app, let's just switch the free glass on" quietly fails on the exact screens people spend the most time reading. If you want glass there, you're back to hand-building it at full web cost, performance tax and all. Which, going by everything I said above, usually means don't: treat those screens like the web, because that's what they are.

Take the free glass ONLY where it's actually free. Build it by hand ONLY where the look actually pays its rent.

If you're building it anyway, here's the map

I'm not the only one who's gone down this road, and the web recreations sort cleanly into three tiers. The tiers line up exactly with cost: the more realistic the glass, the more it costs to run.

Pure CSS , the cheapest, but really just frost with no true bending of what’s behind it: Kevin Bism’s pure-CSS recreation and FreeFrontend’s gallery.
SVG displacement , the real iOS-26 refraction, and where the render cost starts: Kube’s CSS + SVG writeup for the how-to, nikdelvin/liquid-glass is the one I actually adopted and ported, and rdev/liquid-glass-react is one of the most popular React drop-ins if you’d rather install than hand-roll.
WebGL / shaders , the most convincing and the most expensive: liquid-glass-studio runs the full effect (refraction, plus the faint rainbow split at the edges) on the GPU.

One caveat quietly undercuts the whole realistic end of that list: the SVG-displacement refraction only actually renders in Chrome and other Chromium browsers. In Safari and Firefox, all that work falls back to a plain blur, so a big chunk of your visitors never even see the effect you paid to build. One more reason the web version is a worse deal than it looks.

Off the web, it flips, but only on Apple’s own turf. On iOS there are ready-made wrappers that hand you the real system effect: callstack/liquid-glass for React Native, plus native options for Expo and Flutter. Those genuinely wrap Apple’s effect, which is the whole point: on the platform, it’s basically free. Android is the catch, there’s no system Liquid Glass there to wrap, so the Android libraries reimplement the look from scratch, the same tax as the web. Free where Apple hands it to you, rented everywhere else.

I still did it, for my personal site, where the look basically IS my product. Eyes open, all costs accepted. But I paid twice to build the exact thing Apple is now handing users a slider to dial down, which definitely irks me in a weird way.

We’re not building an asset that will appreciate here. We're renting the one part of the look Apple just made optional.

Subscribe to access my free Claude Code toolkit.

What's the last visual effect that cost YOU a few reverts and a couple hours of your life before it finally stuck? Hit reply, y'all, I read every single one.

🧛

When Claude starts hallucinating, kill the session

Alex Tong — Wed, 01 Jul 2026 13:00:00 +0000

🤌 I was 45 minutes into a Claude Code session when Claude just — started making stuff up.

Default values I never asked for. Constraints I'd set an hour earlier? Completely ignored. Like talking to someone who totally forgot the entire conversation.

So I did what felt natural. I started correcting it in the session. More instructions. More constraints. Spelling things out AGAIN from scratch.

This made everything insanely worse.

Here's the thing nobody tells you about context windows — every correction you make goes into the same context window that's already broken.

Think of your context window like SpongeBob. When he's fresh, he absorbs everything perfectly. But once he's soaked in dirty water — failed attempts, stale instructions, frustrated corrections — squeezing him harder doesn't clean him. You're just pushing the same dirty water around.

At that point your context window is basically SpongeBob rolling around in the mud singing "I'm a dirty boy."

It's a death spiral. And most people don't realize they're in one until they've burned 30 minutes arguing with an AI that stopped listening 20 minutes ago.

This is even more important now with Claude's usage limits. Every correction that makes things worse is burning through your session cap faster — and once you're out, you're out.

So here's a hard rule — stop adding once you notice the session has gone off course. Start terminating.

/clear wipes your conversation history but keeps the project context. Or just open a brand new terminal window entirely. Throw dirty SpongeBob away and grab a fresh sparkly clean one.

Claude will immediately go back to being the brilliant product that it is.

I do this like — a hundred times a day. The moment something starts to feel off, I don't investigate. I don't argue. I just end the session and start over. If I really need context from the old session, I'll ask Claude to summarize it and copy paste the important parts into the new one after reviewing.

Running /compact when things have already gone wrong is usually not the move — you're basically just squeezing a dirty sponge and re-dipping it in dirty water. You freed up space but the residue of bad context is still baked in.

Fresh sessions will produce better code in 3 minutes than 30 minutes of arguing will.

Stop squeezing dirty SpongeBob. Grab a fresh one. 🧛

Related: You're Wasting Your Best Engineering Skill → — the longer take on curating context strategically before Claude starts hallucinating in the first place.

Don't let Claude grade its own homework

Alex Tong — Tue, 30 Jun 2026 13:00:00 +0000

Most teams think of AI code review as something that happens after a PR is opened.

That's too late.

The Claude Code team at Anthropic does something I think more teams should straight up steal:

Claudey A (my pet name for Claude) writes the plan.
Claudey B reviews it as a "staff engineer" — skeptical, looking for edge cases, questioning assumptions.

Two agents. Different roles. The writer doesn't review its own work.

Think about why this matters. When you let the same agent that wrote the code also validate it, you're literally asking the student to grade their own test. Of course it looks correct — it was designed to look correct.

📝 The key insight that changed how I work: When it's time to review, I kill my session and start a brand new one — fresh context window, zero contamination from the implementation. It's like getting a second opinion from a completely different engineer. Issues that used to show up days later in PR review now get caught before a PR even exists.

Layer it: AI review during dev. AI review at the PR level via CI. Humans for judgment calls.

Don't let the agent grade its own homework, unless you're spidey. 🕷️

Related: Stop Reading Every Line of Code → — the full essay on rethinking code review for the AI era.