Global Coding Style

The Global Coding Style skill provides automated guidance for maintaining clean, maintainable, and high-quality software architectures. It enforces a philosophy of reality-first development, ensuring that code is written to solve current, verified requirements rather than speculative future abstractions. This skill is intended for software engineers and autonomous agents working within complex codebases who need to ensure structural integrity and code clarity. It focuses on reducing technical debt by eliminating dead code, clarifying naming conventions, and ensuring that all logic is supported by rigorous unit and integration testing.

• Enforces single-responsibility principle for all functions and modules to improve testability and readability.

• Integrates with linters and formatters like Black, Ruff, Prettier, and ESLint to maintain project-wide stylistic consistency.

• Promotes the use of guard clauses to handle invalid states early, improving function flow and reducing nested conditional complexity.

• Facilitates the explicit documentation of design trade-offs and non-obvious implementation decisions in code comments.

• Manages the lifecycle of legacy code, providing heuristics for when to maintain backwards compatibility versus performing clean deletions.

• Mandates that all side effects, such as I/O operations or state mutations, are explicitly handled rather than hidden within complex business logic.

• Provides systematic guidance on avoiding speculative abstractions, ensuring that no features are implemented without proven runtime needs or specifications.

• Use this skill during initial implementation, code reviews, and large-scale refactoring sessions to ensure alignment with architectural standards.

• Input: Code segments, architectural design documents, or PR diffs requiring review for readability and complexity.

• Output: Refactored code suggestions, naming improvements, removal of unused imports or unreachable code, and documentation of design rationale.

• Best applied in environments using FastAPI, SQLAlchemy, or asynchronous Python frameworks where code clarity is critical for long-term maintenance.

• Constraints: Always prioritize existing test coverage; if a refactoring decision risks breaking established unit tests, perform a regression check using tools like pytest before finalizing.