least-astonishment
Principle of Least Astonishment (POLA)
Auto-activate when: Making code changes, refactoring, modifying existing functions, changing APIs, renaming things, moving files, or reviewing implementations. Should activate alongside development-philosophy for any non-trivial changes.
Core Principle
Every change should be predictable to someone familiar with the codebase.
If a change would surprise a developer who knows the project, either:
- Don't make it
- Make a smaller, less surprising change
- Explain clearly before proceeding
Before Making Changes
The Surprise Check
More from ilude/claude-code-config
code-documentation
Guidelines for self-explanatory code and meaningful documentation. Activate when working with comments, docstrings, documentation, code clarity, API documentation, JSDoc, or discussing code commenting strategies. Guides on why over what, anti-patterns, decision frameworks, and language-specific examples.
12claude-code-workflow
Claude Code AI-assisted development workflow. Activate when discussing Claude Code usage, AI-assisted coding, prompting strategies, or Claude Code-specific patterns.
10css-workflow
CSS and styling workflow guidelines. Activate when working with CSS files (.css), Tailwind CSS, Stylelint, or styling-related tasks.
7api-design-patterns
Language-agnostic API design patterns covering REST and GraphQL, including resource naming, HTTP methods, status codes, versioning, pagination, filtering, authentication, error handling, and schema design. Activate when working with APIs, REST endpoints, GraphQL schemas, API documentation, OpenAPI/Swagger, JWT, OAuth2, endpoint design, API versioning, rate limiting, or GraphQL resolvers.
7python-workflow
Python project workflow guidelines. Triggers: .py, pyproject.toml, uv, pip, pytest, Python. Covers package management, virtual environments, code style, type safety, testing, configuration, CQRS patterns, and Python-specific development tasks.
6nextjs-workflow
Next.js framework workflow guidelines. Activate when working with Next.js projects, next.config, app router, or Next.js-specific patterns.
6