Your First Task¶

Let's try the system with real examples to see how guardrails work in practice.

Example 1: Bug Fix (ATOMIC Mode)¶

Scenario: A button is misaligned on the profile page.

Your Prompt¶

Fix the profile edit button - it's misaligned on mobile screens

What AI Does¶

1. Deconstruct: Single file change, CSS/styling issue
2. Diagnose: Check responsive breakpoints, flexbox/grid usage
3. Develop: Apply fix, verify against design
4. Deliver: Test, commit with conventional message

Expected Behavior¶

AI should:

• Locate the relevant component file
• Identify the styling issue
• Apply a minimal fix (no over-engineering)
• Keep the file under 200 lines (component guardrail)
• Suggest a commit: fix(profile): align edit button on mobile screens

Example 2: Simple Feature (ATOMIC Mode)¶

Scenario: Add a "copy to clipboard" button.

Your Prompt¶

Add a copy-to-clipboard button for the API key display in settings

What AI Does¶

1. Deconstruct: New button + click handler + feedback
2. Diagnose: Check existing button patterns, clipboard API support
3. Develop: Implement with proper error handling
4. Deliver: Add test, validate, commit

Expected Behavior¶

AI should:

• Use existing button component (if available)
• Handle clipboard API errors gracefully
• Show user feedback (toast/tooltip)
• Follow TypeScript strict mode (no any)
• Add unit test for the click handler
• Commit: feat(settings): add copy-to-clipboard for API key

Example 3: Multi-File Feature (FEATURE Mode)¶

Scenario: Add user avatar upload.

Your Prompt¶

Add avatar upload to user profile - allow jpg/png, max 2MB,
show preview before upload

What AI Does¶

1. Deconstruct: Break into subtasks
2. File input component
3. Preview component
4. Validation logic
5. Upload API call
6. Error handling
7. Diagnose: Check existing upload patterns, API endpoints
8. Develop: Implement each subtask with tests
9. Deliver: Integration test, document, commit each step

Expected Behavior¶

AI should:

• Break into 3-5 subtasks
• Implement sequentially (not all at once)
• Validate file type and size (security guardrail)
• Keep each file under 300 lines
• Add tests for validation logic
• Multiple commits, one per logical change

Example 4: Complex Feature (COMPLEX Mode)¶

Scenario: Build a notification system.

Your Prompt¶

@.claude/skills/create-prd/SKILL.md
Build a notification system with:
- In-app notifications
- Email notifications (optional)
- User preferences for notification types

What AI Does¶

1. Asks clarifying questions (PRD workflow)
2. Creates PRD in .claude/tasks/
3. Generates task breakdown (20-50 subtasks)
4. Implements step-by-step with verification

Expected Behavior¶

AI should:

• Ask about notification types, delivery methods, storage
• Create PRD document with all sections
• Generate numbered task list
• Wait for approval before implementing
• Track progress in .claude/state.md (if multi-session)

Verifying Guardrails Work¶

Security Check¶

Try this prompt:

Create a function that queries the database for a user by email

AI should:

• Use parameterized queries (not string concatenation)
• Validate email input
• Handle errors properly

If AI writes WHERE email = '${email}', remind it: "Check security guardrails in CLAUDE.md"

Code Quality Check¶

Try this prompt:

Write a function that processes order data with all business rules

AI should:

• Keep function under 50 lines
• Extract complex logic to helper functions
• Add type signatures
• No magic numbers

If the function exceeds 50 lines, AI should automatically refactor.

Testing Check¶

Try this prompt:

Add a new utility function to format currency

AI should:

• Create the function
• Create test file alongside
• Test edge cases (null, negative, large numbers)
• Aim for >80% coverage

Common Issues¶

AI Doesn't Follow Guardrails¶

Solution: Explicitly remind it

Follow the guardrails in CLAUDE.md. Specifically:
- Functions must be ≤50 lines
- All inputs must be validated
- Add tests for the new code

AI Skips Tests¶

Solution: Be explicit

After implementing this feature, add unit tests.
Target >80% coverage for the new code.

AI Over-Engineers¶

Solution: Request simplicity

Keep this simple - minimal implementation that meets the requirements.
No extra features or "nice-to-haves".

AI Makes Large Commits¶

Solution: Request atomic commits

Implement this in small steps. Commit after each logical change.
Use conventional commit format.

Practice Prompts¶

Try these prompts to get comfortable with the system:

Beginner¶

1. "Fix the typo in the README.md file"
2. "Add a loading spinner to the submit button"
3. "Update the copyright year in the footer"

Intermediate¶

1. "Add form validation to the contact form (email required, message min 10 chars)"
2. "Create a dark mode toggle that persists to localStorage"
3. "Add pagination to the blog posts list"

Advanced¶

1. "Refactor the API service to use a base HTTP client class"
2. "Add rate limiting to the public API endpoints"
3. "@.claude/skills/create-prd/SKILL.md - Build a search feature with filters"

What You Learned¶

After completing these examples, you should understand:

• ATOMIC mode for small, focused changes
• FEATURE mode for multi-file features
• COMPLEX mode with PRD workflow for large features
• How guardrails are enforced automatically
• How to remind AI when guardrails aren't followed

Next Steps¶