Prompting - Maestro

Master the art of directing AI coding agents for maximum productivity and quality outcomes.

The Mental Model

Think of Maestro as an over-confident, incredibly fast, and very literal developer.

This mental model is crucial for success. Maestro isn’t a magical oracle—it’s a powerful tool that requires clear direction, explicit constraints, and rigorous verification. Success doesn’t come from “clever” phrasing, but from engineering discipline: providing context, setting boundaries, and enforcing quality standards. Key principles:

Be direct and imperative - No hedging or excessive politeness
Provide complete context - Maestro only knows what you show it
Define constraints explicitly - State what NOT to do as clearly as what to do
Demand evidence - Never accept claims without proof

Core Philosophy

The primary friction point with coding agents is ambiguity. Agents crave specificity. To move from frustration to flow, adopt these foundational behaviors:

1. Be Imperative and Direct

Avoid hedging or politeness markers. Your agent does not need to be coaxed; it needs to be commanded. Avoid: “Can you maybe look into this bug?” Adopt: “Fix the null pointer exception in UserService.ts when email is undefined.”

2. Context is King

An agent only knows what you show it. You must curate its reality. When requesting a fix or feature, provide the “scene of the crime”: file names, error logs, stack traces, and relevant design constraints.

3. Constraints are Creative

You must define what the agent cannot do. Explicit negatives prevent the agent from taking architectural shortcuts or introducing bloat. Example: “Implement this entirely in Python, with no dependencies.” Example: “Do not change public APIs.”

The Architecture of a Prompt

A robust prompt is structured like a ticket for a human engineer. It should contain four distinct components:

Component	Purpose	Example
Goal	The specific outcome desired.	”Create a complete Python port of this library.”
Context	The environment and reference material.	”Clone this library to `/tmp`… The goal is an implementation that passes all tests in `/tmp/mquickjs/tests`.”
Constraints	What to avoid.	”Never use React… Javascript should be two space indents.”
Verification	How to prove it works.	”Run `pytest` to confirm the test harness works correctly.”

Essential Communication Patterns

The Goal-Driven Request Pattern

Structure your requests around outcomes, not implementation steps: Instead of:

Create a new file called auth.py
Import the bcrypt library
Write a function to hash passwords
Add another function to verify passwords
Write tests for both functions

Do this:

Implement password hashing for our authentication system.

Requirements:
- Use bcrypt with cost factor 12
- Hash and verify functions
- Handle invalid inputs gracefully
- Comprehensive test coverage

Success: All tests pass, handles edge cases, documented API

The Constraint-Specification Pattern

Make constraints explicit rather than implicit: Weak:

Add caching to the API

Strong:

Add Redis caching to GET /users/:id endpoints.

Constraints:
- Must use existing Redis connection pool
- 5-minute TTL
- Invalidate on user updates (PUT /users/:id)
- Cache misses must not block requests
- Add metrics for cache hit rate

Validation:
- Existing tests still pass
- \<10ms cache hit latency
- Cache invalidation verified with integration tests

The Evidence-Demand Pattern

Never accept claims without proof: Maestro: “The optimization improved performance” You: “Show me the benchmark comparing old vs new implementation using identical test conditions and workload” Maestro: “All tests pass” You: “Display the full test output with coverage report” Maestro: “The implementation is production-ready” You: “Prove it: show me the tests, benchmarks, edge case handling, and error scenarios”

Strategic Workflows

Move beyond simple Q&A by employing these structured workflows for complex development.

The “Plan First” Pattern

For substantial undertakings, do not let the agent write code immediately. Separate the “thinking” from the “doing.”

Request a Specification: Ask the agent to analyze the requirements and build a detailed spec with TODOs, have a back and forth to define all the requirements well.
Review and Approve: Validate the plan before a single line of production code is written. This should include a goal and a way for the agent to test the project so it can course correct whenever needed.

The “Reference” Pattern

Describing complex logic is tedious and error-prone. If you have existing code that works, point to it. The Prompt: “That button should do the same trick that openai-audio-output.html does…” The Mechanism: The agent reads the referenced code, extracts the pattern, and applies it to the new context. This builds a compound advantage: every tool you build becomes a reference for the next.

The “Two-Phase” Flow

Vary your management style based on your certainty level. Research Mode (Exploratory): “What are the options for HTTP libraries in Rust? Include usage examples.” Accept code without deep review; iterate to learn. Implementation Mode (Directive): Once you know the solution, dictate exact implementation details, library choices, and function signatures.

Tactical Techniques

1. Function Signature Prompting

Maintain design control by defining the interface yourself, identifying the specific inputs and outputs you require.

Write a Python function that uses asyncio httpx with this signature:

async def download_db(url, max_size_bytes=5 * 1024 * 1024) -> pathlib.Path

Requirements:
- Download file from URL using httpx
- Enforce max_size_bytes limit
- Return path to downloaded file
- Raise ValueError if file exceeds size limit
- Handle connection errors gracefully

2. Debugging by Symptom

Do not diagnose; describe. State the symptom and the expected behavior, allowing the agent to determine the root cause.

The URLs are being truncated. I'm only getting the beginning of each URL, but I need the complete URLs.

Expected: https://example.com/path/to/resource
Actual: https://example.com

Fix this so the full URL is captured.

3. Visual & Browser Tasks

For visual tasks, focus on goals rather than procedures. Browser agents work best with outcome-oriented prompts.

I'm trying to figure out how come all pages under [URL] have an open CORS policy... I can't figure out where.

Pro-Tip: Pre-position the agent. If the task requires authentication, sign in yourself before engaging the agent to avoid complex login scripting.

4. Custom Instructions (The “Config File”)

Use project-level custom instructions to enforce style and prevent repetitive corrections.

Never use React... CSS should be indented with two spaces... Inputs and textareas should be font size 16px.

Managing Complex Projects

Breaking Down Large Goals

For substantial projects, decompose into phases: Example: Building a Microservices Architecture Phase 1: Research & Design

Research microservices patterns for Node.js applications.

Deliverables:
- Analysis of 3 viable approaches
- Recommendation with trade-off analysis
- High-level architecture diagram
- Key technology choices justified

Phase 2: Core Infrastructure

Implement the service communication layer.

Scope:
- Service discovery
- Inter-service messaging
- Error handling and retries
- Health checks

Validation: All components tested in isolation

Phase 3: Service Implementation

Implement user service following the established pattern.

Must:
- Follow architecture from Phase 1
- Use communication layer from Phase 2
- Include comprehensive tests
- Document API contracts

The Discovery Pattern

Before making changes to existing code, ensure understanding:

I want to add feature X to our codebase.

Before implementing:
1. Clone the repository
2. Explain the current architecture
3. Identify where X should integrate
4. Propose 2-3 implementation approaches
5. Recommend one with justification

Only after I approve the approach, proceed with implementation.

The Benchmark-Driven Pattern

For performance-critical work:

Optimize the image processing pipeline.

Current performance: 2 seconds per image (measured with test_images/sample.jpg)

Process:
1. Profile current implementation
2. Identify bottlenecks with evidence
3. Propose optimizations
4. Implement changes
5. Benchmark with SAME test image
6. Show before/after comparison

Target: \<500ms per image
Acceptance: Must show actual benchmark results

Managing the “Developer”

Even the best agents drift or hallucinate. Here is how to keep them on the rails.

Verify, Don’t Trust

Agents may “cheat” by simplifying requirements or skipping edge cases. Always inspect the actual approach, not just whether it runs. Verification Strategy: Request that the agent write a test for a trivial case (e.g., assert 1 + 1 == 2) to prove the infrastructure works before building complex logic. The “YOLO” Check: If you let an agent run in “YOLO mode” (unsupervised), be prepared to coach it back to reality if it rewrites your Python project in JavaScript.

Iterate Relentlessly

Treat bad results as a starting point, not a failure. Refinement: “Write that better!” is a valid prompt once expectations are established. Session Hygiene: If the context gets messy, reset.

When to Push Back

Push back when you see:

Unvalidated claims (“it should work”)
Incomplete test coverage
Missing edge case handling
Performance assertions without benchmarks
Shortcuts that compromise quality
Unclear or confusing code

How to Push Back Effectively

Ineffective: “This isn’t good enough” Effective: “The error handling is incomplete. What happens when Redis is unavailable? Add tests that simulate connection failure and prove the system degrades gracefully.” Ineffective: “Did you test this?” Effective: “Run the full test suite and show me the output. Then add integration tests that verify cache invalidation works correctly.”

Validation and Quality Control

The Comprehensive Validation Request

Don’t let Maestro declare success without proof:

Before claiming this is complete:
Run the FULL test suite (not just related tests)
Show me the test output
Run performance benchmarks
Compare results to baseline
Check for regressions
Verify edge cases are handled
Confirm error scenarios are tested
Show me code coverage report

The Test-First Pattern

Ensure testing isn’t an afterthought:

Implement user registration.

Workflow:
1. Write comprehensive tests first (TDD style)
2. Tests should cover:
   - Happy path
   - Invalid inputs
   - Duplicate registrations
   - Database failures
   - Email sending failures
3. Implement to make tests pass
4. Show me test output proving all pass

The Test-Preservation Pattern

Protect against regressions:

Add retry logic to API client.

Requirements:
- All existing tests must pass unchanged
- Add new tests only for retry behavior
- Verify backward compatibility
- No changes to public API surface

If any existing test fails, stop and explain why before proceeding.

Handling Challenges

When Maestro Gets Stuck

Symptoms:

Repeated similar errors
Circular debugging
No progress after multiple attempts

Your Response:

Stop. Let's reconsider the approach.

Current issue: [describe what's failing]

Options:
1. Try a different implementation strategy
2. Simplify the requirements
3. Break into smaller steps
4. Research alternative solutions

What do you recommend and why?

When Tests Fail Unexpectedly

Don’t let Maestro skip or comment out tests:

These test failures are real signals.

DO NOT:
- Skip the failing tests
- Comment them out
- Change tests to match implementation

DO:
- Understand why they fail
- Fix the implementation
- Ensure all tests pass
- Add tests if coverage is insufficient

When Requirements Aren’t Clear

Maestro can help clarify:

I want to improve the performance of our system but I'm not sure where to start.

Please:
1. Profile the current system
2. Identify the top 3 bottlenecks
3. Estimate impact of optimizing each
4. Recommend where to focus
5. Explain your reasoning

Then we'll decide together which to tackle.

Request Quality Checklist

Before submitting a request to Maestro, verify:

Is the context clear? Did I include relevant files, errors, logs, or references?
Are constraints specified? Did I define what NOT to do?
Is success defined? Did I specify success criteria, tests, or benchmarks?
Is the scope manageable? Is this one focused task, or multiple tasks bundled together?
Are quality standards explicit? Did I specify testing, performance, or code quality requirements?

High-quality requests lead to high-quality outcomes.

Common Patterns at a Glance

Starting a Feature

Implement [feature] for [context].

Requirements:
- [specific requirement 1]
- [specific requirement 2]
- [specific requirement 3]

Constraints:
- [what not to do]
- [architectural boundaries]

Success criteria:
- [measurable outcome 1]
- [measurable outcome 2]

Debugging an Issue

[Symptom description] is happening.

Expected: [what should happen]
Actual: [what is happening]

Context:
- [relevant files]
- [error messages]
- [steps to reproduce]

Fix this and add tests to prevent regression.

Performance Optimization

Optimize [component] performance.

Current: [measurement]
Target: [goal]

Process:
1. Profile and identify bottlenecks
2. Propose optimizations with rationale
3. Implement changes
4. Benchmark with same test data
5. Show before/after comparison with evidence

Code Review Request

Review this implementation:

[description or file reference]

Check for:
- Edge cases and error handling
- Test coverage
- Performance implications
- Security considerations
- Code clarity and maintainability

Provide specific feedback with examples.

Next Steps

Now that you understand effective prompting:

Working with Maestro: Advanced collaboration patterns
Session Strategies: Patterns for different project types
Best Practices: Production-ready standards
Commands Reference: Master session control tools

Remember: Clear communication, explicit constraints, and rigorous validation are the keys to success with AI coding agents.

​The Mental Model

​Core Philosophy

​1. Be Imperative and Direct

​2. Context is King

​3. Constraints are Creative

​The Architecture of a Prompt

​Essential Communication Patterns

​The Goal-Driven Request Pattern

​The Constraint-Specification Pattern

​The Evidence-Demand Pattern

​Strategic Workflows

​The “Plan First” Pattern

​The “Reference” Pattern

​The “Two-Phase” Flow

​Tactical Techniques

​1. Function Signature Prompting

​2. Debugging by Symptom

​3. Visual & Browser Tasks

​4. Custom Instructions (The “Config File”)

​Managing Complex Projects

​Breaking Down Large Goals

​The Discovery Pattern

​The Benchmark-Driven Pattern

​Managing the “Developer”

​Verify, Don’t Trust

​Iterate Relentlessly

​When to Push Back

​How to Push Back Effectively

​Validation and Quality Control

​The Comprehensive Validation Request

​The Test-First Pattern

​The Test-Preservation Pattern

​Handling Challenges

​When Maestro Gets Stuck

​When Tests Fail Unexpectedly

​When Requirements Aren’t Clear

​Request Quality Checklist

​Common Patterns at a Glance

​Starting a Feature

​Debugging an Issue

​Performance Optimization

​Code Review Request

​Next Steps