{"slug": "3-files-every-ai-assisted-project-needs-before-you-write-a-line-of-code", "title": "3 Files Every AI-Assisted Project Needs Before You Write a Line of Code", "summary": "A developer argues that AI-assisted projects need three files—`CLAUDE.md`, `.cursorrules`, and a streamlined `README.md`—created before any application code is written. These files form a \"triangle\" that defines the project's context and rules, preventing the AI from making incorrect assumptions or working against the developer's intent. The setup takes 20-30 minutes but ensures the AI builds within the developer's defined constraints rather than guessing independently.", "body_md": "Most developers think of project setup as: install dependencies, configure TypeScript, set up linting.\n\nThat is the wrong order. The AI-native setup order is different, and skipping it means your AI assistant works against your project instead of with it.\n\nHere are the three files that should exist before you write a line of application code.\n\n`CLAUDE.md`\n\nis a markdown file at your project root that Claude Code loads as a system prompt prefix on every session. Think of it as the briefing document your AI assistant reads before touching your codebase.\n\nA minimal `CLAUDE.md`\n\nfor a new project:\n\n```\n# Project: My SaaS App\n\n## Stack\nNext.js 15, TypeScript strict, Prisma + PostgreSQL, Tailwind CSS\n\n## Rules\n- No `any` types. No unvalidated JSON.parse().\n- Auth via NextAuth.js. Never roll custom auth.\n- DB access only in `src/services/` — never in route handlers directly.\n- Run `npm run typecheck` before declaring a fix done.\n\n## Deploy\nVercel. Main branch auto-deploys. Staging on `preview` branches.\n```\n\nTen lines. That is enough to prevent 80% of the decisions where the AI would otherwise guess wrong.\n\n**Why write this before any code?** Because when you write it after, you are describing what you accidentally built rather than what you intended. The instruction layer should drive the codebase, not document it retroactively.\n\nIf you use Cursor, `@.cursorrules`\n\nloads into Cursor's context. It is similar to `CLAUDE.md`\n\nbut optimized for Cursor's behavior — shorter, more rule-focused, less narrative.\n\nThe key difference from `CLAUDE.md`\n\n: `CLAUDE.md`\n\ncan afford to be contextual (\"we use Prisma because our team knows it\"). `@.cursorrules`\n\nshould be purely prescriptive (\"never write raw SQL; use Prisma query builders\").\n\nKeep them in sync. If you update the auth pattern in one, update the other. Two source-of-truth files with the same content that drift apart are worse than one.\n\nA clean pattern: have `CLAUDE.md`\n\nbe the canonical source. In `.cursorrules`\n\n, reference it and add only Cursor-specific formatting rules:\n\n```\nProject context: see CLAUDE.md at repo root.\n\nAdditional Cursor rules:\n- Auto-import from absolute paths, not relative.\n- Prefer named exports over default exports.\n- Format with Prettier on save — do not manually align anything.\n```\n\nFour lines. Everything else lives in `CLAUDE.md`\n\n.\n\nThis one surprises people. The README is not for human readers — it is for your AI assistant's cold-start.\n\nWhen you open a new Cursor session or start a new Claude Code chat, the AI does not remember anything from yesterday. The README is the document it will read first if you paste it in, and it is what future agents (or you, in three months) will read to understand how the project works.\n\nA README that serves as an AI onboarding document:\n\n```\n## Quick context\nSaaS app for indie devs. Subscription billing via Stripe, auth via NextAuth.js,\ndatabase via Prisma + PostgreSQL on Neon.\n\n## Local setup\nnpm install && cp .env.example .env.local && npx prisma migrate dev\n\n## Project structure\nsrc/\n  app/          Next.js App Router pages\n  services/     Business logic — no HTTP here\n  components/   React components — no data fetching here\n  lib/          Utilities and config\n\n## Common tasks\nRun dev: npm run dev\nRun types: npm run typecheck\nRun tests: npm test\nDeploy: push to main\n```\n\nNo fluff. No marketing copy. Just: what is this, how do I start it, what is where.\n\nThese three files form a triangle:\n\n`CLAUDE.md`\n\ntells the AI `.cursorrules`\n\ntells the AI `README.md`\n\ntells the AI When all three are in place before you write application code, you are building inside a defined context. The AI works with your decisions instead of making its own.\n\nWhen none of them are in place, you are doing vibe coding in the wrong direction — the AI is building something, and you are figuring out what it is as you go.\n\nSetting these three files up for a new project takes 20-30 minutes if you are doing it from scratch. Doing it for 12 different tech stacks (Next.js SaaS, Express + JWT, FastAPI, Discord Bot, Chrome Extension, and more) takes considerably longer.\n\nThe [Vibe Coder Kit](https://blncraft.gumroad.com/l/vibe-coder-kit) packages 12 production-configured starters where all three files are already in place and consistent with the actual codebase. You clone, run the setup command, and your AI assistant is already briefed.\n\nAt the end of your next project setup, ask: \"If a new developer (or a new AI session) opened this repo with no context, could they figure out what it is, how to run it, and how to work in it?\"\n\nIf the answer is yes, you have done the setup right.\n\n*BLN Craft builds developer tools for AI-native workflows. Find us at blncraft.com.*", "url": "https://wpnews.pro/news/3-files-every-ai-assisted-project-needs-before-you-write-a-line-of-code", "canonical_source": "https://dev.to/blncraft/3-files-every-ai-assisted-project-needs-before-you-write-a-line-of-code-4k4d", "published_at": "2026-05-29 23:06:11+00:00", "updated_at": "2026-05-29 23:42:18.213451+00:00", "lang": "en", "topics": ["ai-tools", "ai-products", "artificial-intelligence", "large-language-models"], "entities": ["Claude Code", "Cursor", "Next.js", "Prisma", "PostgreSQL", "Tailwind CSS", "NextAuth.js", "Vercel"], "alternates": {"html": "https://wpnews.pro/news/3-files-every-ai-assisted-project-needs-before-you-write-a-line-of-code", "markdown": "https://wpnews.pro/news/3-files-every-ai-assisted-project-needs-before-you-write-a-line-of-code.md", "text": "https://wpnews.pro/news/3-files-every-ai-assisted-project-needs-before-you-write-a-line-of-code.txt", "jsonld": "https://wpnews.pro/news/3-files-every-ai-assisted-project-needs-before-you-write-a-line-of-code.jsonld"}}