human-code

Rules that make AI coding agents write code a person would write.

These are the engineering rules we use in every [Navulo](https://github.com/navulo) project. They are open, and you can use them in yours.

The problem

Claude Code, Codex, Cursor and other agents write code that works but is hard to live with. They:

• add layers, files and abstractions that the task does not need;
• comment every line, often with traces of the chat;
• guard against states that cannot happen, and hide real failures behind fallbacks;
• write a new helper instead of finding the one that already exists.

The last habit shows up in the data. [GitClear's analysis of commit histories](https://devclass.com/2025/02/20/ai-is-eroding-code-quality-states-new-in-depth-report/) found that as coding assistants spread, copy-pasted code grew and refactored code shrank.

Before and after

The task: show the user's name in the profile header.

Without the rules, an agent typically creates a new file:

// src/utils/userHelpers.ts
/**
 * Gets the display name for a user.
 * @param user - The user object
 * @returns The display name of the user
 */
export function getUserDisplayName(user: User | null | undefined): string {
  // Check if the user exists
  if (!user) {
    return "Unknown User";
  }
  try {
    // Combine the first and last name
    const fullName = `${user.firstName ?? ""} ${user.lastName ?? ""}`.trim();
    // Fall back to the email if the name is empty
    return fullName || user.email || "Unknown User";
  } catch (error) {
    console.error("Error getting display name:", error);
    return "Unknown User";
  }
}

With the rules, the agent finds `formatFullName` in `src/lib/user.ts`, which four other screens already use:

{formatFullName(user)}

Its report says: "Used `formatFullName` from `src/lib/user.ts`. `user` cannot be null here, because the route loader throws on 404."

The first version breaks six rules:

• it adds a new helper n