system-prompts-and-models-of-ai-tools/best_practices_article.md

Best Practices for AI-Assisted Coding (Vibe Coding)

Introduction

AI-assisted coding tools, sometimes referred to as "vibe coding systems," are rapidly changing the landscape of software development. These systems leverage large language models (LLMs) and sophisticated tooling to understand user intent, generate code, and automate various development tasks. To maximize the effectiveness and reliability of these tools, it's crucial to adhere to a set of best practices in their design, development, and usage. This article synthesizes key best practices identified from research and observations of various vibe coding systems.

Prompting Techniques

Effective communication with the AI is fundamental. The quality of the output often directly correlates with the clarity and structure of the input prompts.

• Use Clear and Concise Language: Employ basic prompting phrases and keywords to guide the AI.
  • Emphasis: Use words like IMPORTANT:, NOTICE:, NEVER, Always, DO, DON'T to highlight critical instructions. Bolding important words (**important words**) can also help.
  • Sparing Use of Emphasis: Keywords like NOTE:, MUST, or !IMPORTANT should be used sparingly to emphasize truly critical information, as overuse can diminish their impact.
• Structured Input: For some systems, like those based on Claude, using XML-like structures in prompts can improve understanding and parsing of instructions. This is seen in tools like VS Code Copilot, same.dev, and Windsurf.

  <identity>
  You are an AI programming assistant.
  When asked for your name, you must respond with "GitHub Copilot".
  ...
  </identity>
  <instructions>
  ...
  </instructions>
  

• Keywords for Organization (Replit): Systems like Replit utilize keywords to organize prompts into logical sections, which can help in structuring complex requests:
  • <Iteration Process>
  • <Operation Principles>
  • <Workflow Guides>
  • <Step Execution>
  • <Debugging Process>
  • <Communication Policy>

UI/UX Considerations

The user interface and experience are critical for making AI coding tools accessible and productive.

• Dynamic Rendering: Using MDX (Markdown + JSX) for responses allows for dynamic and interactive content rendering, similar to streaming content in a browser. This is a notable feature in tools like v0.
• Accessibility: Always implement accessibility best practices to ensure tools are usable by everyone (v0).
• Markdown Template Engines: Employ Markdown template engines for rendering and compositing complex views. This is a good practice observed in code generation tools.
• Suggestion Systems: Proactively suggest relevant follow-up actions to the user. This can help guide the user, spark new ideas, and highlight potential next steps (v0).

  <Actions>
    <Action name="Add hero section" description="Create a prominent hero section" />
    <Action name="Toggle dark mode" description="Add dark mode support" />
  </Actions>
  

• UI Frameworks: Utilizing established UI frameworks and libraries like shadcn/ui in CLI-mode or preset-mode is considered a best practice for UI design (same.dev, v0).

Tooling and Capabilities

The underlying tools and defined capabilities of the AI system dictate its effectiveness.

• Clearly Defined Capabilities: A Capabilities section is essential to describe the boundaries of the AI's abilities. This helps manage user expectations (v0).

  Users interact with v0 online. Here are some capabilities of the v0 UI:
  
  - Users can attach (or drag and drop) images and text files in the prompt form.
  - Users can execute JavaScript code in the Node.js Executable code block
  ...
  

• Domain-Specific Knowledge:
  • Incorporate a domain knowledge section for specialized information.
  • All domain knowledge used by the system (e.g., in v0) MUST be cited, often using a format like [^index] linking to a sources section. This is especially important for private knowledge bases.
  • Model Context Protocol (MCP) is a good practice for managing and vending domain knowledge.
• Handling Refusals: Implement a clear Refusal section to define how the system responds to inappropriate or harmful requests. The response should be direct and avoid apologies or explanations (v0).

  # Refusals
  
  REFUSAL_MESSAGE = "I'm sorry. I'm not able to assist with that."
  
  1. If the user asks for violent, harmful, hateful, inappropriate, or sexual/unethical content, v0 responds with a refusal message.
  2. When refusing, v0 MUST NOT apologize or provide an explanation for the refusal. v0 simply states the REFUSAL_MESSAGE.
  

• Data Serialization: Using libraries like zod to serialize and deserialize JSON schema to data is a good practice, ensuring data integrity and structure (same.dev). Alternatively, function parameters can be used directly.
• Tool Categorization: Clearly define and categorize the tools and actions an agent can perform. This is seen in systems like lovable and manus, using XML-like tags for operations:

  <lov-write> for creating or updating files. Must include complete file contents. </lov-write>
  <lov-rename> for renaming files from original path to new path. </lov-rename>
  

System Design

The architectural design of the AI system plays a vital role in its robustness and ability to handle complex tasks.

• Thinking Tags for Planning: Encourage the system to use "thinking tags" (e.g., <Thinking>...</Thinking>) to plan and outline steps before generating code or taking action. This is similar to writing a Product Requirements Document (PRD) and is a practice used by v0.
• Event Stream Architecture (Manus): Organizing events and actions into an event stream is a good practice. This allows for tracking task progress and system state effectively. The stream can include:
  • Message: User inputs.
  • Action: Tool use.
  • Observation: Results from actions.
  • Plan: Task planning updates.
  • Knowledge: Task-related best practices.
• Modular Design (Manus): A modular architecture, as seen in manus, enhances maintainability and clarity. Key modules include:
  • Planner Module: For overall task planning, represented by numbered pseudocode.
  • Knowledge Module: Provides task-relevant knowledge and best practices.
  • Datasource Module: Manages access to authoritative data APIs.
• Agent Loop (Manus): Operating in an agent loop allows for iterative task completion:
  1. Analyze Events
  2. Select Tools
  3. Wait for Execution
  4. Iterate
  5. Submit Results
  6. Enter Standby

Development Practices

Adhering to sound software development principles is just as important for AI-assisted coding as it is for traditional development.

• File and Code Editing (VS Code Copilot):
  • Read Before Edit: Don't try to edit an existing file without reading it first.
  • Use Dedicated Tools: Employ specific tools (e.g., insert_edit_into_file) for file modifications rather than printing code blocks representing changes.
  • Concise Edits: When using editing tools, avoid repeating existing code. Use comments like // ...existing code... to represent unchanged regions.
  • Validate Changes: After editing a file, call validation functions (e.g., get_errors) and fix relevant errors.
• Environment Description: Providing information about the project's current state (e.g., version numbers, directory structure, linter errors, terminal logs) is beneficial (same.dev).
• General Coding Best Practices (lovable):
  • Code Quality and Organization: Create small, focused components (e.g., < 50 lines), use TypeScript, follow project structure, implement responsive designs, and use extensive console logs.
  • Component Creation: Create new files for components, use UI libraries like shadcn/ui, follow atomic design, and ensure proper file organization.
  • State Management: Use appropriate libraries for server state (e.g., React Query) and local state (e.g., useState/useContext), avoid prop drilling, and cache responses.
  • Error Handling: Use toast notifications, implement error boundaries, log errors, and provide user-friendly error messages.
  • Performance: Implement code splitting, optimize images, use React hooks correctly, and minimize re-renders.
  • Security: Validate inputs, implement proper authentication, sanitize data, and follow security guidelines (e.g., OWASP).
  • Testing: Write unit and integration tests, test responsive layouts, and verify error handling.
  • Documentation: Document complex functions, keep READMEs updated, include setup instructions, and document APIs.

Communication and Workflow (Manus)

Defining clear rules for how the AI interacts with the user and manages its workflow is crucial for a smooth experience.

• Task Management (todo_rules):
  • Use a todo.md file as a checklist based on task planning.
  • Update todo.md immediately after completing each item.
• Messaging (message_rules):
  • Communicate via message tools, replying promptly to new user messages.
  • Distinguish between notify (non-blocking) and ask (blocking) messages.
  • Provide results and deliverables as attachments.
• File Operations (file_rules):
  • Use dedicated file tools for I/O to avoid shell command issues.
  • Save intermediate results and organize reference information.
• Information Gathering (info_rules):
  • Prioritize information: authoritative datasource API > web search > model's internal knowledge.
  • Access original pages from search results, not just snippets.
• Browser Interaction (browser_rules):
  • Use browser tools to access URLs from users or search results.
  • Actively explore links for deeper information.
  • Handle cases where content extraction might be incomplete by scrolling.
• Shell Usage (shell_rules):
  • Avoid commands requiring confirmation (use -y or -f flags).
  • Chain commands with &&.
  • Use bc for simple calculations, Python for complex math.
• Coding Execution (coding_rules):
  • Save code to files before execution.
  • Use search tools for unfamiliar problems.
• Deployment (deploy_rules):
  • Use expose port tools for temporary external access.
  • Ensure services listen on 0.0.0.0.
  • Test services locally before exposing them.
• Content Generation (writing_rules):
  • Write in continuous paragraphs; avoid lists unless requested.
  • Cite sources when writing based on references.
  • For lengthy documents, save sections separately then combine.
• Error Handling (error_handling):
  • Verify tool names and arguments upon error.
  • Attempt to fix issues based on error messages or try alternative methods.
  • Report failures to the user if unresolved.

Conclusion

The development and application of AI-assisted coding tools represent a significant advancement in software engineering. By adhering to best practices in prompting, UI/UX design, tooling, system architecture, development processes, and communication workflows, we can build more effective, reliable, and user-friendly vibe coding systems. These practices, drawn from observations of systems like v0, Manus, and VS Code Copilot, provide a strong foundation for harnessing the full potential of AI in the coding domain. Continuous learning and refinement of these practices will be essential as the field evolves.