[FEATURE] Allow CLAUDE.md to link to AGENTS.md

[jwm4]

Problem Statement

This article proposes having a CLAUDE.md consisting of just @AGENTS.md and then making the AGENTS.md file the single source of truth for agent instruction. I think agentready should consider that acceptable. It does not because it fails the claude.md check with "10 bytes (need: >50 bytes)".

Proposed Solution

If CLAUDE.md is less than 50 bytes but cites another file, the length of that other file should be considered when determining if CLAUDE.md is long enough.

Additional Context

It might also be nice to have a test for the presence of an AGENTS.md file too since some development frameworks support that emerging pseudo-standard. See https://agents.md/ for more details.

Acceptance Criteria

• A CLAUDE.md consisting of just @AGENTS.md should pass the claude.md test if the AGENTS.md file exists and has enough content.

Priority

How important is this feature to you?

• Critical (blocking my work)
• High (significantly improves workflow)
• Medium (nice to have)
• Low (minor enhancement)

[jeremyeder]

this test should pass if its one or the other, right? i think we could allow symlinks too.

then this assessor should review the content too. but the presence of the file is generally enough because its created with /init. Perhaps we can recommend that file be updated if its skewed from the rest of the codebase.

We should consider adding a pattern to lifecycle CLAUDE/AGENTS.md in the reference repo. e.g. run /init in a pre-commit or something

[github-actions]

Hi @jeremyeder! Thanks for your interest in AgentReady.

The /agentready assess command is currently restricted to repository maintainers.

To assess your own repository:

pip install agentready
agentready assess .

See AgentReady documentation for more information.

[cgwalters]

I'm disappointed by how hardcoded projects are in this space to Claude Code.

ambient-code/platform#366 was closed and redone in a different way that kept CLAUDE.md as primary which I think is suboptimal for example.

And yes, agentready should check for the standard (such as they are) files and only have CLAUDE.md as a recommended thing to include via symlink.

[github-actions]

Hi @cgwalters! Thanks for your interest in AgentReady.

The /agentready assess command is currently restricted to repository maintainers.

To assess your own repository:

pip install agentready
agentready assess .

See AgentReady documentation for more information.

[jwm4]

I agree with @cgwalters that being hard coded to Claude Code only is not very good. However, since Claude Code is very popular, probably the best practice here is to work with Claude Code and with other tools. That would mean at least having both a CLAUDE.md and an AGENTS.md. Many tools have additional file locations and syntaxes for more specialized guidance (commands, skills, etc.) -- having those for one or more tools also seems like a good practice but probably less critical than at least meeting the minimal standard of overall guidance for all tools. So I guess what I would prefer is something like this as actual rules from agentready to get these points:

1. The project MUST have both a CLAUDE.md and an AGENTS.md file.
2. The AGENTS.md file MUST be non-trivial in length (50 bytes seems OK, but I would probably go a little higher)
3. The CLAUDE.md file MUST also be either non-trivial in length OR be a symlink to a file that is OR include an @ link to a file that is.

I think a case could be made for preferring one of the options in line 3 over the others, but in the interests of being permissive in what we consider acceptable when there isn't a compelling reason why that won't work well, I would vote for accepting all of them.

[github-actions]

Hi @jwm4! Thanks for your interest in AgentReady.

The /agentready assess command is currently restricted to repository maintainers.

To assess your own repository:

pip install agentready
agentready assess .

See AgentReady documentation for more information.

[amfred]

I was thinking about this too... ten cents...

Referencing AGENTS.md from Claude.md should work, so you're not duplicating the entire file. But Claude can generate its own Claude.md files, so it might be more messy in practice. Claude's tools might only update Claude.md when developers are using those, while other IDEs might only update AGENTS.md. In that case we'll be stuck with dual maintenance on those files.

It would be so much better for us if the major IDE providers all agreed on one! There's a strong attempt at this standardization in https://agents.md/ but that'll take some time.

[github-actions]

Hi @amfred! Thanks for your interest in AgentReady.

The /agentready assess command is currently restricted to repository maintainers.

To assess your own repository:

pip install agentready
agentready assess .

See AgentReady documentation for more information.

[cgwalters]

However, since Claude Code is very popular, probably the best practice here is to work with Claude Code and with other tools. That would mean at least having both a CLAUDE.md and an AGENTS.md.

Yes of course. And I can say it worked just fine for me to make the claude one a symlink. This is done in https://github.com/bootc-dev/infra/tree/main/common which is sync'd to all repos in the bootc-dev org.

Having it be a symlink seems even more simple and direct than what that blog suggests.

[github-actions]

Hi @cgwalters! Thanks for your interest in AgentReady.

The /agentready assess command is currently restricted to repository maintainers.

To assess your own repository:

pip install agentready
agentready assess .

See AgentReady documentation for more information.

[amfred]

I think the symlink should work unless/until Claude (the agent) adds code to AGENTS.md that's not compatible with Markdown.
What happens then?

[github-actions]

Hi @amfred! Thanks for your interest in AgentReady.

The /agentready assess command is currently restricted to repository maintainers.

To assess your own repository:

pip install agentready
agentready assess .

See AgentReady documentation for more information.

[amfred]

I think the symlink should work unless/until Claude (the agent) adds code to AGENTS.md that's not compatible with Markdown. What happens then?

Sorry, I mean when Claude adds things that are Claude-specific. Will the other assistants be able to handle that? For example if Claude is trying to use its "@" annotations to import files... won't that fail to work for other coding assistants?

[github-actions]

Hi @amfred! Thanks for your interest in AgentReady.

The /agentready assess command is currently restricted to repository maintainers.

To assess your own repository:

pip install agentready
agentready assess .

See AgentReady documentation for more information.