Three Files to Guide AI Before Writing Code

A dev.to founder proposes an AI-native project setup, prioritizing explicit instruction files over traditional configurations. This reordered approach aims to prevent common AI missteps from the outset.

The founder behind dev.to argues that the conventional project setup sequence, typically focused on installing dependencies and configuring linting, is fundamentally misordered for AI-assisted development. This perspective posits that skipping an "AI-native setup order" means an AI assistant will work against a project's intent. The proposed solution involves establishing three specific files before any application code is written, aiming to prevent 80% of decisions where the AI would otherwise guess incorrectly, according to the source.

CLAUDE.md: The Instruction Layer

CLAUDE.md is positioned as the primary instruction layer. It is a Markdown file located at the project root, designed to be loaded by Claude Code as a system prompt prefix for every session. The source describes it as the briefing document an AI assistant reads before interacting with the codebase. This file explicitly defines the project's technical stack, architectural rules, and deployment environment. For example, a minimal CLAUDE.md specifies "Next.js 15, TypeScript strict, Prisma + PostgreSQL, Tailwind CSS" for the stack.

Crucially, CLAUDE.md enforces specific coding rules: "No any types. No unvalidated JSON.parse(). Auth via NextAuth.js. Never roll custom auth. DB access only in src/services/ — never in route handlers directly." It also includes a directive to "Run npm run typecheck before declaring a fix done." The rationale for writing this file before any code is that it allows the instruction layer to drive the codebase's development, rather than retroactively documenting what was accidentally built. This proactive guidance, even in a ten-line file, is intended to preempt numerous architectural and stylistic inconsistencies.

.cursorrules: The Tool Layer

The .cursorrules file serves as the tool-specific instruction layer, optimized for Cursor. While similar in purpose to CLAUDE.md, its content is shorter and more rule-focused, less narrative. The key distinction is that CLAUDE.md can provide context, such as "we use Prisma because our team knows it." In contrast, .cursorrules should be purely prescriptive, stating, "never write raw SQL; use Prisma query builders."

The founder emphasizes the importance of keeping these two files synchronized. Allowing two sources of truth to drift apart is considered worse than having a single, less comprehensive file. A clean pattern suggested is to designate CLAUDE.md as the canonical source. The .cursorrules file then references CLAUDE.md and adds only Cursor-specific formatting rules. Examples include "Auto-import from absolute paths, not relative," "Prefer named exports over default exports," and "Format with Prettier on save — do not manually align anything." This approach keeps the .cursorrules file concise, often just four lines, with the bulk of the project's guidance residing in CLAUDE.md.

README.md: The Onboarding Layer

The third file in this AI-native setup is README.md, which the founder states is "not for human readers — it is for your AI assistant's cold-start." This redefines the traditional purpose of a README. When a new Cursor session or Claude Code chat begins, the AI does not retain memory from previous interactions. The README.md is designed as the document the AI will read first if pasted into a session. It also serves as the reference for future agents or even the human developer returning to the project after an extended period.

An AI-centric README.md provides quick context. For instance, it might state: "SaaS app for indie devs. Subscription billing via Stripe, auth via NextAuth.js, database via Prisma + PostgreSQL on Neon." This immediate overview helps the AI understand the project's domain and core technologies. The README.md also includes essential local setup instructions, such as npm install. By providing this foundational context upfront, the AI can begin work with a more informed understanding of the project's purpose and technical landscape.

What We'd Change

This playbook presents a clear methodology for integrating AI into the initial project setup, but it introduces specific dependencies and potential friction points. The approach is highly tailored to particular AI tools, namely Claude Code and Cursor. Adapting this strategy for other AI assistants, such as GitHub Copilot or custom fine-tuned models, would necessitate different file names, syntax, and integration methods, potentially fragmenting the instruction layer across various proprietary formats.

The proposed pattern of maintaining CLAUDE.md as the canonical source while referencing it in .cursorrules attempts to mitigate the

Pull quote: “”