Add Custom Code Rules

Custom Code Rules allow you to enforce team-specific coding standards and patterns unique to your organization, and to have Aikido fix the violations they find. Create rules that detect specific code patterns, enforce naming conventions, or flag architectural violations that aren't covered by default checks.

What are Custom Code Rules?

Custom Code Rules are AI-powered checks that you define to match your team's specific requirements. Unlike default checks that apply general best practices, custom rules enforce standards unique to your codebase, architecture, or business logic.

Creating a Custom Code Rule

1. 1

   Define your rule

   1. Navigate to Code Quality > Checks tab
   2. Click Add Custom Code Rule
   3. Write a clear description of what the rule should detect:

   Example:

   Allow only Alpine base images in Dockerfiles as base images

2. 2

   Select target languages

   Choose which programming languages this rule applies to

3. 3

   Generate and refine examples

   • Click Generate Examples to let AI create initial code samples
   • Review and modify the generated examples
   • Provide both compliant and non-compliant examples:

   Compliant example:

   # ✅ Code that follows the rule
   FROM alpine:3.18
   RUN apk add --no-cache nodejs

   Non-compliant example:

   # ❌ Code that violates the rule
   FROM ubuntu:latest
   RUN apt-get update && apt-get install nodejs

4. 4

   Validate your rule

   1. Click Validate Rule to test your examples
   2. The system will verify that:
      • Your compliant examples pass the rule
      • Your non-compliant examples are correctly flagged
      • The rule logic is consistent and clear
   3. Adjust examples if validation fails
5. 5

   Add an AutoFix prompt

   This step is optional. AutoFix must be enabled for the workspace.

   1. Write a prompt that tells AutoFix how to correct a violation. For the Alpine example: Replace the base image with alpine.
   2. Click Validate Prompt. Aikido applies the prompt to your non-compliant example, then checks the result against the rule.
   3. When validation passes, the fixed example no longer triggers the rule. Click Continue.
   4. When validation fails, the fixed example still triggers the rule. Adjust the prompt and validate again.

   Click Skip to save the rule without AutoFix. Aikido offers AutoFix for a custom rule after you save a prompt that passes validation. Edit the rule later to add or change the prompt. Changing the prompt requires validation again before you can save.

6. 6

   Configure rule details

   Once validated, provide additional information about your rule:

   1. Title: Give your rule a clear, descriptive name

      Use Alpine base images in Docker containers

   2. TL;DR: Write a brief summary of the issue

      Non-Alpine base images increase container size and attack surface

   3. How to fix: Provide actionable guidance for developers. This text is what people see on the finding. The AutoFix prompt from the previous step is what Aikido uses to generate the change.

      Replace your base image with an Alpine Linux variant. For example, change 'FROM node:18' to 'FROM node:18-alpine'. You may need to adjust package installation commands from apt-get to apk.

   4. Click Save Rule to activate it

   Your custom rule will now appear in the Checks tab and begin scanning new pull requests in enabled repositories.

Writing effective Custom Rules

Be specific and clear

❌ Too vague:

Use proper error handling

✅ Specific and actionable:

All API endpoints must wrap database calls in try-catch blocks and return 
standardized error responses with status codes

Focus on patterns, not style

Custom rules work best for detecting logical patterns rather than formatting:

✅ Good custom rule candidates:

• API authentication requirements
• Database transaction patterns
• Security header implementations
• Business logic validations

❌ Better handled by linters:

• Indentation and spacing
• Bracket placement
• Variable naming style

Common Custom Rule examples

Security rules

All SQL queries must use parameterized statements. Direct string 
concatenation in SQL queries is not allowed.

Architecture rules

Controllers should not directly access the database. All database 
operations must go through a service or repository layer.

API standards

All REST API endpoints must include rate limiting headers 
(X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset).

Testing requirements

Every exported function must have at least one corresponding test 
in the __tests__ directory with the same file name pattern.

Documentation standards

All public API methods must include JSDoc comments with @param, 
@returns, and @throws annotations.