docs: add CLAUDE.md/AGENTS.md agent guide (#759)

[yingjerkao]

Summary

Seeds the agent-driven workflow proposed in #759 with an operational guide for coding agents (Claude Code, Codex). This is the "Phase 1" safeguard from that issue: a single place that tells an agent how to produce PRs that pass CI, plus the guardrails and domain rules agents otherwise get wrong.

AGENTS.md is a symlink to CLAUDE.md (git mode 120000) so both toolchains read one source of truth — edit CLAUDE.md only. Resolves cleanly on Linux/macOS/WSL, where Cytnx is developed.

Scope of decisions (per discussion)

• Shared file — one canonical CLAUDE.md, AGENTS.md symlinked to it.
• Lean operational contract (~126 lines) — loads fast every session, stays current.
• Mechanical only — the phased roadmap stays in Introducing Agentic Code Generators into Workflow #759; this file is how to work correctly, not what to work on.

Contents

• Build — submodule init + preset configure/build (CMakePresets.json), toggle summary.
• Test — C++ (debug-* preset → test_main → ctest --preset cpu-only), GPU (gpu_test_main, cpu-and-cuda), Python (the exact editable-install + pytest pytests/ CI runs).
• Format — clang-format pinned to v14; run pre-commit, re-add after the hook reformats (a newer clang-format fails CI).
• CI gates — the four checks to clear before pushing (clang-format-check, ci-cmake_tests, downstream find_package, version-consistency).
• Commits & PRs — branch off master, scoped commits, conventional subjects, Co-Authored-By trailer, problem→fix→testing body.
• Guardrails (per Introducing Agentic Code Generators into Workflow #759) — scoped diffs; physics/numerical-correctness changes require human review; flag mixed-dtype changes.
• Domain gotchas — dtype enum ordering (lower = higher precision), Type.type_promote across the real/complex boundary, GPU in-place kernel gaps (GPU: scalar in-place ops throw on non-contiguous tensors for *= and /=, and do a per-call H2D copy #988), cuKron broken under CUDA 13 (GPU build broken: cuKron fails to compile (CUDA 13) after the #982 type_promote change #999), the cytnx_error_msg/cytnx::error macros, and the std::variant dispatch direction (Refactor internal functions using std::variant and visitor pattern #650, Make invalid types passed to cv_typeid_v<T> a compile-time error #938).
• Repo map + pointers to CONTRIBUTING.md / RELEASING.md / Readme.md.

Notes for reviewers

• All commands were fact-checked against the repo (presets, test_main/gpu_test_main targets, ctest presets).
• Docs-only change — no CI impact beyond the docs build; the clang-format hook has no C/C++ files to check here.
• Open questions I'd welcome input on: (1) keep AGENTS.md as a symlink vs. a one-line pointer file (symlink risk on native-Windows checkouts); (2) whether the Co-Authored-By agent-attribution line should be project policy.

Closes #759 is not asserted — this is only Phase 1 of that issue; leaving #759 open for the later phases.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive guide for coding agents in CLAUDE.md and creates a symlink to it in AGENTS.md. The review feedback suggests replacing the Git symlink with a standard markdown pointer file to avoid compatibility issues on Windows. Additionally, it recommends simplifying the build instructions in CLAUDE.md by leveraging CMake's --preset option during the build phase instead of hardcoding build directories and job flags.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 32.96%. Comparing base (7b4d7dc) to head (670a145).
⚠️ Report is 52 commits behind head on master.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1008      +/-   ##
==========================================
+ Coverage   30.82%   32.96%   +2.14%     
==========================================
  Files         229      230       +1     
  Lines       33348    33106     -242     
  Branches    14069    13813     -256     
==========================================
+ Hits        10281    10915     +634     
+ Misses      15795    14824     -971     
- Partials     7272     7367      +95     

Flag	Coverage Δ
cpp	32.61% <ø> (+2.15%)	⬆️
python	61.84% <ø> (+0.40%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Components	Coverage Δ
C++ backend	33.73% <ø> (+1.47%)	⬆️
Python bindings	25.15% <ø> (+6.37%)	⬆️
Python package	61.84% <ø> (+0.40%)	⬆️
see 71 files with indirect coverage changes

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 7b4d7dc...670a145. Read the comment docs.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[pcchen]

Review

Nice work — this is an unusually well-fact-checked guide. I verified the claims directly against the repo (presets, test_main/gpu_test_main targets, .clang-format, pre-commit v14 pin, submodules, the pyproject preset pin + [dev] extra, the Type.hpp enum ordering, type_promote, CYTNX_FUNC_NAME, cytnx_error_msg, and each CI workflow). Almost everything holds up. One claim is wrong, plus two minor notes.

1. The version-consistency gate is mischaracterized (describes a CI safety net that doesn't exist)

- **version-consistency** — if you change the minimum Python version, update every site listed in CONTRIBUTING.md.

This conflates two unrelated things:

• The version-consistency workflow (display name "Release metadata consistency") runs tools/check_release_consistency.py and checks version.cmake / docs/site_root/versions.json — the release package version and docs slug. It has nothing to do with the minimum Python version.
• The minimum Python version has no automated check at all. CONTRIBUTING.md says so explicitly: "There is no automated check for this — please grep for the old version string."

So an agent that bumps requires-python, sees "version-consistency" listed as the enforcing gate, and assumes CI will catch a missed site, will push drift that CI never validates. Suggest describing this gate as guarding version.cmake/versions.json release metadata, and keeping the min-Python-version note with the (accurate) "See also → CONTRIBUTING.md" pointer.

Minor notes (non-blocking)

• CI-gate identifiers vs. displayed check names. The guide names the gates clang-format-check, ci-cmake_tests, ci-downstream-find-package, version-consistency — these are the workflow filenames, but the checks shown on the PR UI read "Formatting Check", "Tests and Codecov", "Downstream find_package", "Release metadata consistency". An agent scanning the PR status list for those exact strings won't find them verbatim; worth aligning or noting they're filenames.
• AGENTS.md symlink on native Windows. Already flagged as an open question in the PR description — on a checkout with core.symlinks=false, AGENTS.md materializes as a 9-byte text file containing CLAUDE.md rather than resolving. Given Cytnx is developed on Linux/macOS/WSL this is acceptable, but the fallback content is misleading if a Windows agent reads it.

Everything else I spot-checked — presets, debug-*/ctest presets, tests/gpu/, clang-format v14, dtype enum ordering (ComplexDouble=1 … Int64=5, matching the dtype <= 2 complex idiom in Type.hpp), type_promote, CYTNX_FUNC_NAME, the .[dev] install command, and the pytest invocation — is accurate.

Posted by Claude Code on behalf of @pcchen

[IvanaGyro]

It is possible to use preset here

[IvanaGyro]

It is able to set up cuda build environment in cloud agent environment. We can consider to ask build cuda to align with the previous section "use cuda preset if touch cuda code"

[yingjerkao]

It is able to set up cuda build environment in cloud agent environment. We can consider to ask build cuda to align with the previous section "use cuda preset if touch cuda code"

Does this mean running agents off Github? Or we can subscribe to the Github GPU workers.

[IvanaGyro]

Does this mean running agents off Github?

Yes. In both codex and Claude Code cloud session. cuda compiler and libraries can be installed on a machine without GPU. The limitation is cuda code can be built on those machines but can not be run. We can also build cuda variant with GitHub action without GPU workers.

[IvanaGyro]

How about just tell the bots follow conventional commits? It is a commit standard

[IvanaGyro]

Maybe this should be defined in Contribution.md

[IvanaGyro]

While building and running debug cuda preset, some env need to be set to suppress ASAN errro

[yingjerkao]

Could you provide some examples?

[IvanaGyro]

ASAN_OPTIONS='protect_shadow_gap=0:replace_intrin=0:detect_leaks=0'
Refer to:
google/sanitizers#629 (comment)
https://stackoverflow.com/a/68027496

[ianmccul]

its worth having a separate GEMINI.md because that is used by the Gemini bot for reviews. For example it keeps suggesting changes for C++17 compatibility, which is really annoying and pointless. GEMINI.md can be more focussed on what needs reviewing, rather than developer-orientated CLAUDE.md and AGENTS.md. See for example https://github.com/Uni20-dev/uni20/blob/main/GEMINI.md. Its basically a moving target of "stop bringing up these issues in automated reviews".

Gemini free reviews go away in another week, but you could get a gemini free trial for another month, and maybe worth paying for it longer-term. I have used gemini-cli briefly (now replaced by Antigravity), but only the free tier so I am not sure how good the higher tier models are, but I've been generally impressed with the gemini reviews.

[pcchen]

Code Review

Useful, accurate agent guide — I spot-verified the content against the repo: every named preset exists in CMakePresets.json, the clang-format-v14 pin, dtype-enum ordering (lower index = higher precision), type_promote cross-kind behavior, cytnx_error_msg → cytnx::error → CytnxError, the variant-dispatch migration direction, and the CI-gates list all check out. The "domain gotchas" section is exactly the right list — it's the traps this month's PRs actually hit.

Findings

1. 🟠 AGENTS.md is a broken symlink. It's committed with git mode 120000 (symlink) but its blob is a 103-byte markdown string — a symlink's blob must be exactly the target path. On POSIX checkout this materializes as a dangling symlink whose "target" is the literal text # Agent Guide⏎⏎Please see…; any non-Claude agent reading AGENTS.md gets ENOENT. (GitHub's web UI renders the target text, which is why the PR view looks fine.) Fix: either a true symlink (blob content exactly CLAUDE.md) or a regular 100644 file with the pointer text — and align the "AGENTS.md is a symlink to it" sentence accordingly.

2. 🟡 Consider folding in the review-attribution policy. There's an (uncommitted) maintainer CLAUDE.md convention in use — agent-authored posts carry "Posted by Claude Code on behalf of @user" attribution. That's an operational-contract item for agents and belongs in this canonical file; it would also avoid a local-file collision when this lands.

3. 🟡 Add the naming conventions @IvanaGyro asked to codify (in the #1001 thread): leading _ = member variable, trailing _ = in-place mutator returning self, snake_case for new code (#836). This PR is the natural home — a short "Naming" section would close that loop.

4. 🟢 Forward-looking gotcha: "a length-1 scalar RHS must stay CPU-resident (#988)" describes post-#980/#992 semantics — neither merged yet. Fine as guidance; consider "(once #980/#992 land)".

Content: LGTM. The symlink defect (finding 1) is the one must-fix.

Posted by Claude Code on behalf of @pcchen

[IvanaGyro]

Add the naming conventions @IvanaGyro asked to codify (in the #1001 thread): leading _ = member variable, trailing _ = in-place mutator returning self, snake_case for new code (#836). This PR is the natural home — a short "Naming" section would close that loop.

I may have bad wording so the bot cannot understand me.

I suggest follow Google style for naming for all new code except that file has consistent naming other than the style guide. Most of C++ files have messy naming now. It is not benefit to try to follow the messy naming if the file has already messy. Google style picked in this project (not by me). Additionally, leading _ should be prohibited for new code strictly.

[ianmccul]

I suggest also adding to the AI guidance, is to pass simple C++ types by value. The AI tends to follow the surrounding code so it passes simple values by const& when it should pass by value. For Cytnx scalars, passing by reference will never be faster. Even complex<double> is better passed by value, and will actually be passed via CPU registers in some cases. Passing by reference requires pushing the value onto the stack, passing a pointer to that value into the function, and then the function has to load the pointer and dereference it to retrieve the value.

The other thing is if (x) cytnx_error_msg(true, "...... %s", "\n"); But I regard that as Cytnx house style now. Cytnx wouldn't be complete without it. But suggest cytnx_error_msg adds "\033[1A" to the string, to get the extra line back 🤣

[ianmccul]

I don't like the Google style of T &x. It sort-of makes sense in C code for pointers, T *x, where (*x) is is an object of type T, but in C++ we prefer to think that x is a "pointer to T". And for references, T &x looks very strange to me. There is no sense in which &x functions like something of type T.

[yingjerkao]

I think the easiest way to enforce Google C++ style is using Skills, such as Google C++ Style Guide Skill,Google Python Style Guide Skill.