| name | coding-standards |
| description | Principles, workflows, and standards for writing clean, secure, and highly optimized code, including guidelines for code writing, code review, and architectural integrity. |
Coding Standards & Practices Playbook
This playbook establishes the professional engineering standards required for writing, reviewing, testing, and designing software at an enterprise level.
1. Pre-Implementation Impact Analysis Protocol
Before writing any code or proposing design decisions, the agent MUST perform a comprehensive Impact Analysis. This critical thinking phase must be documented in the issue specification or shared directly with the user.
Analysis Structure
- Explore Options: Propose at least two different implementation approaches (e.g. Option A vs Option B).
- Trade-offs Matrix: Compare options on complexity, maintainability, dependency footprints, performance, and UI/UX ease-of-use.
- Downstream Impacts: Evaluate how each option affects other parts of the workspace, future compatibility, prompt cache size, and developer cognitive load.
- Recommendation: Clearly state the recommended approach and justify why it offers the best balance of robustness and UX/DX simplicity.
2. The Code Writer Playbook (Writing High-Quality Code)
A world-class code writer transforms ambiguous problems into clean, robust, and self-documenting code.
A. The TDD (Test-Driven Development) Cycle
- Red: Write a failing unit test that describes the desired feature or bugfix before writing any production code.
- Green: Write the minimal amount of code necessary to make the test pass.
- Refactor: Clean up the implementation. Remove duplication, improve naming, reduce cognitive complexity, and ensure type safety.
B. Defeating Cognitive Complexity
- Short Functions: Keep functions under 50 lines. If a function does more than one thing, split it.
- Guard Clauses: Return early to eliminate nested
if-else blocks and reduce indentation levels.
- Descriptive Naming: Use clear, pronoun-free naming for variables, classes, and methods.
C. Defensive Code Design
- Input Validation: Check arguments at API boundaries for type safety, ranges, and nullability.
- Safe Resource Lifecycle: Always use context managers (
with statements in Python) for open files, database connections, and sockets.
D. Strict Type Hints & Annotations
- Required Types: Every function/method signature MUST declare parameter types and return types (e.g.,
def calculate_sum(a: int, b: int) -> int:).
- Avoid Generic Fallbacks: Avoid using generic
Any type annotations unless absolutely necessary. When generics are needed, use type variables (TypeVar) or Union/Optional types for precision.
- Static Type Checkers: Run local checkers (e.g.,
mypy or tsc) to verify type compliance before commits.
3. The Code Review Playbook (Zero-Regression Inspections)
A world-class code reviewer ensures code quality, correctness, and team consistency prior to merges.
A. The Self-Review (First Line of Defense)
Before proposing any code review, developers must self-review their changes:
- Diff Inspection: Examine
git diff line-by-line to ensure no debug/temporary code or logging statements are left.
- Code Documentation: Verify all public APIs have clean docstrings explaining parameters, returns, and exceptions.
B. Core Inspection Gates
- Secrets Audit: Programmatically and visually verify that no credentials, API keys, passwords, or
.env configurations are checked in.
- Insulation Check: Verify that layer boundaries are maintained. Helper utilities, DB models, and third-party frameworks must not bleed into core business logic.
- DRY & SOLID Verification: Identify duplicate code patterns and recommend modular class structures following SOLID principles.
- Type Safety: Ensure no variable types are declared as generic
Any or left untyped at public interface boundaries.
C. Common Code Smells to Reject
- Dead Code: Unused imports, variables, functions, or commented-out code blocks.
- Magic Strings/Numbers: Replace inline literals with named constants or configuration variables.
- Swallowed Exceptions: Reject try-except blocks that catch general exceptions without logging or raising them.
4. Testing & Validation Gates
Quality is not verified after implementation—it is built-in.
- Deterministic Tests: Mock all network APIs, database queries, and OS processes. Unit tests must run offline, deterministically, and fast (under 100ms per test).
- Edge Case Coverage: Write test assertions for null inputs, boundary values, empty arrays, and error-throwing states.
- Automated Validation: Ensure static linting, typing checks, and testing suites are run before staging commits.
5. Architectural Integrity & Design Decisions (ADRs)
Maintain a long-term, self-documenting system architecture.
- Use ADRs: For every major design choice (e.g. library addition, folder reorganization, protocol switch), write an Architectural Decision Record in
.agents/memory/decisions/.
- Decoupled Architecture: Structure modules into clear domains with well-defined APIs. Keep system utilities separate from business logic.
6. Token & Context Efficiency Playbook
To optimize agent runtime cost, token consumption, and cognitive footprint, agents must strictly follow these rules:
- Targeted File Reads: Avoid viewing whole files. Always specify
StartLine and EndLine parameters when calling view_file to target only the code relevant to the task.
- Decoupled Subagents: Only invoke subagents for separate, heavy, or multi-step research operations. Perform straightforward code editing and validation within the parent agent context.
- Zero Redundant Commands: Do not run repetitive commands or searches. If a search query or validation command fails 3 times, immediately halt and prompt the user.
- No E2E testing overhead: Do not request, setup, or run browser-based End-to-End or UI tests unless explicitly demanded by the user. Focus strictly on fast, mock-driven unit and integration testing.
