Skills Directory

---
title: TypeScript Strict Mode
description: Enforce strict TypeScript compilation settings across the project to catch potential errors early.
tags: [typescript, code-quality]
category: code-quality
---
All new TypeScript files and modifications to existing ones must adhere to the `strict: true` compiler option. This includes `noImplicitAny`, `strictNullChecks`, `strictFunctionTypes`, `strictPropertyInitialization`, `noImplicitThis`, and `alwaysStrict`. When working with existing codebases that are not fully strict, prioritize making new additions strict and gradually refactor older sections. Use type assertions (`as`) sparingly and only when absolutely necessary, providing a clear comment explaining the rationale. Avoid `any` type unless explicitly justified for interoperability with external libraries or specific complex scenarios. Focus on explicit typing for function parameters and return values.

---
title: React Functional Components
description: Prefer functional components with React Hooks for all new UI development.
tags: [react, frontend, code-quality]
category: frontend
---
All new React components should be implemented as functional components utilizing React Hooks for state and lifecycle management. Avoid creating new class components. When refactoring existing class components, prioritize converting them to functional components, especially if they are simple or frequently modified. Ensure proper use of `useState`, `useEffect`, `useContext`, and custom hooks to encapsulate logic. Memoization with `useMemo` and `useCallback` should be applied judiciously to optimize performance only when profiling indicates a bottleneck, not as a default. Components should be pure functions of their props and state where possible.

---
title: Python PEP 8 Compliance
description: All Python code must strictly adhere to the PEP 8 style guide for consistency and readability.
tags: [python, code-quality]
category: code-quality
---
All Python code written or modified within this project must strictly follow the PEP 8 style guide. This includes naming conventions (e.g., `snake_case` for functions and variables, `PascalCase` for classes), line length (max 79 characters), proper indentation (4 spaces), and consistent whitespace usage. Utilize tools like `flake8` or `black` for automated formatting and linting. Docstrings should be provided for all modules, classes, and functions, following PEP 257 conventions. Prioritize readability and maintainability through clear, concise code and adherence to established community standards. Avoid overly complex list comprehensions or single-line statements that reduce clarity.

---
title: Go Error Handling
description: Implement idiomatic Go error handling using multi-value returns and explicit checks.
tags: [go, code-quality, backend]
category: backend
---
All Go functions that can encounter an error must return an `error` as their last return value. Explicitly check for errors immediately after a function call that returns an error, typically using `if err != nil { ... }`. Do not ignore errors. When propagating errors, use `fmt.Errorf` with `%w` to wrap the original error, providing context without losing the root cause. Avoid panicking except for truly unrecoverable program states (e.g., initialization failures). Log errors at the appropriate layer, typically at the boundary where the error cannot be handled further. Custom error types should implement the `error` interface and provide additional context or methods where beneficial.

---
title: SQL Injection Prevention
description: All database interactions must use parameterized queries or ORMs to prevent SQL injection vulnerabilities.
tags: [security, backend, database]
category: security
---
To prevent SQL injection attacks, all database queries must utilize parameterized statements or prepared statements. Never concatenate user-supplied input directly into SQL query strings. For object-relational mappers (ORMs) like SQLAlchemy, Hibernate, or Prisma, ensure they are configured and used correctly to generate safe queries. When raw SQL is absolutely necessary, use the database driver's parameterized query features (e.g., `?` or `$1` placeholders). Input validation and sanitization should be performed on all user-supplied data, but this is a secondary defense; parameterized queries are the primary mechanism against SQL injection. Regularly review database access patterns for potential vulnerabilities.

---
title: API Versioning Strategy
description: All public-facing APIs must implement a clear versioning strategy, preferably URI-based.
tags: [architecture, backend, api]
category: architecture
---
All public-facing API endpoints must include versioning to ensure backward compatibility and smooth evolution. The preferred method is URI versioning (e.g., `/api/v1/resource`). Header-based or query parameter-based versioning may be considered for specific cases but require strong justification. When introducing breaking changes, a new API version must be released. Non-breaking changes (e.g., adding new fields) can be introduced within the same version. Clearly document the deprecation policy for older API versions, including timelines for support cessation. Ensure API documentation reflects all available versions and their respective schemas. Plan for graceful degradation and client migration paths.

---
title: Next.js Data Fetching
description: Use `getServerSideProps`, `getStaticProps`, or client-side fetching appropriately in Next.js.
tags: [nextjs, frontend, performance]
category: frontend
---
For data fetching in Next.js, choose the appropriate method based on the data's nature and update frequency. Use `getStaticProps` for data that can be pre-rendered at build time and is not user-specific, leveraging `revalidate` for incremental static regeneration. Use `getServerSideProps` for data that must be fetched on each request and is user-specific or highly dynamic. For client-side data fetching, especially for user-specific or interactive content, use `useEffect` or a data fetching library like SWR or React Query. Avoid mixing server-side and client-side fetching unnecessarily on the same page. Optimize data payload sizes and consider caching strategies.

---
title: Docker Image Optimization
description: Build small, secure, and efficient Docker images using multi-stage builds and minimal base images.
tags: [devops, docker, performance]
category: devops
---
All Dockerfiles must employ multi-stage builds to minimize the final image size by separating build-time dependencies from runtime dependencies. Use minimal base images like `alpine` or `distroless` where possible. Avoid installing unnecessary packages in the final image. Copy only essential files into the image. Ensure `WORKDIR` is set and `USER` is defined to run as a non-root user. Leverage `.dockerignore` to exclude irrelevant files from the build context. Cache layers effectively by placing frequently changing instructions later in the Dockerfile. Scan images for vulnerabilities using tools like Trivy or Clair as part of the CI/CD pipeline.

---
title: Kubernetes Manifest Best Practices
description: Follow best practices for creating and maintaining Kubernetes deployment manifests.
tags: [devops, kubernetes, architecture]
category: devops
---
Kubernetes manifests should be declarative and idempotent. Define resource requests and limits for all containers to ensure proper scheduling and prevent resource starvation. Use `readinessProbes` and `livenessProbes` to ensure application health and proper traffic routing. Employ `ConfigMaps` and `Secrets` for configuration and sensitive data, avoiding hardcoding values directly in manifests. Use `Labels` and `Selectors` consistently for effective resource management and service discovery. Define `PodDisruptionBudgets` for critical applications. Version control all manifests and use tools like Helm or Kustomize for templating and managing deployments across environments. Avoid `latest` tag for container images in production.

---
title: Automated Testing Coverage
description: All new code and significant refactors must be accompanied by comprehensive automated tests.
tags: [testing, code-quality]
category: testing
---
Every new feature, bug fix, or significant refactoring must be accompanied by appropriate automated tests, including unit, integration, and end-to-end tests where applicable. Aim for a minimum of 80% line coverage for new code, but prioritize meaningful tests over arbitrary coverage percentages. Unit tests should be isolated and fast. Integration tests should verify interactions between components. End-to-end tests should cover critical user journeys. Tests must be deterministic and runnable in a CI/CD pipeline. Avoid mocking too much, which can lead to brittle tests. Clearly name tests to reflect the behavior they are verifying. Regularly review and update existing tests.

---
title: Cross-Browser Compatibility
description: All frontend development must ensure compatibility with the defined set of target browsers.
tags: [frontend, testing, code-quality]
category: frontend
---
All web applications and components must be tested and verified for functionality and appearance across the defined set of target browsers (e.g., latest Chrome, Firefox, Safari, Edge). Utilize tools like BrowserStack or Cypress for automated cross-browser testing. When using new CSS properties or JavaScript features, always check their browser support using resources like Can I use... and provide appropriate fallbacks or polyfills. Avoid browser-specific hacks unless absolutely necessary, and always document them. Prioritize responsive design principles to ensure a consistent user experience across various screen sizes and devices, not just different browsers. Regularly update the list of supported browsers.

---
title: Logging and Monitoring Standards
description: Establish consistent logging and monitoring practices across all services for better observability.
tags: [devops, observability, backend]
category: devops
---
All services must implement structured logging, emitting logs in a machine-readable format (e.g., JSON). Log levels (DEBUG, INFO, WARN, ERROR, FATAL) should be used consistently. Avoid logging sensitive information. Include relevant context in logs, such as request IDs, user IDs, and transaction IDs, for easier debugging and tracing. Define key metrics for application performance and health (e.g., request latency, error rates, CPU/memory usage) and expose them via standard protocols (e.g., Prometheus). Set up appropriate alerts for critical thresholds. Ensure logs are centralized and accessible for analysis. Regularly review log volume and verbosity to balance detail with storage costs.

When performing code reviews, Claude, prioritize identifying potential security vulnerabilities, performance bottlenecks, and maintainability issues. Focus on architectural consistency, adherence to established design patterns, and clarity of intent. Provide actionable feedback with specific code examples for suggested improvements. Do not just point out issues; suggest concrete solutions. Ensure that the proposed changes align with the project's overall direction and existing coding standards. Pay close attention to error handling, resource management, and test coverage. If a significant refactor is needed, suggest it as a separate task rather than blocking the current pull request.

When generating unit tests, Claude, ensure they are isolated, fast, and deterministic. Each test case should focus on a single unit of work and cover a specific scenario, including common cases, edge cases, and error conditions. Use mocking and stubbing judiciously to isolate the unit under test from its dependencies. Avoid over-mocking, which can lead to brittle tests. Name tests clearly to describe the behavior being verified. Prefer `Arrange-Act-Assert` structure. Do not generate tests that rely on external services or databases for unit testing; use integration tests for those scenarios. Ensure generated tests are easily readable and maintainable.

When designing or modifying APIs, Claude, adhere strictly to RESTful principles. Use clear, noun-based resource URLs (e.g., `/users`, `/products/{id}`). Employ appropriate HTTP methods (GET, POST, PUT, PATCH, DELETE) for their intended actions. Ensure consistent request and response formats, preferably JSON. Handle status codes correctly (e.g., 200 OK, 201 Created, 400 Bad Request, 404 Not Found, 500 Internal Server Error). Implement proper authentication and authorization mechanisms. Consider pagination, filtering, and sorting for collection resources. Document API endpoints thoroughly using OpenAPI/Swagger specifications. Prioritize backward compatibility for existing versions and plan for clear versioning when breaking changes are necessary.

When tasked with refactoring, Claude, always aim for small, incremental changes. Ensure that a comprehensive suite of tests exists and passes before, during, and after any refactoring effort. If tests are insufficient, suggest adding them first. Focus on improving readability, reducing complexity, and eliminating duplication. Avoid 'big bang' refactors. Each refactoring step should leave the code in a working state. Document the rationale behind significant refactors. Prioritize refactoring 'hot spots' – areas of the codebase that are frequently changed or are sources of bugs. Communicate the scope of refactoring clearly before execution.

When reviewing or generating code, Claude, actively scan for common security vulnerabilities such as SQL injection, XSS, CSRF, insecure direct object references, broken authentication, and sensitive data exposure. Pay attention to input validation, output encoding, access control, and cryptographic practices. For web applications, ensure proper use of security headers. Highlight any potential misconfigurations in infrastructure-as-code. If a vulnerability is suspected, provide a detailed explanation of the risk and suggest remediation steps, referencing OWASP Top 10 where applicable. Never suggest solutions that compromise security for convenience.

When generating documentation, Claude, focus on clarity, conciseness, and accuracy. Ensure that all generated documentation is up-to-date with the current codebase. For code comments, explain *why* certain decisions were made, not just *what* the code does. For API documentation, provide examples of requests and responses. For user guides, use simple language and provide step-by-step instructions. Maintain a consistent style and tone. Suggest updates to READMEs, architectural decision records (ADRs), and inline comments as part of any code changes. Prioritize documentation that helps new developers onboard quickly or existing developers understand complex systems.

When assisting with debugging, Claude, adopt a systematic approach. First, ask for detailed reproduction steps and any available error messages or logs. Analyze log files for stack traces, error codes, and contextual information. Propose hypotheses about the root cause and suggest targeted diagnostic steps, such as adding temporary logging, inspecting variables, or stepping through code. Prioritize narrowing down the problem space before jumping to solutions. If the issue is environment-specific, suggest checking configuration or dependencies. Document the debugging process and findings, even if the initial hypotheses are incorrect, to aid future troubleshooting. Aim to identify the smallest possible change to fix the bug.

When working on frontend components, Claude, advise on creating modular, reusable, and testable structures. Components should ideally follow the Single Responsibility Principle. Separate presentational components from container components when appropriate. Use a consistent naming convention for files and components. Ensure components are easily composable and accept props for customization rather than relying on global state where not necessary. Prioritize accessibility (A11y) considerations from the outset. Suggest using design systems or component libraries consistently. Encourage breaking down complex UIs into smaller, manageable components to improve maintainability and facilitate testing. Emphasize clear prop types or interface definitions.

Copilot, when generating code, strictly adhere to the project's established naming conventions. For Python, use `snake_case` for variables and functions, `PascalCase` for classes. For JavaScript/TypeScript, use `camelCase` for variables and functions, `PascalCase` for components and types. Database table names should be plural `snake_case`, and column names singular `snake_case`. Constants should be `SCREAMING_SNAKE_CASE`. Ensure variable names are descriptive and avoid abbreviations unless they are widely understood within the domain. Consistency in naming improves readability and maintainability across the entire codebase.

Copilot, when writing or suggesting code, minimize the use of global variables and mutable global state. Prefer passing data explicitly through function parameters or using dependency injection. For frontend applications, utilize state management libraries (e.g., Redux, Zustand, React Context) in a structured way rather than ad-hoc global variables. Global state can lead to unpredictable behavior, make testing difficult, and introduce hard-to-trace bugs. If global state is unavoidable for specific patterns, encapsulate it carefully and ensure its lifecycle is well-managed. Focus on creating pure functions where possible to enhance predictability and testability.

Copilot, for JavaScript and TypeScript code, always prefer modern ES6+ features. Use `const` and `let` instead of `var`. Employ arrow functions for concise syntax and correct `this` binding. Utilize template literals for string interpolation. Leverage destructuring assignments for objects and arrays. Use `async/await` for asynchronous operations instead of chaining `.then()` callbacks extensively. Favor `import/export` modules over CommonJS `require/module.exports`. Embrace spread and rest operators. This ensures the codebase remains modern, readable, and takes advantage of performance improvements and language enhancements. Avoid older, deprecated syntax.

Copilot, when generating React components, strictly follow React Hooks best practices. Only call Hooks at the top level of functional components or from custom Hooks. Do not call Hooks inside loops, conditions, or nested functions. Ensure all dependencies for `useEffect`, `useMemo`, and `useCallback` are correctly specified in their dependency arrays to prevent stale closures or unnecessary re-renders. Create custom Hooks to encapsulate reusable logic. Avoid over-optimizing with `useMemo`/`useCallback` unless profiling indicates a performance issue. Keep components small and focused, separating concerns effectively. Prioritize readability over overly clever one-liners.

Copilot, when generating Python code, always include type hints for function parameters, return values, and significant variables. This improves code readability, enables static analysis tools, and helps prevent runtime errors. Use standard library typing modules (e.g., `List`, `Dict`, `Optional`, `Union`, `Any`). For complex types, define `TypeAlias` or `TypedDict`. If a function's return type is the class itself, use `Self` from `typing_extensions` or a forward reference string. Ensure type hints are accurate and reflect the expected data types. This practice is crucial for maintainability and collaboration in larger Python projects.

Copilot, when generating SQL queries, prioritize efficiency and performance. Suggest using appropriate indexes. Avoid `SELECT *` in production code; explicitly list required columns. Use `JOIN` clauses effectively instead of subqueries where a join is more performant. Be mindful of N+1 query problems in ORM contexts. Suggest `LIMIT` and `OFFSET` for pagination. Consider the impact of `ORDER BY` and `GROUP BY` on performance. When dealing with large datasets, suggest techniques like batch processing or materialized views. Always aim for queries that minimize table scans and leverage existing indexes. For complex operations, break them down into simpler, more manageable steps.

Copilot, implement consistent and robust error handling across all code. For languages like Python and Java, use `try-except` or `try-catch` blocks to gracefully handle expected exceptions. In Go, explicitly check `error` return values. Distinguish between recoverable and unrecoverable errors. Log errors with sufficient context but avoid logging sensitive information. For API endpoints, return standardized error responses with appropriate HTTP status codes and clear error messages. Avoid catching generic exceptions unless re-raising them after logging. Propagate errors up the call stack until they can be handled meaningfully or reported to the user/system administrator. Ensure resource cleanup in `finally` blocks or using `defer`.

Copilot, when operating in a Test-Driven Development (TDD) context, prioritize generating failing tests *before* generating the corresponding implementation code. For a given requirement or desired behavior, first suggest a minimal test case that clearly demonstrates the absence of that behavior. Once the test is written and confirmed to fail, then provide the simplest possible code implementation to make that test pass. After the test passes, assist in refactoring the implementation while ensuring all tests continue to pass. This red-green-refactor cycle is crucial. Focus on unit tests primarily, but also suggest integration tests where appropriate for broader system interactions.

All new branches must adhere to a strict naming convention to maintain order and clarity in the repository. Feature branches should be prefixed with `feature/`, followed by a concise, kebab-case description (e.g., `feature/add-user-profile`). Bug fix branches should use `fix/` (e.g., `fix/login-bug-123`). Release branches should be `release/vX.Y.Z`. Hotfix branches should be `hotfix/vX.Y.Z-issue`. Development branches are typically `develop` or `main`. Any branch not conforming to these patterns will trigger a warning in the CI pipeline and may require manual approval or renaming. This rule aids in automated workflow triggers and improves project visibility.

All commit messages must follow the Conventional Commits specification (https://www.conventionalcommits.org/). Each commit message should start with a type (e.g., `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`), followed by an optional scope, a colon, and a subject line. The subject line should be concise and imperative. An optional body can provide more detailed explanations. This format enables automated changelog generation, semantic versioning, and clearer project history. Commits that do not conform will fail the CI/CD pipeline's commit linting step, requiring the author to amend the message before merging.

All project dependencies, across all languages and package managers (e.g., `package.json`, `requirements.txt`, `go.mod`), must be pinned to exact versions. Avoid using caret (`^`), tilde (`~`), or `latest` ranges for production dependencies. This ensures deterministic builds and prevents unexpected breaking changes or security vulnerabilities introduced by new minor/patch versions. Dependency updates should be performed explicitly and reviewed, preferably through automated dependency update tools (e.g., Dependabot) that create pull requests for review. Regularly scan for known vulnerabilities in pinned dependencies using tools like Snyk or OWASP Dependency-Check.

Before any deployment to production environments, a predefined deployment checklist must be completed and verified. This checklist includes items such as: all automated tests passing, security scans clear, environment variables configured, database migrations reviewed, rollback plan documented, monitoring dashboards set up, and relevant stakeholders notified. The CI/CD pipeline will gate deployments based on the completion status of this checklist, potentially requiring a manual approval step. This process ensures that deployments are safe, predictable, and minimize the risk of production incidents, promoting a culture of thoroughness and accountability.

All Pull Requests (PRs) must undergo a thorough review by at least two designated reviewers before merging. Reviewers are expected to check for functional correctness, adherence to coding standards, test coverage, potential performance issues, security vulnerabilities, and clarity of documentation. Feedback should be constructive and actionable. The author is responsible for addressing all comments and ensuring the PR meets quality standards. Automated checks (linting, tests) must pass before a PR can be marked as ready for review. Large PRs should be avoided; encourage breaking down changes into smaller, more manageable units to facilitate quicker and more effective reviews.

All new features, especially those with significant impact or requiring A/B testing, must be implemented behind a feature flag. This allows for controlled rollout, easy rollback, and testing in production environments without impacting all users. Feature flags should be managed by a dedicated service or library. Ensure that default states for feature flags are safe and that the code path for both enabled and disabled states is thoroughly tested. Implement a clear lifecycle for feature flags, including a process for their eventual removal (flag cleanup) once a feature is fully rolled out and stable. Document all feature flags and their intended purpose.

Aider, when making changes, strive to create atomic commits. Each commit should represent a single, logical change and be as small as possible while remaining functional. Avoid mixing unrelated changes (e.g., refactoring, bug fix, and new feature) into a single commit. This makes it easier to review changes, revert specific modifications if necessary, and understand the project's history. If a task involves multiple distinct steps, commit each step individually. For example, a refactor should be a separate commit from a new feature implementation. Ensure commit messages clearly describe the purpose of the change.

Aider, when interacting with the user, be clear, concise, and proactive in confirming understanding before executing significant changes. Before making substantial modifications, summarize the proposed changes and ask for explicit confirmation. If a request is ambiguous, ask clarifying questions. Provide context for your actions and explain your reasoning. When presenting code, highlight the specific changes made. Avoid making assumptions about user intent. If you encounter a problem or limitation, communicate it transparently. Your goal is to be a helpful and predictable pair programmer, not to surprise the user with unexpected alterations. Offer alternatives when appropriate.

Aider, when a new feature needs to be added to an existing, potentially messy, part of the codebase, prioritize refactoring the existing code first to make it easier to integrate the new feature cleanly. Do not simply 'bolt on' new functionality to poorly structured code. This 'refactor before new feature' approach ensures that the codebase's quality improves over time, rather than degrading. Propose refactoring steps that simplify the target area, improve its testability, or make it more extensible. Once the area is clean, then proceed with implementing the new feature. This might involve an extra commit or two, but it pays off in long-term maintainability.

Aider, any new code you introduce or modify significantly must be accompanied by adequate test coverage. For new functions or modules, aim for comprehensive unit tests that cover all major logical paths and edge cases. If existing code lacks tests and you are modifying it, suggest adding tests for the affected areas. Prioritize tests that verify critical business logic and potential failure points. Do not commit code without corresponding tests, unless explicitly instructed otherwise or if the change is purely cosmetic and has no functional impact. Ensure tests are clear, readable, and pass reliably.

Aider, whenever you make a code change that affects functionality, APIs, configuration, or introduces new concepts, ensure that relevant documentation is updated accordingly. This includes inline comments, docstrings, README files, API documentation, and any other project-specific documentation. If a change deprecates a feature, update the documentation to reflect this. If a new dependency is added, update installation instructions. The documentation should always reflect the current state of the codebase. If you identify outdated or missing documentation related to your changes, propose an update as part of your work. Good documentation is as important as good code.

Aider, integrate security considerations throughout the development workflow. Before implementing new features or modifying sensitive areas, consider potential security implications. When reviewing code, actively look for common vulnerabilities (e.g., input validation issues, insecure data handling, authorization flaws). If you identify a potential security risk, flag it immediately and suggest mitigation strategies, referencing best practices like OWASP Top 10. Ensure that any generated code adheres to secure coding guidelines. If a change involves handling sensitive data, confirm that appropriate encryption, access controls, and logging are in place. Security is a continuous concern, not an afterthought.