Add AGENTS.md and CLAUDE.md for AI agent guidance#656
Add AGENTS.md and CLAUDE.md for AI agent guidance#656rtibbles wants to merge 2 commits intolearningequality:mainfrom
Conversation
Tested via TDD methodology against a KPUB file type implementation task — iteratively refined through RED/GREEN/REFACTOR cycles to ensure subagents correctly scope changes to the pipeline and avoid unnecessary File/Node subclass creation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Create a concise, model-agnostic AGENTS.md with commands, critical gotchas, and key architecture for all AI coding agents. Restructure CLAUDE.md to import AGENTS.md via @ reference and extend with Claude-specific architecture details. AGENTS.md was validated through 3 rounds of TDD testing (RED-GREEN- REFACTOR) with Haiku and Sonnet subagents using a KPUB file type implementation task to verify gotcha effectiveness. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
nucleogenesis
left a comment
nucleogenesis
left a comment
There was a problem hiding this comment.
Things read very well overall. I've left a few questions to discuss before approval.
|
|
||
| ## Critical Gotchas | ||
|
|
||
| - **Linting:** Always use `pre-commit run --all-files`. Never run black, flake8, or other tools directly. |
There was a problem hiding this comment.
(maybe-blocking): Never ever ever? Sometimes it might be nice to have an agent have the ability to run specific test files' tests directly without running the full suite (although ricecooker's tests probably run a lot more quickly than Kolibri's).
Would save context to avoid running the whole pre-commit suite on all files to test a single test case too.
There was a problem hiding this comment.
I realize this is in the "linting" section - but I worry this might be taken as "law" to the agent to "Never run black, flake8, or other tools directly."
Could maybe mitigate by explicitly explaining the agent should run single tests when they don't need to run the full suite or something?
| ## Development Notes | ||
|
|
||
| - The pipeline code is the reference architecture — follow its OOP patterns when writing new code. | ||
| - Older code (especially `ricecooker/classes/`) has less test coverage. Take extra care when modifying it. |
There was a problem hiding this comment.
suggestion: What if we also include a requirement to add regression tests when making changes to "older code" (or any existing code when relevant)?
|
|
||
| This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. | ||
|
|
||
| @AGENTS.md |
There was a problem hiding this comment.
suggestion/question: Does this effectively inject the AGENTS.md in this spot in the context?
AGENTS.md reads to me (as a human anyway) as supplementary to the rest of this CLAUDE.md file and could be a little confusing to read first (again, as a human) - not sure how this may or may not impact LLMs though.
2 participants
Summary
Add two documentation files to guide AI coding agents working in this repository:
AGENTS.md— Concise, model-agnostic guidance (36 lines) with commands-first layout, critical gotchas, project overview, and key architecture. Designed to fit in smaller context windows.CLAUDE.md— ImportsAGENTS.mdvia@AGENTS.mdreference and adds Claude Code-specific extensions: detailed pipeline architecture,le_utilsdependency context, and expanded file type implementation guidance.The
AGENTS.mdcontent was validated through 3 rounds of TDD testing (RED-GREEN-REFACTOR) using Haiku and Sonnet subagents with a KPUB file type implementation task. Each round identified common agent mistakes and refined the gotchas to prevent them. Key gotchas that proved effective:classes/modulesle_utilsconstant verification before use (names are non-obvious)tests/pipeline/References
Follows the AGENTS.md / CLAUDE.md split pattern from Kolibri PR #14164.
Reviewer guidance