DOC: add AGENTS.md and CLAUDE.md for AI coding agents - #717
Conversation
Adds repository guidance for AI coding agents: build/test/docs commands, the big-picture architecture (filestore, dataset containers, mappers, quickflat, the WebGL viewer pipeline), and non-obvious gotchas (silent caching, import side effects, CTM vertex reordering, Three.js r69). Per the discussion in #706, the content lives in AGENTS.md (the cross-tool standard) and CLAUDE.md imports it, so both filenames stay in sync without a symlink (which would break on Windows checkouts). Closes #706 Co-Authored-By: Claude Fable 5 <[email protected]>
|
Overall it looks OK to me. Anything worth adding @kroq-gar78 @alexhuth @marklescroart ? |
| pip install -U setuptools wheel numpy cython | ||
| pip install -e '.[headless]' --no-build-isolation # headless extra = playwright, for WebGL tests | ||
| pip install -e . --no-build-isolation --group dev # test + type-checking dependencies |
There was a problem hiding this comment.
Can we use uv instead? That'd simplify the setup substantially (just uv sync --all-extras --dev). We'd also have to modify the testing and docs commands later.
There was a problem hiding this comment.
does uv work with windows?
There was a problem hiding this comment.
Supposedly yes! But I haven't tried it. https://docs.astral.sh/uv/getting-started/installation/#__tabbed_1_2
There was a problem hiding this comment.
I like uv but I'm tempted to leave the pip installation instructions. For an LLM it doesn't matter if it's 4 lines vs. one line, and maybe it's easier to debug? But I may be wrong...
There was a problem hiding this comment.
Even for an LLM, I still think uv would be better because it keeps the environment isolated in the repo. The agent doesn't need to worry about outside side effects. (Right now the file doesn't have any instructions to create a venv either, which would be the alternative but IMO is more complicated)
Clarify that changes to overlays.svg are due to pretty-printing and should not be committed.
|
It would also be great if we strongly suggest (require?) new Python code to have type annotations. I'm not sure where in the file that would go. |
2 participants
Closes #706.
Adds repository guidance for AI coding agents (Claude Code and any tool that reads the cross-tool
AGENTS.mdstandard).What's in it
--no-build-isolation), theheadlessextra + Playwright setup, running the full suite / a single file / a single test, the per-test timeout, which tools tests self-skip on (Inkscape, Playwright, FreeSurfer), and the docs build.Databaselayout, thedatasetbraindata × Dataview class hierarchy, the mapper families and their caching, quickflat's layer-composition design, the WebGL pipeline (Package → CTM packs → Tornado templates → Three.js r69 app,JSProxy,shaderlib.js), the sharedoverlays.svgROI system, and configuration (options.cfg, filestore/colormaps).recache/db.clear_cache,import cortexside effects, CTM vertex reordering,package_dataenumeration for new webgl resources, CRLF line endings in some JS files.Layout
Per @kroq-gar78's suggestion in #706, the content lives in AGENTS.md and CLAUDE.md imports it with Claude Code's
@AGENTS.mdsyntax. I used an import rather than a symlink so Windows checkouts (recently fixed in #701) don't degrade the link into a plain text file.🤖 Generated with Claude Code