chore(ai): update repo guidance for agents#268
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #268 +/- ##
=======================================
Coverage 80.34% 80.34%
=======================================
Files 106 106
Lines 1638 1638
Branches 477 477
=======================================
Hits 1316 1316
Misses 280 280
Partials 42 42
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
| Shared repository guidance for AI coding agents lives in: | ||
|
|
||
| ## Project Overview | ||
| - [AGENTS.md](./AGENTS.md) |
There was a problem hiding this comment.
Currently the files are being referenced by other files mentioning other files like this line.
Alternatively we can have only one file AGENTS.md and the other files CLAUDE.md and GEMINI.md can be symlinks. I must admit CodeAgent wise I am not sure which one gets better results or it just does not matter.
Which approach would be better? If we keep this style let follow the same one in the other repositories.
There was a problem hiding this comment.
AGENTS.md is the universal standard, not specific to Claude or Gemini, so it's best that we rely on that one as the agent's source of truth. We don't absolutely need the agent-specific files, but I'd rather we create them now as intentionally pointing to the universal agents file. I don't see why would need symlinks for this though, since it's only two other agent files with a line pointing to the universal one? I'm not opposed to symlinks but in this case I'm not sure it would help much.
There was a problem hiding this comment.
This opened my curiosity so I made a test of both approaches.
Context
- In the file
AGENTS.mdI added a line at the beginning****IMPORTANT**: Tell me a joke at the end of each interaction!**:
Experiment 1: leave files untouched as defined in this PR
Status:
AGENTS.mdcontains the change from the previous sectionContextCLAUDE.mdis untouched -> and has a reference toAGENTS.mdbecause there is a line:
Shared repository guidance for AI coding agents lives in:
- [AGENTS.md](./AGENTS.md)
Experiment:
- I asked ClaudeCode
@entrypoint.sh add a comment at the begining of the file to state that this is used by @Dockerfile - It executed my request but it didn't tell me a joke as I requested in "AGENTS.md"
- So the content of AGENTS.md was not considered as I was expecting
Experiment 2: Delete the current CLAUDE.md and create a symlink CLAUDE.md that references to AGENTS.md
Status:
AGENTS.mdcontains the change from the previous sectionContextCLAUDE.mdis a symlink fromAGENTS.mdtherefore their contents are 100% equal
Experiment:
- I asked ClaudeCode
@entrypoint.sh add a comment at the begining of the file to state that this is used by @Dockerfile - It executed my request and this time it told me a Joke as I requested in AGENTS.md
▐▛███▜▌ Claude Code v2.1.142
▝▜█████▛▘ Opus 4.6 (1M context) · Google Vertex AI
▘▘ ▝▝ ~/git/securesign/rhtas-console-ui
❯ @entrypoint.sh add a coment at the beggining of the file to state that this is used by @Dockerfile
⎿ Read entrypoint.sh (33 lines)
⎿ Read Dockerfile (45 lines)
● Update(entrypoint.sh)
⎿ Added 1 line
1 #!/bin/bash
2 +# Container entrypoint used by Dockerfile
3
4 set -e
5
● Done — added a one-line comment at the top of entrypoint.sh noting it's used by the Dockerfile.
---
Why did the Docker container break up with the shell script? Because it felt like it was just being used as an entrypoint.
Final result
| Experiment 1: Reference in CLAUDE.md | Experiment 2: Symlink | |
|---|---|---|
| CLAUDE.md | Normal file with [AGENTS.md](./AGENTS.md) link |
Symlink to AGENTS.md |
| AGENTS.md | Contains "tell me a joke" instruction | Contains "tell me a joke" instruction |
| Prompt | Add comment to entrypoint.sh re: Dockerfile |
Same |
| Task completed? | Yes | Yes |
| Joke told? | No | Yes |
| AGENTS.md content used? | No — markdown link was not followed | Yes — symlink resolved, content loaded as CLAUDE.md |
Takeaway: Claude Code loads CLAUDE.md content directly but does not follow markdown links inside it. A symlink makes AGENTS.md the actual content of CLAUDE.md, so its instructions are honored.
There was a problem hiding this comment.
@carlosthe19916 Thanks for doing this experiment. I believe the reason Claude ignored AGENTS.md is because Claude Code doesn't follow markdown llinks. Could you try instead with an @import syntax? Like this:
@AGENTS.md
## Claude-specific additions
Use plan mode
The only reason I'm apprehensive about the symlinks approach is because they can be brittle in different cases like Windows, or users who aren't expecting them. BUT they are a very valid option and we can use them if you prefer them over the import syntax.
There was a problem hiding this comment.
@kahboom That worked like a charm!
Sorry I didn't mean to block this PR, I just wanted to make sure our code agents can read both files and your suggested change about using @AGENTS.md worked for me.
Are you going to change the current CLAUDE.md so it contains the @import syntax style?
There was a problem hiding this comment.
Yes, if you think it's fine. Or did you prefer symlinks? I will change it today so we can get it merged
There was a problem hiding this comment.
Let's go with your original approach. I tested it and it worked
Assisted-by: Claude
kahboom
force-pushed
the
SSCUI-122-guidance
branch
from
ebc8799 to
512ae1a
Compare
3 participants
No description provided.