Python GuidelinesSAFE

Battle-tested Claude Code, OpenAI Codex, Cursor configs, plugins, hooks and agents with Kimi, MiniMax and GLM API support.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: python-guidelines
description: This skill should be used when writing, reviewing, or refactoring Python code. Covers code integration, idiomatic patterns, docstring formatting, anti-abstraction rules, and software engineering basics.
---

# Python Guidelines

**Integrate into existing code. Don't append to it.**

> Simple is better than complex. Flat is better than nested.
> Errors should never pass silently. Unless explicitly silenced.
> If the implementation is hard to explain, it's a bad idea.
>
> -- The Zen of Python (PEP 20)

## Code Philosophy

- Match existing naming, importing, and signature patterns. Use existing utilities and data structures.
- Functions have a single purpose. Don't hardcode behavior that makes them less general.
- No trivial wrappers for 2 lines or less. Inline it.
- Inline single-use variables at the usage site.
- No try/except unless critical. Let errors surface.
- No duplicate code.
- Functions handle their own input validation. No if-else checks in main.
- Use pathlib, not os.path.
- Consider API and time costs for MongoDB/Gemini/OpenAI/Claude/Voyage.

Don't do this:

```python
# Generate comment report only if requested
if include_comments:
    comment_report = generate_comments_report(start_date, end_date, team, verbose)
else:
    comment_report = ""
    print("   Skipping comment analysis (disabled)")
```

Do this:

```python
comment_report = generate_comments_report(start_date, end_date, team, verbose) if include_comments else ""
```

Ask yourself: "Am I adding code, or integrating into what exists?"

## Simplicity Over Abstraction

**YAGNI: You Aren't Gonna Need It.**

Don't build for hypothetical future requirements. Add complexity only when the current task demands it.

Avoid:

- Abstract base classes for a single implementation
- Configuration options nobody asked for
- Error handling for impossible scenarios
- Wrapper classes around a single function
- Dependency injection when direct calls work
- Generic type parameters for one concrete type

Three similar lines of code is better than a premature abstraction. Refactor when the third real use case appears, not before.

But simplicity does not mean chaos. Always maintain:

- Clear function names that describe what they do
- Logical grouping of related code into modules
- Consistent naming conventions across the project
- Clean separation between I/O and logic
- Explicit parameters over global state or side effects

Ask yourself: "Is this abstraction solving a problem I have right now, or one I'm imagining?"

## Environment

- **Package manager**: uv (NOT pip)
- **Virtual env**: `source .venv/bin/activate` or `uv run python -c "..."`
- **3rd party packages**: Find source with `python -c "import pkg; print(pkg.__file__)"`, then Read.

## Testing Discipline

Never assume anything. Run `python -c "..."` to verify hypotheses about code behavior, package functions, or data structures before suggesting a plan or exiting plan mode.

Ask yourself: "Did I verify this with `python -c` before building on it?"

## Google-Style Docstrings

- **Summary**: Imperative mood ("Calculate", not "Calculates")
- **Args**: All parameters with types and descriptions. No default values. Indent 4 spaces.
- **Types**: `int | str` unions, uppercase shapes `(N, M)`, lowercase builtins `list`/`dict`/`tuple`, capitalize `Any`/`Path`
- **Optional**: `name (type, optional): Description`
- **Returns**: Always `(type)` in parentheses. Never tuple types. Separate named values for multiple returns.
- **Sections**: Examples (>>>), Notes, References (plaintext only). Section titles at 0 indent.
- **Omit**: "Returns:" if nothing returned, "Args:" if no args, "Raises:" unless critical
- **Classes**: Attributes section only, omit Methods/Args. Don't convert single-line to multiline.
- **`__init__`**: Args only. No Examples/Notes/Methods/References.
- **Tests**: Single-line docstrings only.
- Erase default values from existing arg descriptions. Optionally include minimal Examples.

Ask yourself: "Would a new developer understand this function from the docstring alone?"

## Reference Files

Read the matching file before you write the code, not after:

- [`references/idiomatic-patterns.md`](references/idiomatic-patterns.md) -- read when writing loops, comprehensions, unpacking, context managers, or dataclasses. 18 idioms with before/after code
- [`references/zen-of-python.md`](references/zen-of-python.md) -- read when choosing between two designs or judging whether an abstraction earns its place. PEP 20 with annotations
- [`references/google-style-guide.md`](references/google-style-guide.md) -- read when deciding on exceptions, mutable defaults, import style, naming, or comments
- [`references/effective-python-tips.md`](references/effective-python-tips.md) -- read when reviewing or refactoring existing code. Key tips from "Effective Python" (Brett Slatkin)

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (3)

.claude/output-styles/adhd-explanatory.md

AGENTS.md

GEMINI.md

Gates applied: no_behavioural_pass.