Skip to content

docs(agents): require running Python through Nix#749

Merged
cpcloud merged 2 commits intomainfrom
chore/nix-python-rule
Mar 11, 2026
Merged

docs(agents): require running Python through Nix#749
cpcloud merged 2 commits intomainfrom
chore/nix-python-rule

Conversation

@cpcloud
Copy link
Copy Markdown
Collaborator

@cpcloud cpcloud commented Mar 10, 2026

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

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings March 10, 2026 16:16
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 ### Nix section requiring Python to be run via nix run 'nixpkgs#python3' rather than a bare interpreter command.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread AGENTS.md Outdated
Comment on lines +206 to +207
`nix run 'nixpkgs#python3' -- $@`. Never use a bare `python` or `python3`
command directly.
Copy link

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
`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.

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>
@cpcloud cpcloud merged commit 30e72fa into main Mar 11, 2026
18 checks passed
@cpcloud cpcloud deleted the chore/nix-python-rule branch March 11, 2026 00:19
cpcloud added a commit that referenced this pull request Mar 19, 2026
## 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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants