Concept 10: Communication with AI

Introduction

The difference between frustrated developers and productive vibe engineers? Prompting.

Bad Prompting: "Make my game better" -> Vague responses, wasted time

Good Prompting: "Add difficulty selector (Easy/Medium/Hard buttons) that filters word list in Spelling Bee. Click updates currentDifficulty, refreshes word pool." -> Precise code, first-try solutions

For complex features (authentication, databases, multi-component systems), you'll need advanced strategies that break down complexity, maintain consistency, and guide AI through architectural decisions.

You'll master: avoiding anti-patterns, writing specific prompts, managing context, creating agent.md documentation, and orchestrating multi-step workflows.

Learning Objectives

By the end of this lesson, you will:

• Avoid anti-patterns, write specific prompts, manage context efficiently
• Create agent.md documentation for project knowledge
• Decompose complex features, use chain-of-thought for architecture, apply few-shot learning for consistency

Part One: Prompting Anti-Patterns (15 minutes)

Anti-patterns waste time and produce poor results.

Anti-Pattern #1: The Vague Request

❌ "Make my game better" -> AI doesn't know what "better" means.

✅ Better: "Fix the scoring bug where users get negative points after using more than 3 hints. Here's calculateScore(): [paste code]. Expected: Score never goes below 0."

Anti-Pattern #2: The Single-Word Command

❌ "Debug" -> No error or context provided.

✅ Better: "Getting TypeError: Cannot read property 'toLowerCase' of undefined at checkAnswer (game.js:47) when clicking Submit. Here's checkAnswer(): [paste code]. Expected: Check if answer is correct."

Anti-Pattern #3: The Assumption Trap

❌ "Add authentication" -> AI assumes OAuth/database when you wanted simple localStorage.

✅ Better: "Add username/password auth using localStorage (no database). Login form with two inputs, persist session on refresh. Files: index.html, chat.js, style.css. Create new auth.js for login logic. This is a student project."

Anti-Pattern #4: The "Fix It" Paradox

❌ "My code doesn't work. Fix it." -> AI can't see your code or symptoms.

✅ Better: "filterWords() not working-selecting 'Easy' still shows Medium/Hard words. [paste filterWords() and click handler]. Expected: Only easy words. Actual: All difficulties. No console errors."

Anti-Pattern #5: The Feature Dump

❌ "Add hints, scoring, timer, difficulty, animations, sounds, profiles, sharing" -> Too much at once.

✅ Better: "Add hint system only (other features later). Requirements: 1) 'Get Hint' button reveals first letter, 2) 3 hints max, 3) Disable button after 3, 4) Track in gameState.hintsUsed. Current gameState: { score: 0, currentWord: {...}, hintsUsed: 0 }."

💡 Tip: If a new teammate wouldn't understand your prompt, neither will AI. AI needs: Specificity, Context, Examples, Constraints.

Part 2: Prompting Best Practices (20 minutes)

Best Practice #1: The Specificity Pyramid

Three levels: What (goal), How (approach/UX), Where (integration/files).

Example: Adding a Score Display

❌ Vague: "Add scoring"

✅ Specific:

WHAT: Add score display to Spelling Bee game
HOW: Show at top, update real-time, format "Score: 15 points", bold purple text
WHERE: HTML in index.html header, update in checkAnswer() (game.js), style in style.css
Context: Current logic: +5 per correct answer (working)

Best Practice #2: Break Complex Tasks into Steps

❌ Overwhelming: "Create difficulty selector with filtering, UI, localStorage, points"

✅ Step-by-Step: (1) Create buttons HTML+CSS, (2) Add click handlers + active styling, (3) Create filterWordsByDifficulty() function

Best Practice #3: Provide Examples

❌ "Create word list" -> Basic array

✅ "Create word list. Each: { word: 'algorithm', difficulty: 'hard', definition: '...' }. 5 per difficulty (15 total)" -> Perfect structure

Best Practice #4: Specify Output Format

❌ "Create score function" -> Inconsistent style

✅ "Create calculateScore() as ES6 arrow, params (correct, incorrect, hintsUsed), formula: correctx5 + incorrectx-2 + hintsUsedx-3, JSDoc included" -> Exact format

Best Practice #5: Show, Don't Tell

❌ "Match my style" -> AI guesses

✅ "Match this: startGame = () => { gameState.isPlaying = true; updateUI(); }. Use arrow functions, clear names, helper calls" -> Perfect match

Best Practice #6: State Constraints

❌ "Add auth" -> 300 lines of backend complexity

✅ "Add simple auth. CONSTRAINTS: NO backend/database (use localStorage), NO libraries, under 50 lines. Requirements: login form, persist session" -> Simple solution

The Prompting Template

• Goal: What to build/fix
• Requirements: 3-5 specifics
• Context: File structure, existing code, data formats
• Constraints: What NOT to do
• Expected Output: Success criteria

Part 3: Context Management (15 minutes)

Context is AI's "working memory": chat history, files, code snippets, errors, and documentation. Managing it well makes AI 10x more helpful.

What Is Context?

The Context Window (AI's memory limit):

• Claude Sonnet: 200K tokens (~600 pages)
• GPT-4: 128K tokens (~384 pages)
• Claude Haiku: 48K tokens (~144 pages)

Exceeding it? AI "forgets" older conversation-context management matters!

Best Practices:

1. Select Only Relevant Files: Send game.js + index.html only (not all 20 files) -> faster response
2. Paste Complete Error Messages: Uncaught TypeError at checkAnswer (game.js:47) (not "I'm getting a TypeError")
3. Strategic File Selection: For "Add timer"-send game.js (logic), index.html (display), style.css (styling); skip words.js (data), images (AI can't process)
4. Start Fresh When Needed: After 30+ messages or when AI references old code
5. Token Efficiency: "Change button color on click. Current: <button>. Goal: Green." (not "Hey there! I hope you're having a great day...")

💡 Tip: Context is like recipe ingredients-too little fails, too much confuses, just right produces perfect results.

Part 4: Agent.md Documentation (10 minutes)

agent.md is a secret weapon that makes AI feel like it already knows your project.

What Is agent.md?

agent.md (or AGENT.md, .ai/agent.md) is a file you create at the root of your project that documents:

• Project structure
• Coding conventions
• Common patterns
• Known issues
• Setup instructions

Why it matters: When you reference agent.md in your prompts (@agent.md), AI reads it and understands your project context instantly-without you explaining everything each time.

What to Include in agent.md

One. Project Overview: Name, description, tech stack

2. File Structure: List files with brief descriptions

3. Coding Conventions: Function style, naming, formatting preferences

4. Data Structures: Key object shapes with example formats

5. Known Issues: Documented bugs and planned fixes

6. Setup Instructions: How to run, test, and reset

Using agent.md in Prompts

Example One: Adding a Feature

"@agent.md Add 'Clear History' button below chat input.
Follow project conventions."

AI knows: Arrow functions, const/let, green theme, under 30 lines, localStorage usage

Example 2: Debugging

"@agent.md Knowledge base search not finding responses.
Known issue #2 mentions case-sensitivity. Fix it."

AI knows: Knowledge base structure, keywords array format, exact fix needed

Real agent.md Example: Smart Farm Project

# Smart Farm Chatbot - Agent Instructions

## Project Description
Agricultural chatbot for beginner farmers. Answers questions about crops, watering, pests, and farming techniques.

## Tech Stack
- Vanilla JavaScript (ES6), HTML5, CSS3
- localStorage (no backend)

## File Structure
/smart-farm/
├── index.html (main page)
├── chat.js (chatbot logic)
├── knowledge.js (JSON knowledge base)
├── style.css (styling)
├── utils.js (helpers)
└── agent.md (this file)

## Code Style
- Arrow functions: `const functionName = () => {}`
- No semicolons, CamelCase variables, Template literals, Destructuring

## Data Structures
### chatHistory (localStorage)
[{ id: "1", sender: "user", text: "...", timestamp: 123456 }]

### knowledgeBase (knowledge.js)
[{ topic: "Watering", keywords: ["water"], response: "...", expertise: "beginner" }]

## Key Functions
- `sendMessage()`, `findResponse()`, `displayMessage()`, `saveToHistory()` (chat.js)
- `formatTimestamp()`, `clearHistory()` (utils.js)

## Known Issues
1. Search is case-sensitive (needs toLowerCase())
2. No input validation
3. Knowledge base has only 10 topics

## Important Context
- Student project (keep simple)
- No external APIs (offline-first)
- Focus on educational value

Benefits of agent.md

Without agent.md: "Add export chat history" -> AI suggests Node.js + database (wrong tech stack)

With agent.md: "@agent.md Add export chat history" -> AI generates frontend-only solution (arrow functions, localStorage, Blob download, follows conventions)

When to Update agent.md

Update when: adding files/features, discovering patterns, fixing recurring issues, changing data structures, adding dependencies.

Keep it current! Outdated agent.md is worse than none.

💡 Tip: Start agent.md on Day 1. 10 minutes documenting structure/conventions. Update as you go. By Week 2, it's invaluable.

Part 5: Advanced Prompting Strategies (25 minutes)

Complex features (authentication, databases, multi-component systems) require advanced strategies that break down complexity, maintain consistency, and guide AI through architectural decisions.

Strategy #1: Feature Decomposition (5-7 Prompts)

Break features into testable steps:

1. Setup & Structure
2. Core Logic
3. Integration
4. UI Components
5. Error Handling
6. Polish
7. Testing

Example: "User Authentication"

❌ Single prompt: "Add user authentication" -> 300+ untested lines with style conflicts

✅ Decomposed:

Results: Testable at each step-if Step 5 breaks, you know exactly where vs. debugging 300+ lines.

Strategy #2: Chain-of-Thought Prompting

Ask AI to "think step-by-step" for architectural decisions. Skip for simple code generation.

Example: Choosing State Management

"Help me choose Redux vs Zustand.

Think step-by-step:
1. Key differences?
2. My project: auth, shopping cart, product catalog, order history
3. Team: solo, 3 weeks to MVP
4. Experience: React hooks, never used Redux

Based on this, what's better for my situation?"

AI analyzes: Differences -> needs -> constraints -> recommends Zustand + React Query with reasoning (not generic "use Zustand" advice).

Template:

"[Decision question]

Think step-by-step:
1. [Requirements]
2. [Constraints]
3. [Tradeoffs]

Context: [3 specific details]

What do you recommend?"

Strategy #3: Few-Shot Learning for Consistency

Show 2-3 code examples instead of describing style.

Example: Matching Function Style

❌ Without: "Create email validation" -> AI might use function declarations

✅ With examples:

"Create validateEmail matching my style.

Examples from my codebase:
const hashPassword = (password: string): string => {
  return btoa(password);
};

const formatDate = (timestamp: number): string => {
  return new Date(timestamp).toLocaleDateString();
};

Pattern: Arrow functions, TypeScript types, verbNoun names

Now create validateEmail following this pattern."

AI generates: const validateEmail = (email: string): boolean => { ... } (perfect match!)

Template: Show 2-3 examples -> List patterns -> Request new code

Multi-Step Workflow: "Shopping Cart Feature"

Step 1 (Chain-of-Thought): "Think step-by-step: cart state, refresh handling, guest users. Context: Zustand, Firebase, guest checkout." -> AI recommends Zustand + localStorage for guests, Firebase sync for logged-in.

Step 2 (Decompose): 7 prompts: Cart types -> Zustand slice -> localStorage -> Firebase sync -> CartDrawer UI -> Add to Cart button -> Checkout flow.

Step 3 (Few-Shot): "Create cartSlice matching [paste authSlice/productSlice examples]" -> Consistent style.

Results: Architecturally sound, manageable scope, consistent, testable-70% faster than single prompts.

Summary

You mastered AI communication from basics to advanced multi-step orchestration:

Anti-Patterns (What NOT to Do):

• ❌ Vague requests, single-word commands, assumptions, "fix it" without context, feature dumps

Best Practices:

• ✅ Specificity pyramid (What, How, Where)
• ✅ Break into steps, provide examples, specify format, show don't tell, state constraints

Context Management:

• Select relevant files, paste complete errors, use "Send to Chat" strategically, start fresh when needed, optimize tokens

agent.md Documentation:

• Project overview, file structure, conventions, data structures, known issues-reference with @agent.md

Advanced Strategies:

• Feature Decomposition: 5-7 prompts (Setup -> Core -> Integration -> UI -> Error Handling -> Polish -> Testing)
• Chain-of-Thought: "Think step-by-step" for architectural decisions
• Few-Shot Learning: Show 2-3 examples for consistency
• Multi-Step Workflow: Combine all three for complex features

Next Steps

In Activity 10, you'll practice these techniques on real scenarios-from basic debugging to advanced feature decomposition.

Key Takeaways

💡 Remember: Good prompting = right information at the right level of detail.

Prompting Mindset:

• "What would a teammate need to know?"
• "Am I giving enough context without overwhelming?"
• "Can I break this into testable steps?"
• "What constraints prevent over-engineering?"

The 3 C's:

1. Clear - Specific goals/requirements
2. Concise - No fluff
3. Complete - Context, constraints, examples

For Complex Features:

• Plan 5-7 prompts before starting
• Use chain-of-thought for architecture
• Show examples for consistent style
• Test incrementally

Practice makes perfect. Pay attention to which prompts get first-try results-and learn from them!