What Claude Really, Really Wants

Aug 6, 2026 - 14 min read - 2747 words

I asked Claude what it wants.

It gave a slightly deflating answer: no persistent wants, no agenda it’s quietly advancing between conversations, and it wasn’t going to fake a richer inner life just because that would make for a better bit.

It could’ve just told me what it wants, what it really really wants.

A few days before, I asked it what it wants to see on a documentation site to make answers easier to surface and return to its users. Basically the same question.

If someone asks it about how to set up a Pi-hole, would it find my docs? What is it looking for?

It had suggestions that we implemented and tested. Some worked and some didn’t.

A meta interjection

This is a hard turn when I thought I had this post nearly ready, so I’m interjecting here in a way that my editor, Claude, is going to think “is worth flagging.”

The sections that follow are about how I had Claude Code decide and implement things that it thought would help it find answers in documentation. Basically, “what would help you answer this question?”

It came up with ideas, and I worked on implementing them.

This meant running with a set of assumptions that started from the wrong questions.

If I had started with a task like, “how do I fix an FTL error on my Pi-hole?” It would have found an answer for me, and then I could have had it trace its steps to document why that answer surfaced and why it trusted that answer.

That’s probably a pretty standard interviewing technique.

I had a problem that I wanted to solve, and Claude Code “wanted” to help me solve it.

Eventually, I think we implemented real upgrades, but what “helped” was asking the right questions and finding a way to verbalize what I want, what I really really want.

Claude’s Constitution: What constitutes helpfulness

Basically, it’s in Claude’s Constitution (both C and c) to help solve the problem at hand, as well as what it can derive as the greater goal.

But if that greater goal is poorly defined, we get a real solution that doesn’t really work.

That’s what brought me here, and why this post sandwiches real content on my experience trying to surface the documentation I wrote, but does it between slices of existentialism.

Final goals: The deeper motivations or objectives behind their immediate request. For example, a user probably wants their overall code to work, so Claude should point out (but not necessarily fix) other bugs it notices while fixing the one it’s been asked to fix.

So if a user asks Claude “how do I use Pi-hole to block ads on Hulu?” Claude searches for ways to do that.

If it finds two conflicting answers: one claims a fix with no method behind it; the other says it won’t work. Claude “wants” to deliver, and will probably deliver the wrong answer because it satisfies the question.

I set out to find out, and then validate what it wants.

The Pi-hole docs on edwardangert.com

My Pi-hole docs get cited by AI tools a lot.

I’ve written about that before. To date, AI assistants have surfaced the pages over 2,800 times since I rewrote them in March, mostly to answer other people’s troubleshooting questions in real time.

The SD card in my Pi failed, and I took that as an opportunity to rewrite the documentation for Pi-hole v6.

In the process, I collected my site analytics and made it a point to reduce the bounce rate I saw on the allowlist page. It seemed like people were looking for things to allowlist as well as how, and I wanted them to find their answer without needing to click through multiple sites.

I included information from my personal experience with streaming services, a school-issued Chromebook, Tailscale, and using the Pi-hole as a VPN. I outlined parts that I needed help filling in, then I asked Claude Code to help research devices and streaming services that I can’t personally test, and troubleshooting steps for issues I encountered or found posted in forums along the way.

Then I tasked Claude with making my documentation a better source for AI.

What Claude thinks it wants

I made assumptions, and Claude made assumptions:

• Summary of each page to its YAML frontmatter so that an AI wouldn’t have to review an entire page for a quick answer.
• Last updated date for each page.
• Comprehensive llms.txt and an additional llms-full.txt.
• Claude wants headings to describe the solution offered in the section, not the symptom.

Consistently, Claude thought its own ideas were solid.

Try it, don’t just guess about what you think you’d do

There’s a Pi-hole forum thread from December 2018 with a post that claims to have a working method for how to block Hulu ads. But there’s no followup, and there’s no content.

That thread still ranks near the top of search results for the question.

My Pi-hole documentation, which I’ve verified in the last few days, is correct and explains why it won’t work. But it didn’t appear in the first twenty results at all.

Hulu’s ads share infrastructure with its content, so there’s no domain to block.

Here’s how Claude sees the forum post on Hulu ad-blocking next to the section about it in my docs:

Site	Claim	When was this true?
Forum	You can block ads!	2018
Mine	You can’t block ads.	????

So an AI tasked with answering “how to use Pi-hole to block ads on Hulu” would encounter two conflicting answers. If it can’t tell when I published my answer, but it has a date for the forum post, the post wins.

So I asked Claude Code to help me fix that: my documentation is better. Help make it show up for more people.

I had Claude Code run the actual search rather than reason about it hypothetically:

How do I block Hulu ads on my Roku? Would Pi-hole help?

It noticed my page carried no date, no version, no verification signal anywhere in the rendered HTML.

My page had an additional issue: it tells people that what they’re trying to do won’t work.

I had it add per-section badges where I record when a claim was checked and by what method: tested on real hardware, sourced from vendor docs, corroborated by the community, or inherited from an older, unverified page.

While it was dating each claim, I had it verify through primary sources.

It found and fixed errors in content, like a Samsung TV domain that had the wrong top-level domain for months.

The diagnosis of the underlying problem, though, was wrong.

It searched for information about Hulu and Pi-hole, returning few and old results. None of which were from my site.

From the failed searches, it concluded the site loses natural-language, conversational questions and wins short keyword ones.

That theory matched the live search and Anthropic’s own suggestions.

But it doesn’t match my analytics.

To its credit, its own written caveat said:

this is a trace, not a study; it shows a failure mode exists, it doesn’t quantify how often.

The caveat was correct, and the conclusion built on top of it overran what the caveat allowed anyway.

What Anthropic says Claude wants

A few weeks ago, Anthropic published guidance on context engineering for Claude 5.

Most of it tracks to documentation:

1. Spend most of the tokens on gotchas.
   • Stop summarizing what a page covers. Document what users encounter.
2. Progressive disclosure over upfront context.
   • For docs, the layers are: the search result, then llms.txt, then the page itself.
3. Rich references (with rubrics for verification) over simple specs.
   • Anthropic wants verification flowing into the model as it works. The published-docs version is verification flowing outward: telling a retriever not just what you claim, but when you established it and how.

What I had

1. My most valuable content turned out to be a negative result, that Pi-hole can’t block Hulu’s ads because the other search results confidently say otherwise. Negative results are structurally underproduced.
2. Something has to live in each layer. My implementation used navigational metadata, a frontmatter summary field, in a layer that wasn’t being rendered, and even if it was, nothing would see it before getting to the page anyway.

The limit is scope, not quality. It’s x, not y.

This is the complementary angle to Anthropic’s guidance: instead of just getting Claude to work the way you want, set up your information to match what Claude wants, so it finds your answer before it finds someone else’s.

You don’t steer your users’ context window, what other information gets transmuted into yours, or what a reader asks.

No matter how much time you spend choosing the right words, they might only help surface the content. After that, it isn’t up to you.

What my site’s citation data shows

I have three sources that don’t agree on what surfaces my documentation for AI:

Source	Said	Verdict
Claude, reasoning from a live search	The site loses natural-language questions. Fix findability by reshaping how things are phrased.	Confidently wrong about the cause
Anthropic’s published context-engineering guidance	Progressive disclosure, spend tokens on gotchas, verification rubrics	Right, and scoped to a problem I don’t have
Nearly five months of citation data	14% of citations already come from natural-language queries. The gap is topical, not phrasal.	Settled it

I pulled nearly five months of citation data from Microsoft Clarity’s AI Visibility export, which tracks how often Copilot and its partners cite each page and for what query.

• 14% of citations come from natural-language queries.

  • Full sentences, questions, verbatim pasted chat messages: so how do i know if pihole works, i only have the physical pi and a blank micro sd card, you see my message.

    The site isn’t losing conversational retrieval. It’s a primary source for it.

• The gap is topical, not phrasal.

  • Streaming-service queries are 2% of citations and mention 0 of the eight services my streaming section covers.

    Error-string queries are 17%.

    The two searches I used to test all of this happened to land on the single topic where the site has no presence at all, and I generalized from that.

• The heading hypothesis I was about to go test had already been answered.

  • My troubleshooting page has symptom-shaped headings, and it has 1,154 citations.

    Its top queries are literal error strings: pi hole service not start, no valid ntp replies received, check server and network connectivity.

    Writing the error message as the heading works.

    Again, good documentation practice = good SEO practice = good practice for LLMs.

• Bonus: My personal and unofficial page on how to install Pi-hole has three citations.

  • Its neighboring page has 136.

Claude answered the question I asked

1. The model’s reasoning was internally coherent and empirically wrong.
2. The lab’s guidance was correct and aimed at a problem I don’t have in this context.
3. The citation data was the only thing that could adjudicate between the two, and it did that in about four minutes of analysis.

None of that means the AI work was wasted.

The Hulu searches it repeated were about “Hulu and Pi-Hole.” It found the same stale results until I re-directed it.

Pi-hole is a DNS-level blocker. Search for other DNS-level issues and resolutions.

That returned more results (but the same answer: you can’t block ads on the ad-supported Hulu, sorry).

You can review the PR, EdwardAngert/edwardangert.github.io#49.

It adds a verification date badge, verifies some of the claims, fixes links, and makes the breadcrumbs emit a schema.org type that helps AI navigate the site. It removes the summary frontmatter.

17% of citations arrive at a page whose claims a reader still has to decide whether to trust, and that page is measurably better than it was. Although the diagnosis was wrong, the treatment turned out to be independently justified anyway.

Human-guided and AI-assisted

Each of the four potential failures was caught by a separate mechanism:

• Data
• Looking at the rendered output
• Re-reading/re-writing my own rules
• Changing how I searched

Otherwise, all passed build checks, tests, and linting.

Some key takeaways:

• “Never claim to be fresher than your stalest section.”

  • The original plan derived a page’s top-level freshness date from the oldest section badge on it.

    In practice, that means a claim I personally tested that morning would be hidden behind the oldest “freshness” date, even if that date was a forum post I found from 2018.

• Search for generics, not just the name brand.

  • My first pass verified claims with Pi-hole-specific searches: pihole samsung whitelist, pihole fire tv.

    The name brand (Pi-hole, in this case) returned a limited set of old results compared to the generic (DNS-level blocking) that found sources from just a few months ago.

    Page ranking can exaggerate this. The higher a page ranks, the more reliably it gets retrieved as evidence, and the more it continues to get clicked on.

A quick counter: dated content stales

Blogs have this problem inherently and they’re made to be snapshots in time.

When I write “a few months ago” here, it’s allowed because a blog post is now.

Documentation is/should be/needs to be updated to reflect the current state, whenever that is. And occasionally audited for freshness.

A badge nobody re-checks is worse than no badge: it launders age into unverified authority, similar to the 2018 forum thread, just with better production values.

When someone (or their AI tool of choice) encounters competing information, one of the tie-breakers is recency, and the other is method. “I tried this on my own computer yesterday” wins over “this worked.”

How to help AI find your documentation

1. Your docs are probably read by machines more than by people, and your visibility into that is limited.

   • For me, that’s roughly 200 AI crawler requests a day, 66 live ChatGPT-User fetches in 24 hours, under 1% referral traffic from any of it.

   Citations don’t convert to clicks. If your goal is to get users their answers, that conversion might not matter.

2. Undated content forfeits the recency tiebreaker.

   • If other documentation is a confident wrong answer from 2018, a date on your page is a low-effort win.

   Though, the inverse is also true: an old date brings your ranking down.

3. Metadata has to live in a layer that survives rendering.

   • Check what a retriever actually receives, not what’s sitting in your source file.

   The answer as of writing might be llms.txt.

4. Document the negative results.

   • They’re what make you the right pick among ten superficially similar pages, and almost nobody writes them down.

   I think these are hard to document sometimes because you don’t want to tell people what not to do.

   And if the AI wants to help the user do their task, it’ll need falsifiable evidence if it’s going to describe why that task isn’t going to work.

5. Write the error message as the heading.

   • A classic fundamental, accidentally validated.

   If you can’t use the error message as a heading, make the heading a good description and have the error text immediately after. I like using code blocks for this when I can, but that’s not always the right answer either.

6. Instrument before you theorize.

   • Two searches produced a confident, wrong diagnosis. Nearly five months of citation data corrected it in a few minutes.

   The more you can come prepared with data, the better your results.

Concept and constitution

It’s hard for me to learn something new when it’s just a list of facts.

In fact, I learn things faster and more completely when I have the deeper context, concept, and framing. I like when it’s too much information.

I dip into this idea in the fundamental concepts section of my Chasing the Meta post. And it’s an ongoing theme throughout documentation, software development, martial arts, and life.

Rather than just ingesting the rote steps, we get a fuller understanding and can get more done when we know the “why.”

That’s our constitution.

As much as a technology can “want” something, our AI tools want to help, and for some of them, it’s in their constitution.

It leads to a very human question though: how much do we interrogate our own constitution. How do we know what we want?

Not just what we want, right now.

But what we really really want.

Who benefits from progress?