AI is Not Magic
The single biggest mistake beginners make is treating AI like a mind-reader. They write vague prompts and expect perfect results. When results are wrong, they conclude "AI is bad." The real issue is that the AI only knows what you tell it.
An LLM (Large Language Model) like Claude is a statistical prediction engine. It predicts the most probable sequence of words (tokens) that should follow your input, based on patterns learned from a massive amount of text including code. It is extraordinarily good at this - but it is prediction, not understanding.
# Vague - AI guesses what you mean (often wrong):
"Fix my code"
"Add authentication"
"Make it better"
# Somewhat clear - AI produces something generic:
"Write a login form in PHP"
"Add user authentication to my app"
# Precise - AI produces exactly what you need:
"In UserController.php, the login() method on line 34 fails with
'Undefined variable $remember' when the checkbox is unchecked.
Fix it to default $remember to false when the POST value is missing."
Rule: the more specific you are, the better the result.The Context Window
The context window is the AI's "working memory" - everything it can see at once during your session. Think of it as a whiteboard that can hold a finite amount of text.
Everything in the context window:
- Your CLAUDE.md (project background)
- All messages in the current conversation
- Any files the AI reads during the session
- All tool call results (grep output, test results, etc.)
Imagine hiring a contractor who can only work from the documents
you put on a table in front of them.
If you put 1 relevant document:
- They understand the task precisely
- Their work is focused and accurate
If you put 50 documents (most irrelevant):
- They must guess which ones matter
- They may use the wrong ones
- Their work is diluted and inconsistent
AI context works the same way.
Give the AI exactly what it needs - nothing more, nothing less.What the AI Actually Sees
When you type a prompt in Claude Code, here is what is actually sent to the AI model:
[SYSTEM PROMPT]
You are Claude Code, an AI coding assistant...
Project context from CLAUDE.md:
- PHP 8.2 web application
- MySQL database via PDO
- Bootstrap 5 frontend
[... rest of CLAUDE.md ...]
[CONVERSATION HISTORY]
User: Create a login form
Assistant: I'll create a login form. [reads auth.php...] Here is the form:
[the code it wrote]
User: The form submits but the session is not set
[CURRENT MESSAGE]
User: The form submits but the session is not set
[AVAILABLE TOOLS]
- Read file
- Write file
- Search (Grep)
- Run bash command
- Edit fileThe AI sees text, not your actual running application. It does not see your browser, your database state, or anything not explicitly in the context. This is why "the session is not set" is a better bug report than "it does not work."
Why AI Makes Mistakes
Understanding error types helps you fix them faster:
| Mistake type | Cause | Fix |
|---|---|---|
| Wrong assumption | AI guessed at unstated requirements | Be more specific in your prompt |
| Outdated approach | Training data had older patterns | Specify versions: "PHP 8.2, PDO not mysqli" |
| Hallucinated function | AI invented a function that does not exist | Test all AI code before trusting it |
| Context mismatch | AI read the wrong file or no files | Tell it exactly which file/line to look at |
| Cascading error | First output was wrong, AI built on it | Correct early; start a new session if stuck |
| Incomplete output | Output was cut off at context limit | Ask "continue from where you stopped" |
Giving Good Context
Four things to include in any prompt for better results:
1. WHERE: Which file, function, or line number
"In app/models/UserModel.php, the create() method..."
2. WHAT: What you want to happen
"...should validate that email is unique before inserting."
3. CONSTRAINT: What must not change or must be true
"Use the existing PDO connection ($this->db). Do not change the method signature."
4. OUTPUT: What you want back
"Show only the changed lines as a diff."
Combined example:
"In app/models/UserModel.php, the create() method should validate
that the email is unique before inserting. Use the existing PDO
connection ($this->db). Do not change the method signature.
Show only the changed lines as a diff."Iteration is Normal
Professional AI users iterate constantly. The AI is rarely perfect on the first try for complex tasks - and that is expected. Each iteration adds context and brings the output closer to what you need.
Turn 1: "Create a user registration form in PHP with email and password"
-> AI creates a form. Good structure but no validation.
Turn 2: "Add validation: email must be valid format, password minimum 8 chars"
-> AI adds validation. Works but error messages are in English.
Turn 3: "Change error messages to Tamil. Email: 'சரியான மின்னஞ்சல் முகவரியை உள்ளிடவும்'"
-> AI updates messages. Done.
This 3-turn exchange took 3 minutes total.
Without AI it would have taken 45 minutes.Do not try to write one perfect mega-prompt that covers everything. Start simple, get something working, then refine with follow-up prompts. This mirrors how you would work with a human developer - you do not email them a 500-word spec; you have a conversation.