Web Application Development
Introduction
Before starting any work on the application development using Agentic AI (Claude), we should prepare the Agent for the job which can be done by manually building the context for the AI consumption. This sets the clear path to our AI on what the requirements and the goals are. There are few files I should be creating before starting delegating a job to the AI which can be -
README.md — the "what is this" fileWhat the app does · who it's for · core problem it solvesTech stack (e.g. React + Node + PostgreSQL) · deployment targetLinks to live URL, repo, design docs if anyClaude reads this first to understand what you're building.
ARCHITECTURE.md — the "how it's built" fileFolder structure and what lives whereKey components / pages / modules and their rolesHow data flows (e.g. API → state → UI)Stops Claude from suggesting solutions that clash with your structure.
TASKS.md — the "what to do next" fileCurrent sprint / active features being builtKnown bugs or blockersBacklog items (future ideas, not current focus)Update this every session — it becomes Claude's task board
CONVENTIONS.md — the "how we write code" fileNaming conventions (camelCase, kebab-case, PascalCase?)File naming rules (e.g. components in PascalCase.jsx)State management approach · error handling patternsComment style, linting rules, formatting (Prettier, ESLint config?)Keeps Claude's code consistent with yours across sessions
CLAUDE.md — the "instructions for Claude" file ⭐Which files to read at the start of each sessionYour preferred coding style ("always explain changes", "keep it simple")What NOT to do ("don't change the auth module without asking")Key decisions already made ("we chose Supabase, not Firebase")How to handle uncertainty ("ask before adding new dependencies")Start every Claude session by sharing this file. It's your standing prompt.
The 5 files and what goes in them
README.md — write this like you'd explain your app to a developer friend in 2 minutes. What it does, who uses it, your stack.
ARCHITECTURE.md — paste your folder tree (src/components/, src/pages/, etc.) and write one line explaining each folder's job. Add a brief data flow description.
TASKS.md — treat this like a lightweight Jira. Keep a "doing now", "up next", and "backlog" section. Update it as you go.
CONVENTIONS.md — if you're using a framework like React or Next.js, note your preferred patterns. For example: "we use custom hooks for API calls, not inline fetch in components."
CLAUDE.md — this is the most important one. Think of it as a standing prompt you paste at the start of every session. Tell Claude your preferences, guardrails, and key decisions.
How a session should start
"Here's my CLAUDE.md — [paste]. I want to work on [specific task from TASKS.md] today."
That one habit will dramatically improve the quality and consistency of Claude's help across sessions.