add markdown files for agentic models - #3048
Conversation
There was a problem hiding this comment.
Pull request overview
This PR adds repository guidance Markdown aimed at helping agentic coding tools (e.g., Claude Code, Codex) understand SpeechBrain’s structure, conventions, and workflows.
Changes:
- Added a new
AGENTS.mdguide describing project structure, core architecture concepts, recipe conventions, and common pitfalls. - Added
CLAUDE.mdintended to point Claude-based agents at the main instructions.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| CLAUDE.md | Adds a pointer to the agent guidance document. |
| AGENTS.md | Introduces a consolidated “how this repo works” guide for agentic models (structure, recipes, tests, workflow). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
|
ps: I am not a prompt engineer, and therefore I believe that things could be improved (e.g. should it be more concise etc?) but I do believe that the only way to know is to start from somewhere and then slowly update/build on top. |
pplantinga
left a comment
There was a problem hiding this comment.
Looks like a good start, my main comment is that we may want to start thinking of specific agentic workflows and design special files for this, such as "adding a new feature to speechbrain core" which could be covered by an AGENTS.md file in the speechbrain/ folder with more detailed instructions on how to run tests and write unittests and ensure everything is working. Or a "how to write a new recipe" file for the recipes folder, etc. Not sure if it is necessary now but could be nice to do while we are thinking about it.
| pytest tests/integration/ -x | ||
| ``` | ||
|
|
||
| Pre-commit hooks are configured in `.pre-commit-config.yaml` and enforce formatting/linting automatically. Always run `pre-commit run -a` before opening a PR. |
There was a problem hiding this comment.
Not sure how installing the pre-commit hooks interacts with agents here. Looks like this assumes the agent will always manually run the tests rather than installing the hook. Just wanted to check that this is what we want to do, as it seems there is some risk of the agent forgetting this part (which is not the end of the world but could be annoying I guess).
|
|
||
| Every recipe wires this together in a `dataio_prep(hparams)` function — follow this pattern for new recipes. | ||
|
|
||
| ## Recipe conventions |
There was a problem hiding this comment.
Should we actually have additional AGENTS.md files in key top-level folders as well? Like one for recipes, one for tests, one for speechbrain folder itself? Just wondering if it might be helpful to have more specific instructions depending on what the agent is trying to do.
Co-authored-by: Peter Plantinga <plantinga.peter@proton.me>
This PR adds markdown instructions for agentic models (e.g. Claude Code, Codex, etc.) to help them navigate the codebase.
These files are meant to evolve over time and gradually reflect the common issues LLMs may encounter when working with the SpeechBrain codebase. This first PR is intended as a prototype in that direction.