Repository navigation
Add AGENTS.md, with CLAUDE.md importing it - #45
Conversation
Commands, the layering of src/adata, the write-safety rules every store-writing command follows, the test conventions and the release route, for coding agents working in the repo. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.
An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c62d621d08
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| point of the tool is that memory is set by `--chunk`, not by the size of the | ||
| input, so code that loads a whole matrix or column is a regression unless it is | ||
| behind an explicit `--in-memory`. |
There was a problem hiding this comment.
For workflows involving axis metadata, this invariant does not describe the repository: core/select.py::read_names reads an entire axis index, core/concat.py::concat_on_disk retains every input's obs and var names, and conversion/tenx.py::_features calls read_str_all for complete var columns. Their memory therefore scales with axis length even without --in-memory, so an agent cannot follow this guidance without treating established implementations as regressions. Either distinguish matrix payloads from metadata or stream these paths before presenting the rule as universal.
AGENTS.md reference: AGENTS.md:L6-L11
Useful? React with 👍 / 👎.
| - **Never write a store in place.** Every command that writes a store wraps the | ||
| write in `util/staging.staged_outputs([...])`. |
There was a problem hiding this comment.
When an agent works on create or any import subcommand, this categorical guarantee is false: commands/create.py::create_store deletes a forced destination and opens the final path directly with mode "w", while commands/import_data.py::_prepare_target_path copies or opens the final output directly and --inplace later mutates it with mode "a". A failure can therefore leave those destinations removed, partially written, or modified, despite this guide implying atomic rollback; either stage those flows or name only the commands for which the rule currently holds.
AGENTS.md reference: AGENTS.md:L98-L106
Useful? React with 👍 / 👎.
| - **Outputs keep the source's index dtypes, chunking and compression.** | ||
| Changing them is `recast`'s job, or that of an explicit flag. |
There was a problem hiding this comment.
For concatenations whose combined dimensions or nonzero count exceed a source integer type, core/concat.py::_concat_index_dtypes intentionally widens indices or indptr; similarly, storage.fit_chunks must shrink invalid HDF5 chunks and cross-backend copies cannot preserve incompatible codecs. The unconditional statement that only recast or an explicit flag may make these changes could lead an agent to undo safeguards and introduce overflow or invalid datasets. Qualify preservation as best-effort, with required capacity and backend-compatibility exceptions.
AGENTS.md reference: AGENTS.md:L116-L117
Useful? React with 👍 / 👎.
Guidance for coding agents working in this repo. It lives in
AGENTS.md, which most agents read;CLAUDE.mdimports it with@AGENTS.md, so there's one text to maintain.It covers:
src/adata(cli→commands→core→elements→storage, plusconversionandformats);🤖 Generated with Claude Code