# Vibe Coding Tips and Tricks

> Note
> This field is evolving quickly, and we will update this guide as new methods and recommendations arise.

## Table of Contents


- [Vibe coding](#vibe-coding)
- [AI Development Clients](#ai-development-clients)
- [Requirements and Design Guidelines](#requirements-and-design-guidelines)
- [Prompting](#prompting)
- [Testing and Validation](#testing-and-validation)
- [Documentation](#documentation)
  - [Co-authoring Documentation with AI](#co-authoring-documentation-with-ai)
- [Limitations](#limitations)
  - [Number of MCP servers and tools](#number-of-mcp-servers-and-tools)
  - [Conversation Management](#conversation-management)
- [Context](#context)
  - [Rules and Configuration](#rules-and-configuration)
- [Tooling](#tooling)
- [Version Control](#version-control)

## Vibe coding

As described [here](https://en.wikipedia.org/wiki/Vibe_coding), vibe coding is a modern approach to software development where users enter prompts in natural language to generate code.

Vibe coding involves several key components working together:

- **Prompt**: The initial instructions and context provided to guide the coding process
- **Client**: The interface through which users interact with the coding system. For instance, [Amazon Q Developer](https://aws.amazon.com/q/developer/) or [Cline](https://cline.bot/)
- **Additional context**: You can enhance the agent's capabilities by providing additional context, such as AWS MCP servers

An important aspect is that while coding AI intends to help you be more productive, it is not aiming at replacing the developer. You own the architecture and the vision for the product. As the developer, you are expected to understand, review, and validate every technical decision made - the AI serves as a tool to enhance your capabilities, not substitute your critical thinking and expertise. The responsibility for code quality, architectural choices, and technical decisions remains firmly in human hands. Please refer to [this guide](https://d1.awsstatic.com/products/generative-ai/responsbile-ai/AWS-Responsible-Use-of-AI-Guide-Final.pdf) for responsible use of AI.

> Warning
> Never blindly trust code generated by AI assistants. Always:
>
> - Thoroughly review and understand the generated code
> - Verify all dependencies
> - Perform necessary security checks
> - Test the code in a controlled environment

## AI Development Clients

* **Selection Criteria:** When selecting an AI development client, consider your organization's requirements, such as compliance, security policies, and approved vendor lists. Technical aspects like pricing and IDE integration are also important factors in your decision.
* **Leverage Client Features:** Each client has unique characteristics to optimize your workflow. For instance, in Cline, start with Plan mode to discuss and refine implementation details until you have a clear understanding. Only move to Act mode once the plan is thoroughly reviewed - this way, the code generation will align with your agreed-upon approach. Stay informed about new features and updates in your chosen clients through regular review of documentation and release notes.
* **Feature Compatibility:** Each client supports different MCP features (Tools, Resources, Prompts - see [MCP clients](https://modelcontextprotocol.io/clients)). For example, if you plan to use the CDK MCP server, ensure your chosen client supports both Tools and Resources features.
* **Multi-Client Strategy:** You don't need to limit yourself to a single client. Different clients excel at different tasks - you might use Cline for backend/CDK development while using Q CLI for AWS troubleshooting of permissions, network reachability, and security group rules.
* **MCP Server Selection:** Don't feel overwhelmed by the number of available MCP servers (40+ and growing). Focus only on those that match your specific needs and use cases. Review their documentation carefully and test them as part of your selection process.


## Requirements and Design Guidelines

Before starting any coding task, follow these essential steps:

- Clearly define project requirements and scope
- Establish comprehensive design guidelines and coding standards
- Document all constraints and limitations
- Create and maintain markdown files with gathered information for client access
- Begin the coding process only after completing the above steps

You can interact with your AI assistant to help you define the requirements, architecture, design, and tasks for your specific feature/project. This step is extremely important, as it will provide critical information for the AI assistant for the implementation phase. However, remember that the AI is a collaborative tool, not the primary decision-maker.

Clear requirements and well-defined tasks will help the AI assistant generate more relevant code, which can reduce the amount of hands-on intervention needed. However, this doesn't diminish your responsibility to thoroughly review and validate all generated code.

It's crucial not to rely solely on the AI assistant to create these documents. As the project owner, you must maintain control over and understanding of every technical aspect. Your domain expertise, experience, and judgment are essential for making informed decisions. Since AI assistants might show a tendency to agree with suggestions rather than provide critical feedback, it's recommended to frame your interactions as questions rather than assertions. This approach promotes more meaningful dialogue and helps surface potential issues or alternative solutions.

## Prompting

Effective prompting is crucial for successful AI-assisted development:

- Provide detailed specifications for the work to be done
- Include relevant context and files when necessary
- Apply prompting strategically to specific tasks for easier review and testing
- Break down large tasks into smaller, focused subtasks for better results

To help you create your prompts, you can use:

- tools like [Amazon Bedrock Prompt Optimization](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-management-optimize.html) which will rewrite prompts to yield inference results that are more suitable for your use case
- metaprompting by discussing the feature with the AI assistant first, then summarizing the discussion as a prompt for the agent to develop the feature

## Testing and Validation

Ensure code quality and reliability through:

- Incremental testing of each change
- Implementation of automated testing where possible
- Validation against original requirements
- Maintenance of a comprehensive test suite (CI/CD)
- Regular automated security and quality scans

In general, we found that relying solely on your AI code assistant to generate unit tests doesn't provide great results. The assistant might create superficial tests or irrelevant assertions that simply validate the existing code without ensuring proper test coverage or meaningful validation.

It is strongly recommended that you create your own test cases and use a test-driven development approach. While you can leverage your AI assistant to help implement tests based on the test cases you provide, you should be the one defining these test cases. As the owner/supervisor, you understand the business logic, edge cases, and what the software is intended to do. Your domain knowledge and understanding of the requirements are crucial for designing effective test scenarios that truly validate the application's behavior.

The human developer must review and verify that each test case properly examines the intended functionality, handles edge cases appropriately, and maintains the overall quality of the test suite. Remember that effective testing requires deep understanding of both the business requirements and technical implementation - something that current AI assistants cannot fully replicate.

## Documentation

Maintain high-quality documentation by:

- Documenting every change made
- Ensuring the client generates appropriate code documentation (e.g., Python docstrings in code and written documentation in a README)
- Keeping documentation up-to-date with code changes

### Co-authoring Documentation with AI

You may create multiple documents with AI and let AI update them whenever you make changes together. For example, you can define database schemas when planning, and let AI create ERD diagrams. When you review and want to make changes, remember to update both the documentation and the code. This collaborative approach can apply to various aspects of your project, such as API design or network architecture. The key is to split the documentation in meaningful ways and keep it up-to-date and concise, helping both you and AI maintain clear context and control.

> **Tip:** Well-organized documentation helps maintain context for both you and your AI assistant throughout the project lifecycle.

## Limitations

### Number of MCP servers and tools

- Excessive number of MCP servers/tools can negatively impact client performance
- Refer to your client documentation for best practices and limits

### Conversation Management

- Long conversations can degrade client performance due to growing context size
- Maintain separate conversations for different features
- Regularly review and clean up conversation history

## Context

### Rules and Configuration

For optimal results:

- Define clear rules for code generation and modification
- Maintain consistent configuration across environments
- Document special rules and exceptions
- Regularly review and update configuration settings
- Implement modular design principles

Examples of rules:

```markdown
- If a file is longer than 300 lines of code, break it down into multiple files.
- Add documentation for every new piece of code added.
```

## Tooling

To foster an environment where AI coding agents excel, follow software developement best practices (clear requirements, modular code, good documentation,...) and use tools (static code analysis, code coverage, CI/CD pipeline, tests, formatter,...).

When you assign tasks to a coding agent, it can autonomously iterate by running test cases and static analysis tools, correcting itself as needed. This minimizes manual intervention and streamlines the development process.

## Version Control

Follow these version control best practices:

* **Meaningful Commits:** Commit changes frequently with clear, descriptive messages. Consider using AI to help draft commit messages, but always review them to ensure they accurately reflect your changes and provide good reference points for potential rollbacks.
* **Branch Strategy:** Use feature branches for new development. Create separate branches for significant changes to maintain flexibility in your development process.
* **Repository Structure:** Maintain a clean and organized repository structure. Define your structural requirements (like file size limits, mono repo setup, frontend framework) early and include these in your AI prompts for consistent code organization.
