Understanding Agent Engineering
Just like “prompt engineering” helps you get better results from language models, “agent engineering” is a set of best practices to maximize your success with Workshop. While Workshop is powerful and intuitive, following these practices will significantly improve your outcomes, especially for complex projects.
Agent engineering is about designing thoughtful interactions with AI systems to ensure they operate reliably, efficiently, and successfully. Even as AI models become more sophisticated, these practices help guide them toward the results you want.
The Five Pillars of Successful Building
1. Separate Planning from Execution
Before diving into code, make sure you have clear requirements. If your project needs are still forming, start with collaborative planning:
Use Plan Mode to work through requirements systematically. This mode acts like an experienced technical product manager, asking the right questions and helping you scope appropriately.
Plan Mode is especially valuable at the start of a project. It helps you avoid the most common mistake: jumping into code before requirements are clear.
2. Build Incrementally
The most common mistake is asking for too much at once. Break your project into small, achievable steps:
Instead of this:
Try this approach:
Then continue step by step:
This incremental approach has multiple benefits:
- Higher success rate for each step
- Easier to debug when issues arise
- Natural checkpoints to save progress
- Flexibility to change direction based on results
3. Verify Understanding Before Making Changes
When working with existing code, always ensure Workshop understands the current system before asking for modifications.
The wrong approach:
The right approach:
This pattern is crucial for success with existing codebases. Just like human developers study code before modifying it, Workshop needs guided exploration to understand how things work.
4. Manage Task Execution
Some tasks require multiple iterations. Instead of micromanaging every step, you can give Workshop more autonomy:
For ongoing work:
For quick iterations:
When things get complex:
5. Handle Errors Effectively
When Workshop gets stuck or makes mistakes, use these recovery strategies:
For spinning wheels or repeated failures:
For dependency or environment issues:
For complex debugging:
Using .workshop/rules.md for Project-Specific Instructions
Workshop automatically reads a .workshop/rules.md file in your project root, making it the ideal place to document project-specific context:
You do not need to write this file manually. Ask Workshop to create it:
Treat .workshop/rules.md as a living document. Update it as your project evolves. Focus on what is unique or non-obvious about your project — Workshop already understands common frameworks and patterns.
Context Management Best Practices
As projects grow, help Workshop maintain context effectively:
Start new conversations for new topics. Credit cost per message increases as conversations get longer because each new message includes the full context of prior messages. Starting fresh conversations for distinct tasks is both cheaper and more effective.
Use the /compact command. When a conversation gets long but you are not ready to start fresh, the /compact command summarizes the conversation to reduce context size while preserving key information.
Reference files explicitly. When you need Workshop to focus on specific parts of your codebase, point it to the relevant files rather than expecting it to search the entire project.
Keep .workshop/rules.md focused. Add emphasis like “IMPORTANT:” or “NOTE:” for critical information. Avoid dumping massive amounts of context — prioritize what is most unique about your project.
Common Success Patterns
The MVP-First Pattern
Always start with the minimum viable version:
- Core functionality only — Get the basics working
- Add one feature at a time — Build on a solid foundation
- Enhance the user experience — Polish after functionality is proven
The Version Control Pattern
Establish good practices early:
Regular commits create safety nets and clear progress markers. Workshop’s built-in checkpointing provides an additional layer of safety for within-session changes.
The Testing Pattern
Build confidence in your code:
Common Anti-Patterns to Avoid
Measuring Success
Good agent engineering leads to:
- Higher success rates for complex tasks
- Fewer iterations needed to achieve goals
- More maintainable project outcomes
- Better project continuity across conversations
- Reduced frustration with debugging and errors
Agent engineering is a skill that improves with practice. Start with these patterns, experiment with your own approaches, and share what works in our Discord community.
