Infra: Agents.md for contributors using AI - #3826
Conversation
kaitlynmichael
added
infrastructure
AI-friendliness
🧠 Redis MemoryFound 5 related items from repository history (5 new this commit):
Memory updated at 462f9ae |
mich-elle-luna
left a comment
mich-elle-luna
left a comment
There was a problem hiding this comment.
Thank you! This feels a lot safer to implement because it is per directory and is more like guardrails on what not to change or break. Also, it allows owners of other directories to follow this or customized accordingly. Much simpler for new contributors as well because they don't have to do anything. And the main agents.md is already agreed by all of us I believe.
| ## Site mechanics | ||
|
|
||
| - **Cross-references use the relref shortcode**, not markdown paths: | ||
| `{{< relref "/operate/rs/clusters/new-cluster-setup" >}}`. A broken relref fails the |
There was a problem hiding this comment.
is this true? I think we can ship with broken relrefs / they do not break a build, but I may be wrong
There was a problem hiding this comment.
Broken relrefs issue a warning at build time, but they need to be fixed. Broken relrefs lead to one of two places: (1) the top of the page on which the relref is used; (2) a 404 page. It's important that these are addressed, which is why I've been such a p.i.t.a. about it, driving other team members insane. 🙃
There was a problem hiding this comment.
Do we want to soften this language? @dwdougherty @mich-elle-luna
There was a problem hiding this comment.
I think it needs to state clearly that relref-related link warnings should be fixed before pushing upstream.
dwdougherty
left a comment
dwdougherty
left a comment
There was a problem hiding this comment.
Approved. I'll have to create files for the other "develop" sections and the "commands" section.
@dwdougherty my experience is that your claude.local.md file is a great starting place. You just need to trim out stuff that's personal preference or irrelevant to contributors. |
What |
No worries, Claude will know. I can create a prompt for you if you'd like. |
3 participants
one
AGENTS.mdper product directory, recording the conventions eachproduct's pages already follow — so that when a contributor drafts with an agent, the
agent already knows them.
What a contributor gets
Someone drafting a page with Claude Code, Codex, or Cursor gets a first draft that
already uses our terminology, our style, and the disclosure rules for the product they're
writing about. The conventions an agent would otherwise guess at are simply there.
That means:
needing the same handful of corrections every time.
already answers.
can't be published, and the agent now has them in front of it rather than inferring
from a neighboring product's pages.
Quality goes up at the point where the content is created, which is the cheapest place
for it to go up.
Why several small files rather than one
Two reasons, and they point the same way.
Agents do better with smaller files. A context file is loaded into the model's
working memory at the start of a session, sharing room with the task itself. Claude
Code's own guidance is explicit:
Every file here is inside that. For an AI reader, relevance density beats
completeness — the reverse of what makes a human guide good, where answering everything
in one place is the point.
Per-directory files get this for free. A subdirectory's file loads when the agent reads
files in that directory, so a session in the Redis Software pages gets Redis Software
conventions and nothing else.
Each product is genuinely different. Not stylistically — substantively. The rules
that matter most are the ones that only make sense inside one directory:
correct in prose and
CRDBis correct in the REST API reference titles, because the APIsurface is named
crdb. Both are right. Nothing in the pages tells an agent where theline falls.
content/develop/legitimately links to source code, because the implementation ispublic and part of the product. Feature Form lives in that same directory and its
source is private, so the general rule is backwards for those pages.
an agent that follows the majority usage gets it wrong.
A single repo-wide file would have to pick one rule per topic and be wrong for somebody.
Per-product files let each rule be stated correctly, with its exception, where it applies.
Zero extra effort
Nobody has to do anything differently. No install, no new step, no checklist.
The three tools contributors already use read these files automatically — this is the
documented pattern in each, not a workaround we'd be inventing. Codex walks from the git
root down and concatenates every
AGENTS.mdit finds. Cursor supports nested filescombined with their parents. Claude Code has the same hierarchical model under the
filename
CLAUDE.md, which is why each directory also gets a one-lineCLAUDE.mdimporting the
AGENTS.mdbeside it — also documented, down to the syntax:Done right, contributors never need to know they're there. They draft the way they
already draft, and what comes back needs less correction. That's the measure of success —
not adoption, and not anyone reading anything. There's nothing to launch and nothing to
learn.
Writing for AI readers is already practice here, too:
redis/docscommits 29agent-facing files today, including
AGENT.md,AI_AGENT_DEVELOPER_GUIDE.md, eight under.agents/, and nineteen underfor-ais-only/.What's there
Two tiers, both small.
AGENTS.md— universal guidance only: Google style,relrefcross-references, frontmatter shape, editing scope. Nothing product-specific, so it
makes no claim about any product's terminology or what it may publish.
AGENTS.mdper product directory — terminology and disclosure, loaded only bysessions editing those pages.
That division is also the rule for where a new convention goes: as soon as it needs a
product-specific caveat, it belongs in the product file. Which is what keeps root small.
content/operate/kubernetes/content/operate/rs/content/develop/ai/featureform/content/operate/featureform/Every rule states its exception
The rules in these files carry their carve-outs inline. That's the most important
convention in them, and it's the one that decides whether they help or hurt.
A rule without its exception doesn't make an agent cautious. It makes it thorough. A
person reading a style guide hedges — they hit a surface where the rule looks wrong and
they ask, or they leave it. An agent doesn't hedge. It applies the rule everywhere it
pattern-matches, uniformly, in one pass, and every edit looks deliberate in review. So a
rule that's correct 90% of the time doesn't produce 10% mistakes; it produces a confident
sweep that someone has to catch line by line.
Three rules from these files show the shapes that failure takes:
is our convention. Stated flatly, it strips "support for TLS 1.1 will be removed in a
future release" — a notice customers depend on for migration lead time. The rule has to
say that losses are in and gains are out, or it removes the wrong half.
for Kubernetes" is correct, and applying it to
RedisEnterpriseClusterbreaks an APIcontract. Same for a literal
bdbin a request path, orcrdb-cli. The prose rule andthe code rule are different rules.
section wins until it's deliberately changed. In the Kubernetes pages the legacy product
name is the consistent usage, so following it is exactly wrong. That file says so
explicitly and overrides the general rule for that term.
None of these are edge cases an agent would stumble into rarely. They're the highest-
traffic terms in their directories, which is why the exceptions are the most valuable
lines in the files.
It's also why this isn't just the style guide pasted into the repo. A guide written for
people can leave the exceptions implicit, because people supply the judgment. These files
have to state them, because the reader won't.
They never reach the site
Hugo renders any
.mdundercontent/as a page, so the files are excluded inconfig.tomlalongside the existing build-output exclusions. Verified on the branch: afull build produces 5,940 pages and none of them is an
AGENTS.mdorCLAUDE.md.Nothing here is a new decision
Every rule in these files is a convention our pages already follow — the style guide and
our established terminology, restated where a drafting tool can read them.
So if a rule is wrong, missing, or out of date, change it in the PR where you hit it. No
process, no gate, and nothing to ask anyone's permission for.
What I'm asking for
A read on one PR. You don't need to read all ten files — start with the Kubernetes
one. It's short, and it's the best test of the shape, since the legacy product name is
still the majority usage in that directory. If the shape is right, the rest follow it.
Flag anything you'd want different and I'll fold it in.
Note
Low Risk
Contributor-only convention files and Hugo ignore rules; no changes to published documentation or runtime behavior.
Overview
Adds layered
AGENTS.mdfiles so coding agents inherit Redis docs house style and product-specific rules when drafting in a directory, without contributors installing anything new.A repo-root
AGENTS.mdcovers universal style,relrefusage, frontmatter habits, editing scope, and when to flag instead of fix. Per-product files undercontent/operate/kubernetes/,content/operate/rs/, and Feature Form (content/develop/ai/featureform/plus an identical copy incontent/operate/featureform/) add terminology, disclosure, and carve-outs (for example mid-rebrand naming, CRDB vs Active-Active, private source, no roadmap promises).Each of those directories also gets a one-line
CLAUDE.mdthat imports the localAGENTS.mdso Claude Code and other tools share the same instructions.config.tomlextendsignoreFilessoAGENTS.md,CLAUDE.md, andCLAUDE.local.mdundercontent/are not published as Hugo pages.Reviewed by Cursor Bugbot for commit 462f9ae. Bugbot is set up for automated code reviews on this repo. Configure here.