AI-First Engineering

AI-First Engineering

AI-first engineering means we design systems and workflows so that AI is a core part of how we build, not an afterthought.

Design for AI

Codebases are structured and documented so that AI tools (and agents) can navigate, suggest changes, and run checks. We favor clarity, tests, and explicit contracts.

File and module structure

Consistent structure helps both humans and AI find and change the right places. Example pattern we use for feature modules:

src/
  features/
    feedback/
      api.ts          # API client and types
      FeedbackForm.tsx
      feedback.test.ts
      index.ts        # public exports only
  lib/
    utils.ts

• One feature per folder; index.ts defines the public API so AI doesn’t need to guess what to import.
• Tests next to the code so “add a test” has clear context.

Docstrings and JSDoc

We add brief JSDoc for public functions and non-obvious logic. That gives AI (and humans) context without opening many files.

/**
 * Parses and validates the page size from query or body.
 * @param input - Raw value from request (string or number)
 * @returns Number between 1 and 100
 * @throws If input is missing or out of range
 */
export function parsePageSize(input: unknown): number {
  // ...
}

AI can then suggest correct usage and error handling; reviewers can check behavior against the contract.

Types and contracts

We use TypeScript (or equivalent) and explicit types at boundaries. That reduces “guess what this accepts” and makes AI-generated code more likely to match our API.

// Clear contract: input and output types
export type GetDocsOptions = {
  slug: string[];
  pageSize?: number;
};

export type DocPage = {
  title: string;
  description: string | null;
  slug: string[];
};

Tooling

We adopt and standardize on AI-assisted IDEs, code review tools, and automation. Configs and conventions are shared so onboarding is fast.

Quality bar

The bar for correctness, security, and performance does not drop because AI is involved. Human review and ownership remain.

See also