Designing AI-Compatible Code

There’s a lot of writing out there on prompt engineering and model selection in pursuit of making AI agents smarter and more self-directed software engineers, but I’ve found that isn’t always enough to get consistently helpful results, especially when you’re trying to use AI to update older, more complex codebases alongside human engineers. The structure and style of your code can make a huge difference in how well AI can understand and intelligently extend it.

I’m not saying you need to go refactor everything right now, but if you’ve been feeling like your AI engineer is acting less like an expert and more like a junior intern, then gradually incorporating these ideas into your existing code will likely help.

The following code architecture and design guidelines are based on my personal experience using AI to edit existing projects and to clone and extend templates into new projects, ordered purely by my own raw gut feeling of how important they are:

Core Principles

1. Use Common Libraries and Patterns

Choose well-documented, mainstream technologies over custom solutions
Follow established approaches (MVC, Repository structures, React patterns) that AI recognizes
Use standard naming conventions for your language/framework
Stick to idiomatic code rather than clever implementations

2. Modular File Structure

Create many small, focused files (200-300 lines max)
Use nested directories that reflect logical relationships
Group by feature, not file type
One primary responsibility per file

src/
├── components/authentication/
│   ├── login-form.component.ts
│   └── registration-form.component.ts
├── services/user-management/
│   ├── user-profile.service.ts
│   └── user-preferences.service.ts
└── utils/validation/
    ├── email-validator.util.ts
    └── password-strength-validator.util.ts

3. Extremely Descriptive Names

Use verbose, self-documenting names that explain purpose and context
Include units, types, and constraints when relevant
Don't worry about name length - clarity over brevity

// Good
const authenticatedUserWithPermissions = await fetchUser();
const isEmailAddressFormatValid = validateEmail(email);
const convertRawApiResponseToUserProfileData = (response) => { ... };

// Avoid
const user = await fetchUser();
const isValid = validateEmail(email);
const processData = (response) => { ... };

4. Comprehensive Documentation

Add docstrings to all functions, classes, and complex logic
Include parameter types, return values, and usage examples
Document business logic and decision reasoning
Add inline comments for non-obvious code sections

/**
 * Validates user email format and checks against blacklisted domains
 * @param emailAddress - The email address to validate
 * @param checkBlacklist - Whether to check against domain blacklist
 * @returns True if email is valid and not blacklisted
 * @example validateUserEmailAddress('user@example.com', true)
 */
export const validateUserEmailAddress = (
  emailAddress: string,
  checkBlacklist: boolean = true
): boolean => {
  // Check basic email format first
  const emailRegexPattern = /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/;

  if (!emailRegexPattern.test(emailAddress)) {
    return false;
  }

  // Optional blacklist check for spam domains
  if (checkBlacklist) {
    return !isEmailDomainBlacklisted(emailAddress);
  }

  return true;
};

5. Centralize Shared Logic and Config

Extract all configuration into dedicated files, even if used in one place
Create utility functions for any logic that could be reused
Use clear, descriptive configuration objects

// config/database.config.ts
export const DATABASE_CONFIG = {
  connectionTimeoutMs: 5000,
  maxRetryAttempts: 3,
  productionPoolSize: 20,
  developmentPoolSize: 5
};

// utils/email-validation.util.ts
export const validateEmailAddressFormat = (email: string): boolean => {
  // Implementation here
};

Additional Best Practices

Use TypeScript or similar type systems for better AI understanding
Include README files in each major directory explaining purpose
Maintain consistent code formatting with automated tools
Use meaningful commit messages that explain the "why" not just "what"
Include unit tests with descriptive test names that explain expected behavior

A final word of caution

You can of course use AI to implement these changes, but make sure to double check these types of changes, as mistakes here can be pernicious hard to find.

veganbeef