docs(agents): require running Python through Nix#749
Conversation
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR adds a single documentation rule to AGENTS.md instructing AI agents to invoke Python through Nix (nix run 'nixpkgs#python3' -- ...) rather than via bare python or python3 commands when Nix is available. It fits into the existing "Nix" guidelines section, which already covers quoting flake refs, fallback priority, dynamic store paths, and package mappings.
Changes:
- Adds a new bullet under the
### Nixsection requiring Python to be run vianix run 'nixpkgs#python3'rather than a bare interpreter command.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| `nix run 'nixpkgs#python3' -- $@`. Never use a bare `python` or `python3` | ||
| command directly. |
There was a problem hiding this comment.
The example command nix run 'nixpkgs#python3' -- $@ uses the shell special variable $@, which only expands meaningfully inside a shell function or script. In an ad-hoc command invocation (e.g., running a one-off script in a terminal), $@ expands to nothing, silently dropping all intended arguments (script path, flags, etc.). This could mislead an AI agent into producing broken invocations.
The rest of the Nix section consistently uses <placeholder> notation for generic arguments (e.g., <tool>, <command> on lines 195–196). The example here should follow the same pattern, replacing $@ with something like <script.py> [args...] or just <script.py> to make it concrete and unambiguous.
| `nix run 'nixpkgs#python3' -- $@`. Never use a bare `python` or `python3` | |
| command directly. | |
| `nix run 'nixpkgs#python3' -- <script.py> [args...]`. Never use a bare | |
| `python` or `python3` command directly. |
There was a problem hiding this comment.
Fixed in c200a08 — replaced $@ with <script.py> [args...] to match the placeholder convention used elsewhere in the Nix section.
Replace $@ with <script.py> [args...] to match the <placeholder> convention used elsewhere in the Nix section. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
## Summary - Add rule to Nix section of AGENTS.md requiring Python to be run via `nix run 'nixpkgs#python3' -- $@` when Nix is available, never bare `python`/`python3` 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Summary
nix run 'nixpkgs#python3' -- $@when Nix is available, never barepython/python3🤖 Generated with Claude Code