Document NFS-safe Cargo builds: use local CARGO_TARGET_DIR before disabling parallelism

[shinaoka]

Summary

When a repository is checked out on an NFS-mounted workspace or worktree, parallel cargo builds can become flaky in ways that look like toolchain bugs: missing object files during link, zero-length archives, undefined symbol: main from build scripts, linker Bus error, etc.

The base agent guidance should document this explicitly and recommend the right mitigation:

• do not immediately fall back to serialized builds as the default answer
• instead, set CARGO_TARGET_DIR to a path on local disk (for example /tmp/<repo>-target or another non-NFS cache path)
• then keep normal parallel compilation enabled
• for local test execution, prefer parallel runners such as cargo nextest when available instead of regressing to serialized cargo test

Motivation

I hit this on tenferro-rs on 2026-03-09 while working from an NFS-backed worktree. The failures went away once the build artifacts were moved to local disk via CARGO_TARGET_DIR.

That is a generally useful rule for agent workflows, because many users work in network-mounted home directories or shared lab filesystems.

Proposed doc change

Please add a note to the base guidance (root AGENTS.md, and probably the shared rules under ai/vendor/template-rs/) along these lines:

If the repository lives on NFS or another network-mounted filesystem and parallel cargo builds become unstable, move build artifacts to local disk with CARGO_TARGET_DIR first. Prefer keeping parallel builds enabled once the target directory is on local storage. For local test runs, prefer parallel runners such as cargo nextest when available.

It would also help to mention that multiple concurrent cargo invocations should avoid fighting over the same target directory unless that is intentional.

Why this matters

Without this guidance, agents may converge on the wrong workaround (CARGO_BUILD_JOBS=1 everywhere), which is slower than necessary and treats the symptom rather than the main cause.

[shinaoka]

Follow-up: please also mention cargo nextest as a preferred local test runner when available. In the same NFS/network-filesystem guidance, it would be useful to say that once CARGO_TARGET_DIR points at local disk, agents can keep test execution parallel and may prefer cargo nextest locally for faster feedback instead of falling back to serialized cargo test.