Conversation
…to bbuild on top of Agentic AI Foundation standard
|
This document seems to be more about how we view writing a good AGENTS.md file, versus being one itself that should be applied org wide (eg via .github). If that's the case, I think we want to move this into project convention documentation, and then have the appropriate in-repo AGENTS.md files. As an in-repo example from Apache Airflow: https://github.com/apache/airflow/blob/main/AGENTS.md |
|
|
||
| ### File setup | ||
| - Place an `AGENTS.md` at the repo root alongside `README.md`. | ||
| - Create symlinks for tools that use their own filenames: `ln -s AGENTS.md CLAUDE.md` and `ln -s AGENTS.md .github/copilot-instructions.md`. |
There was a problem hiding this comment.
nice, this is something i was going to suggest though wasn't sure if it worked or not. looks like it does!!
There was a problem hiding this comment.
symlinks can be challenging Git + symlink behavior varies by configuration and OS - so using them in this way can lead to inconsistent experiences for developers.
That said - I think this is a reasonable approach for now and we can always look at alternatives if it becomes a problem in future.
There was a problem hiding this comment.
This has worked for me. If there are better methods, please let me know and I can update.
| ### File setup | ||
| - Place an `AGENTS.md` at the repo root alongside `README.md`. | ||
| - Create symlinks for tools that use their own filenames: `ln -s AGENTS.md CLAUDE.md` and `ln -s AGENTS.md .github/copilot-instructions.md`. | ||
| - For monorepos, place additional `AGENTS.md` files in subdirectories. Agents read the nearest file in the directory tree; the closest one takes precedence. |
There was a problem hiding this comment.
i assume you should also remember to symlink these files as well to the appropriate spot
Agree and feels like we need both: a functional doc which is default baseline and symlinkable, and the philosophy / design doc guiding future mutations to the functional and customizations where not symlinking. |
|
|
||
| ### File setup | ||
| - Place an `AGENTS.md` at the repo root alongside `README.md`. | ||
| - Create symlinks for tools that use their own filenames: `ln -s AGENTS.md CLAUDE.md` and `ln -s AGENTS.md .github/copilot-instructions.md`. |
There was a problem hiding this comment.
symlinks can be challenging Git + symlink behavior varies by configuration and OS - so using them in this way can lead to inconsistent experiences for developers.
That said - I think this is a reasonable approach for now and we can always look at alternatives if it becomes a problem in future.
| | CD | Release process, semver tagging convention, environments. What agents must not touch (e.g. production deploy scripts, release signing) | P1 | | ||
| | Security | No secrets in code, no disabling lint rules, check new packages for CVEs. Link to `SECURITY.md` if present | P0 | | ||
| | Dependencies | Rules for adding new deps (license, review process). What requires human approval | P1 | | ||
|
|
There was a problem hiding this comment.
Suggest adding some guidance on things not to do like:
- Don’t change license headers / legal text without human approval
- Don’t modify release/signing/deploy workflows unless explicitly asked
- Don’t add new dependencies without confirming license
Agreed. To anne's point, we do need agents.md for Coop and Osprey. They are diff codebases, diff languages etc. Once we agree on this, I am happy to write the AGENTS.md file for each. I would also be very keen to see if folks have something that works really well for them esp given that I am not a node.js or Typescript expert. |
5 participants
No description provided.