AI agent prompt for working in a codebase
Write a codebase prompt that tells an AI agent how to inspect files, respect architecture, edit safely and verify changes.
Quick answer
A good codebase prompt defines architecture rules, edit constraints, verification commands, security boundaries and how the agent should summarize work.
What to include
Include stack, folder rules, data boundaries, auth rules, formatting commands, test commands and rules for handling dirty git worktrees.
What to avoid
Avoid vague prompts like be careful. Give concrete constraints the agent can obey and verify.
FAQ
Should prompts include test commands?
Yes. The agent needs to know the exact local checks that prove a change is safe.
Build a project prompt
Related guides
CLAUDE.md: A Guide for Every Developer
One markdown file that makes AI coding assistants actually understand your codebase. Here's what to put in it.
There's a reason Claude Code writes great code in some projects and generic boilerplate in others. It's not the model. It's CLAUDE.md . It is one part of my Claude Code workflow: project conventions reduce guesswork, but they do not guarantee a speedup or remove the need to review the change. What it is CLAUDE.md is a plain markdown file that Claude Code reads at the start of every session. Think of it as the onboarding doc you'd give a senior contractor on day one: stack, conventions, rules, context. Without it, Claude infers patterns from what it sees in the codebase. Sometimes it infers correctly. Often it doesn't especially for implicit conventions your team just "knows". With a good CLAUDE.md , Claude outputs code that follows your rules without being told each time. What to put in it 1. Stack and versions Simple but important. Claude will use the right…
Read the guidePrompt vs Workflow vs Agent
Everyone is calling everything an agent. Here's what actually separates the three, and why it matters when you're building.
The word "agent" is everywhere. So is "workflow". People use them interchangeably, which means everyone is confused and half the things called agents are just prompts with extra steps. Here's a clean mental model I use. It's not the academic definition it's the practical one. A prompt A prompt is a single call to an LLM. Input goes in, output comes out. That's it. No loops. No decisions. No tools. One round trip. Most "AI features" shipped in 2023 were prompts. They're underrated a well crafted prompt can do a lot. But they're fundamentally one shot and stateless. A workflow A workflow is a sequence of steps some of which may call an LLM executed in a predetermined order. The structure is defined by the developer, not the LLM. Example: a content repurposing workflow. 1. Receive a LinkedIn post (trigger) 2. Call Claude to rewrite as a Twitter thread 3.…
Read the guideClaude Code Plan Mode: A Practical Guide
Claude Code Plan Mode lets you review and steer a task plan before any file is touched. Full guide: shortcut (Shift+Tab), activation, when to use it, and how to execute the plan.
Most people use Claude Code like a chat: describe the task, watch it execute. That works for small changes. For anything touching more than two files, there's a better path. If you are looking for the shortcut, press Shift+Tab to toggle Plan Mode. To turn it off, press Shift+Tab again or use /plan only for the prompt that needs planning. The dedicated Plan Mode troubleshooting guide covers the common terminal and version issues. Plan Mode. What Plan Mode does When you activate Plan Mode, Claude reads your codebase and produces a step by step execution plan but makes no changes. You see exactly what it intends to do before a single file is written. This gives you a checkpoint: approve the plan, redirect it, or catch a wrong assumption before it cascades into 15 wrong edits. How to activate Plan Mode the shortcut Two ways: Keyboard shortcut : press Shift+Tab…
Read the guide