# Vibecoding

> Open source knowledge base for the vibecoding community - learn AI-assisted coding, prompting strategies, and collaborative development practices.

Vibecoding is an open source knowledge base for the vibecoding community.
Learn AI-assisted coding, prompting strategies, and collaborative development practices.


# Getting Started

# What is Vibecoding?

Vibecoding is a development philosophy that embraces AI-assisted coding as a natural, conversational way to build software. It's about finding your flow and collaborating with AI tools to create, learn, and iterate faster than ever before.

## Core Principles

### 1. Conversation Over Commands

Instead of writing code line-by-line, vibecoding treats development as a dialogue. You describe what you want to build, the AI suggests implementations, and together you refine the solution.

### 2. Iteration Is Key

Don't expect perfection on the first try. Vibecoding is an iterative process:

1. **Describe** your intent clearly
1. **Review** what the AI generates
1. **Refine** through follow-up prompts
1. **Repeat** until you're satisfied

### 3. Learning Through Building

Every interaction with an AI coding assistant is a learning opportunity. Pay attention to:

- Patterns and idioms the AI uses
- Best practices it follows
- Alternative approaches it suggests

### 4. Human Judgment Matters

AI is a powerful tool, but you're still the developer. Always:

- Review generated code before committing
- Understand what the code does
- Test thoroughly
- Consider security and performance implications

## Benefits of Vibecoding

| Traditional Approach           | Vibecoding Approach            |
| ------------------------------ | ------------------------------ |
| Look up documentation          | Ask the AI to explain          |
| Copy-paste from Stack Overflow | Generate tailored solutions    |
| Debug alone                    | Collaborate on troubleshooting |
| Write boilerplate manually     | Generate and customize         |
| Learn syntax first             | Build while learning           |

## Getting Started

Ready to start vibecoding? Head over to the [Quick Start Guide](https://vibecoding-navy.vercel.app/getting-started/quick-start/index.md) to set up your environment and write your first AI-assisted code.

## Common Misconceptions

Vibecoding is NOT...

- **Blindly accepting AI output** - Always review and understand generated code
- **Replacing your skills** - It augments your abilities, not replaces them
- **A shortcut to skip learning** - You'll learn more, just differently
- **Only for beginners** - Experienced developers benefit too

# Quick Start Guide

Get up and running with vibecoding in minutes. This guide will help you set up your environment and start your first AI-assisted coding session.

## Prerequisites

Before you begin, you'll need:

- A code editor (VS Code, Cursor, or similar)
- Access to an AI coding assistant (Claude, ChatGPT, GitHub Copilot, etc.)
- Basic familiarity with your programming language of choice

## Step 1: Choose Your AI Assistant

There are several AI coding assistants available. Here are some popular options:

Claude is Anthropic's AI assistant, available through:

- [Claude.ai](https://claude.ai) - Web interface
- [Claude Code](https://claude.ai/claude-code) - CLI tool for developers
- API access for custom integrations

GitHub Copilot integrates directly into your editor:

1. Install the Copilot extension for VS Code
1. Sign in with your GitHub account
1. Start typing and Copilot will suggest completions

Cursor is an AI-native code editor:

1. Download from [cursor.sh](https://cursor.sh)
1. Open your project
1. Use `Cmd+K` (Mac) or `Ctrl+K` (Windows/Linux) to chat

## Step 2: Set Up Your Project

Create a workspace for your vibecoding experiments:

```bash
mkdir my-vibe-project
cd my-vibe-project
git init
```

## Step 3: Start a Conversation

The key to vibecoding is clear communication. Here's a template to get started:

```text
I want to build [WHAT YOU WANT].

Context:
- I'm using [LANGUAGE/FRAMEWORK]
- This is for [PURPOSE/USE CASE]
- It should [KEY REQUIREMENTS]

Can you help me [SPECIFIC FIRST STEP]?
```

### Example Prompt

```text
I want to build a simple REST API endpoint.

Context:
- I'm using Python with FastAPI
- This is for a todo list application
- It should handle CRUD operations for tasks

Can you help me create the basic project structure and a simple
GET endpoint that returns a list of tasks?
```

## Step 4: Iterate and Refine

After receiving a response:

1. **Review** - Read through the generated code
1. **Test** - Run it and see what happens
1. **Ask questions** - If something is unclear, ask for explanations
1. **Refine** - Request changes or improvements

### Useful Follow-up Prompts

- "Can you explain how [specific part] works?"
- "Can you add error handling to this?"
- "How would I test this?"
- "What are the security considerations?"
- "Can you refactor this to be more [readable/efficient/maintainable]?"

## Step 5: Build Your Workflow

As you get comfortable, develop your own vibecoding workflow:

1. **Start with intent** - What are you trying to accomplish?
1. **Provide context** - What does the AI need to know?
1. **Review critically** - Don't accept code blindly
1. **Iterate rapidly** - Make small changes and test often
1. **Document learnings** - Note patterns that work well

## Next Steps

- Explore [Prompting Strategies](https://vibecoding-navy.vercel.app/guides/prompting-strategies/index.md) for more effective AI interactions
- Learn about different [AI Coding Assistants](https://vibecoding-navy.vercel.app/guides/ai-coding-assistants/index.md)
- Read our [Best Practices](https://vibecoding-navy.vercel.app/guides/best-practices/index.md) guide

## Tips for Success

Be Specific

The more specific your prompts, the better the results. Instead of "make a function", try "create a Python function that validates email addresses using regex".

Provide Examples

When possible, show the AI what you want through examples of input/output or similar code patterns.

Break It Down

Large tasks work better when broken into smaller pieces. Ask for one component at a time.
# Tools

# AI Coding Tools

The AI coding landscape is evolving rapidly. This section helps you navigate the tools available for AI-assisted development.

## Tool Categories

- **IDEs & Editors**

  ______________________________________________________________________

  Full-featured development environments with integrated AI capabilities.

  [Cursor](https://vibecoding-navy.vercel.app/tools/ides/cursor/index.md) · [Windsurf](https://vibecoding-navy.vercel.app/tools/ides/windsurf/index.md) · [VS Code](https://vibecoding-navy.vercel.app/tools/ides/vscode-copilot/index.md)

- **CLI & Terminal**

  ______________________________________________________________________

  Command-line tools for AI-assisted coding in your terminal.

  [Claude Code](https://vibecoding-navy.vercel.app/tools/cli/claude-code/index.md) · [Codex](https://vibecoding-navy.vercel.app/tools/cli/codex/index.md) · [Aider](https://vibecoding-navy.vercel.app/tools/cli/aider/index.md)

- **AI Models & APIs**

  ______________________________________________________________________

  The underlying AI models that power these tools.

  [Claude](https://vibecoding-navy.vercel.app/tools/models/claude.md) · [Gemini](https://vibecoding-navy.vercel.app/tools/models/gemini.md) · [Qwen](https://vibecoding-navy.vercel.app/tools/models/qwen.md) · [OpenAI](https://vibecoding-navy.vercel.app/tools/models/openai/index.md)

## How Tools Work Together

Many tools use multiple AI models under the hood. Understanding these relationships helps you choose the right combination:

| Tool                                                                                       | Type | Models Supported      |
| ------------------------------------------------------------------------------------------ | ---- | --------------------- |
| [Cursor](https://vibecoding-navy.vercel.app/tools/ides/cursor/index.md)                    | IDE  | Claude, GPT-4, Gemini |
| [Windsurf](https://vibecoding-navy.vercel.app/tools/ides/windsurf/index.md)                | IDE  | Claude, GPT-4         |
| [VS Code + Copilot](https://vibecoding-navy.vercel.app/tools/ides/vscode-copilot/index.md) | IDE  | GPT-4 (Copilot)       |
| [Claude Code](https://vibecoding-navy.vercel.app/tools/cli/claude-code/index.md)           | CLI  | Claude                |
| [Codex CLI](https://vibecoding-navy.vercel.app/tools/cli/codex/index.md)                   | CLI  | GPT-4                 |
| [Aider](https://vibecoding-navy.vercel.app/tools/cli/aider/index.md)                       | CLI  | Claude, GPT-4, others |

## Configuration Fundamentals

Most AI coding tools store their configuration in your home directory. Understanding this is key to customizing your setup.

[Understanding Config Directories](https://vibecoding-navy.vercel.app/tools/config-directories/index.md)

## Choosing the Right Tool

**New to AI coding?** Start with [Cursor](https://vibecoding-navy.vercel.app/tools/ides/cursor/index.md) - it has the gentlest learning curve.

**Prefer the terminal?** Try [Claude Code](https://vibecoding-navy.vercel.app/tools/cli/claude-code/index.md) or [Aider](https://vibecoding-navy.vercel.app/tools/cli/aider/index.md).

**Already using VS Code?** Add [GitHub Copilot](https://vibecoding-navy.vercel.app/tools/ides/vscode-copilot/index.md) to your existing setup.

**Want flexibility?** [Cursor](https://vibecoding-navy.vercel.app/tools/ides/cursor/index.md) and [Aider](https://vibecoding-navy.vercel.app/tools/cli/aider/index.md) let you switch between models.

## Community Resources

- [agents-environment-config](https://vibecoding-navy.vercel.app/resources/agents-environment-config/index.md) - Shared configurations for multiple tools
- [Cursor Rules Guide](https://vibecoding-navy.vercel.app/resources/cursor-rules/index.md) - Customize Cursor's behavior

# Understanding AI Tool Config Directories

Most AI coding tools store configuration files in your home directory. Understanding this pattern is essential for customizing your setup and sharing configurations across machines.

## The Concept

When you install an AI coding tool, it typically creates a hidden directory in your home folder (prefixed with `.`). This directory contains:

- **Settings files** - Your preferences and API keys
- **Rules/Instructions** - Custom behavior and coding standards
- **Extensions** - Plugins, skills, or commands
- **Cache** - Model responses and session data

## Directory Locations by Platform

| Tool        | macOS/Linux  | Windows                  |
| ----------- | ------------ | ------------------------ |
| Claude Code | `~/.claude/` | `%USERPROFILE%\.claude\` |
| Cursor      | `~/.cursor/` | `%USERPROFILE%\.cursor\` |
| Gemini      | `~/.gemini/` | `%USERPROFILE%\.gemini\` |
| Qwen        | `~/.qwen/`   | `%USERPROFILE%\.qwen\`   |
| Codex       | `~/.codex/`  | `%USERPROFILE%\.codex\`  |

Finding Your Home Directory

```bash
echo $HOME
# Usually /Users/yourname (macOS) or /home/yourname (Linux)
```

```powershell
echo %USERPROFILE%
# Usually C:\Users\yourname
```

## Common Directory Contents

### Claude Code (`~/.claude/`)

```text
~/.claude/
├── settings.json          # User settings and preferences
├── settings.local.json    # Machine-specific settings (not synced)
├── CLAUDE.md              # Global agent instructions
├── agents/                # Custom agent definitions
├── skills/                # Custom skills and commands
├── statusline.sh          # Custom statusline script
└── projects/              # Project-specific settings
```

**Key files:**

- `CLAUDE.md` - Instructions that apply to all your Claude Code sessions
- `settings.json` - API keys, model preferences, allowed tools
- `agents/` - Reusable agent personalities and behaviors

[Claude Code details](https://vibecoding-navy.vercel.app/tools/cli/claude-code/index.md)

### Cursor (`~/.cursor/`)

```text
~/.cursor/
├── mcp.json               # MCP server configuration
├── commands/              # Custom slash commands
└── rules/                 # Development rules (.mdc files)
```

**Key files:**

- `mcp.json` - Defines which MCP servers Cursor can use
- `rules/` - Contains `.mdc` files with coding standards and behaviors
- `commands/` - Custom commands accessible via `/command-name`

[Cursor details](https://vibecoding-navy.vercel.app/tools/ides/cursor/index.md)

### Gemini (`~/.gemini/`)

```text
~/.gemini/
└── settings.json          # MCP and model configuration
```

[Gemini details](https://vibecoding-navy.vercel.app/tools/config-directories/models/gemini.md)

### Qwen (`~/.qwen/`)

```text
~/.qwen/
└── settings.json          # MCP and model configuration
```

[Qwen details](https://vibecoding-navy.vercel.app/tools/config-directories/models/qwen.md)

### Codex (`~/.codex/`)

```text
~/.codex/
└── config.toml            # Configuration in TOML format
```

[Codex details](https://vibecoding-navy.vercel.app/tools/cli/codex/index.md)

## What Goes Where: Global vs Project

| Scope       | Location         | Use For                                        |
| ----------- | ---------------- | ---------------------------------------------- |
| **Global**  | `~/.tool/`       | Personal preferences, API keys, reusable rules |
| **Project** | `project/.tool/` | Project-specific settings, team-shared rules   |

Most tools check both locations and merge configurations, with project settings taking precedence.

Example: Cursor Rules

```text
~/.cursor/rules/           # Your personal coding standards
myproject/.cursor/rules/   # Project-specific standards (shared with team)
```

Cursor loads both, with project rules overriding global ones for conflicts.

## MCP (Model Context Protocol)

Many tools support MCP servers - external services that extend AI capabilities:

```json
// Example ~/.cursor/mcp.json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@context7/mcp"]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-playwright"]
    }
  }
}
```

MCP servers can provide:

- Documentation lookup
- Browser automation
- Database access
- API integrations

## Sharing Configuration

### Manual Sharing

Copy your config directory to a new machine:

```bash
# Backup
cp -r ~/.cursor ~/cursor-backup

# Restore on new machine
cp -r ~/cursor-backup ~/.cursor
```

### Using Git

Track your configs in a git repository and symlink them:

```bash
# Clone your config repo
git clone https://github.com/you/dotfiles ~/dotfiles

# Symlink configs
ln -s ~/dotfiles/.cursor ~/.cursor
ln -s ~/dotfiles/.claude ~/.claude
```

### Community Solution: agents-environment-config

The [agents-environment-config](https://vibecoding-navy.vercel.app/resources/agents-environment-config/index.md) repository provides a complete setup for managing configurations across multiple AI tools.

[Learn more about agents-environment-config](https://vibecoding-navy.vercel.app/resources/agents-environment-config/index.md)

## Security Considerations

Protect Your API Keys

Config directories often contain API keys. Never commit them to public repositories.

- Use `.gitignore` to exclude sensitive files
- Use environment variables for keys when possible
- Consider using a secrets manager

**Files to keep private:**

- `settings.json` (often contains API keys)
- `settings.local.json`
- Any `.env` files

**Files safe to share:**

- `rules/` directories
- `CLAUDE.md` / `AGENTS.md` (instructions without keys)
- `mcp.json` (unless it contains secrets)

## Troubleshooting

### "Config not loading"

1. Check the directory exists: `ls -la ~/.cursor`
1. Verify file permissions: `chmod 644 ~/.cursor/mcp.json`
1. Check for syntax errors in JSON/YAML files

### "Changes not taking effect"

1. Restart the tool after config changes
1. Check for project-level overrides
1. Verify you're editing the right location (global vs project)

### "Tool can't find config directory"

Some tools create the directory on first run. Try:

1. Run the tool once to initialize
1. Create the directory manually: `mkdir ~/.cursor`

# Cursor

> **Official Docs**: [cursor.com/docs](https://docs.cursor.com/) **Category**: IDE

Cursor is a VS Code fork with AI deeply integrated into the editing experience. It's become one of the most popular AI coding tools due to its intuitive interface and powerful features.

## Quick Links

- [Official Documentation](https://docs.cursor.com/)
- [Cursor Forum](https://forum.cursor.com/)
- [Download Cursor](https://cursor.com/)

Works With

Cursor supports multiple AI models including [Claude](https://vibecoding-navy.vercel.app/tools/ides/models/claude.md), [GPT-4](https://vibecoding-navy.vercel.app/tools/models/openai/index.md), and [Gemini](https://vibecoding-navy.vercel.app/tools/ides/models/gemini.md). You can switch models based on your needs.

## Configuration

> See [Understanding Config Directories](https://vibecoding-navy.vercel.app/tools/config-directories/index.md) for general concepts.

Cursor stores its configuration in `~/.cursor/`:

| File/Directory | Purpose                          |
| -------------- | -------------------------------- |
| `mcp.json`     | MCP server definitions           |
| `rules/`       | Development rules (`.mdc` files) |
| `commands/`    | Custom slash commands            |

### MCP Configuration

```json
// ~/.cursor/mcp.json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@context7/mcp"]
    }
  }
}
```

### Cursor Rules

Cursor rules (`.mdc` files) define coding standards and AI behavior. Place them in `~/.cursor/rules/` for global rules or `project/.cursor/rules/` for project-specific rules.

[Cursor Rules Guide](https://vibecoding-navy.vercel.app/resources/cursor-rules/index.md)

## Tips & Tricks

Community Tips

This section collects tips from real users. [Contribute your tips](https://vibecoding-navy.vercel.app/community/contributing/index.md)!

**Keyboard shortcuts:**

- `Cmd/Ctrl + K` - Open AI chat inline
- `Cmd/Ctrl + L` - Open AI chat panel
- `Cmd/Ctrl + Shift + K` - Generate code

**Workflow tips:**

- Use `@codebase` to give the AI context about your entire project
- Use `@docs` to reference documentation
- Create custom rules for your coding standards

## Common Issues

**"Model not responding"**

- Check your API key in settings
- Verify your subscription status
- Try switching to a different model

**"Rules not loading"**

- Ensure rules are in `.cursor/rules/` directory
- Check file extension is `.mdc`
- Restart Cursor after adding rules

## Community Resources

- [agents-environment-config](https://vibecoding-navy.vercel.app/resources/agents-environment-config/index.md) - Shared Cursor configurations
- [Cursor Rules Guide](https://vibecoding-navy.vercel.app/resources/cursor-rules/index.md) - How to write effective rules

______________________________________________________________________

Help Improve This Page

Know a tip that's not listed? Found a helpful video tutorial? [Contribute to this page](https://vibecoding-navy.vercel.app/community/contributing/index.md).

# VS Code + GitHub Copilot

> **Official Docs**: [docs.github.com/copilot](https://docs.github.com/en/copilot) **Category**: IDE Extension

GitHub Copilot brings AI code completion to Visual Studio Code, integrating with your existing VS Code workflow.

## Quick Links

- [GitHub Copilot Documentation](https://docs.github.com/en/copilot)
- [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot)
- [Copilot Chat Extension](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat)

Works With

GitHub Copilot is powered by [OpenAI's models](https://vibecoding-navy.vercel.app/tools/models/openai/index.md), including GPT-4.

## Configuration

> See [Understanding Config Directories](https://vibecoding-navy.vercel.app/tools/config-directories/index.md) for general concepts.

Copilot configuration lives in VS Code's settings:

| Setting Location                  | Purpose                           |
| --------------------------------- | --------------------------------- |
| VS Code Settings                  | Enable/disable, keybindings       |
| GitHub Account                    | Subscription, organization access |
| `.github/copilot-instructions.md` | Project-specific instructions     |

### Project Instructions

Create a `.github/copilot-instructions.md` file in your repository to give Copilot context about your project:

```markdown
# Copilot Instructions

This is a React + TypeScript project using:
- React 18
- TypeScript 5
- Tailwind CSS

Prefer functional components with hooks.
Use TypeScript strict mode.
```

## Tips & Tricks

Community Tips

This section collects tips from real users. [Contribute your tips](https://vibecoding-navy.vercel.app/community/contributing/index.md)!

**Keyboard shortcuts:**

- `Tab` - Accept suggestion
- `Esc` - Dismiss suggestion
- `Alt + ]` / `Alt + [` - Next/previous suggestion

**Getting better suggestions:**

- Write clear comments describing what you want
- Use descriptive function and variable names
- Keep files focused on single responsibilities

## Common Issues

**"Copilot not suggesting"**

- Check you're signed in to GitHub
- Verify your subscription is active
- Ensure the file type is supported

**"Suggestions are off-topic"**

- Add a `.github/copilot-instructions.md` file
- Write clearer comments before code
- Check if the context window is cluttered

## Community Resources

- [GitHub Copilot Community](https://github.com/orgs/community/discussions/categories/copilot)
- [VS Code Extension Marketplace](https://marketplace.visualstudio.com/)

______________________________________________________________________

Help Improve This Page

Know a tip that's not listed? Found a helpful video tutorial? [Contribute to this page](https://vibecoding-navy.vercel.app/community/contributing/index.md).

# Windsurf

> **Official Docs**: [codeium.com/windsurf](https://codeium.com/windsurf) **Category**: IDE

Windsurf is an AI-native IDE from Codeium, designed from the ground up for AI-assisted development.

## Quick Links

- [Official Website](https://codeium.com/windsurf)
- [Codeium Documentation](https://codeium.com/docs)
- [Download Windsurf](https://codeium.com/windsurf)

Works With

Windsurf uses Codeium's AI models and also supports [Claude](https://vibecoding-navy.vercel.app/tools/ides/models/claude.md) and [GPT-4](https://vibecoding-navy.vercel.app/tools/models/openai/index.md).

## Configuration

> See [Understanding Config Directories](https://vibecoding-navy.vercel.app/tools/config-directories/index.md) for general concepts.

Windsurf stores configuration in its application data directory. The exact location varies by platform:

| Platform | Location                                  |
| -------- | ----------------------------------------- |
| macOS    | `~/Library/Application Support/Windsurf/` |
| Windows  | `%APPDATA%\Windsurf\`                     |
| Linux    | `~/.config/Windsurf/`                     |

## Tips & Tricks

Community Tips

This section collects tips from real users. [Contribute your tips](https://vibecoding-navy.vercel.app/community/contributing/index.md)!

*Tips coming soon! [Be the first to contribute](https://vibecoding-navy.vercel.app/community/contributing/index.md).*

## Common Issues

*Common issues and solutions coming soon!*

## Community Resources

- [Codeium Discord](https://discord.gg/codeium) - Official community

______________________________________________________________________

Help Improve This Page

Know a tip that's not listed? Found a helpful video tutorial? [Contribute to this page](https://vibecoding-navy.vercel.app/community/contributing/index.md).

# Aider

> **Official Docs**: [aider.chat](https://aider.chat/) **Category**: CLI

Aider is an open-source AI pair programming tool that works in your terminal. It supports multiple AI models and integrates with git.

## Quick Links

- [Official Website](https://aider.chat/)
- [GitHub Repository](https://github.com/paul-gauthier/aider)
- [Documentation](https://aider.chat/docs/)
- [Discord Community](https://discord.gg/Tv2uQnR88V)

Works With

Aider supports multiple models including [Claude](https://vibecoding-navy.vercel.app/tools/cli/models/claude.md), [GPT-4](https://vibecoding-navy.vercel.app/tools/models/openai/index.md), and local models via Ollama.

## Configuration

> See [Understanding Config Directories](https://vibecoding-navy.vercel.app/tools/config-directories/index.md) for general concepts.

Aider can be configured via:

| Method                | Location                             |
| --------------------- | ------------------------------------ |
| Command line flags    | Per-session                          |
| Environment variables | `AIDER_*` variables                  |
| Config file           | `.aider.conf.yml` in project or home |
| Git config            | `.aider` section in `.git/config`    |

### Configuration File

```yaml
# ~/.aider.conf.yml or project/.aider.conf.yml
model: claude-3-5-sonnet-20241022
auto-commits: true
dark-mode: true
```

### Environment Variables

```bash
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export AIDER_MODEL="claude-3-5-sonnet-20241022"
```

## Tips & Tricks

Community Tips

This section collects tips from real users. [Contribute your tips](https://vibecoding-navy.vercel.app/community/contributing/index.md)!

**Useful commands:**

- `/add file.py` - Add file to context
- `/drop file.py` - Remove file from context
- `/undo` - Undo last change
- `/diff` - Show pending changes
- `/commit` - Commit changes

**Workflow tips:**

- Start with small, focused changes
- Use `/add` to give Aider context about related files
- Review diffs before committing
- Aider auto-commits by default - use `--no-auto-commits` if you prefer manual control

**Model selection:**

```bash
# Use Claude
aider --model claude-3-5-sonnet-20241022

# Use GPT-4
aider --model gpt-4-turbo

# Use local model via Ollama
aider --model ollama/codellama
```

## Common Issues

**"Model not found"**

- Check you have the correct API key set
- Verify the model name is correct
- For Ollama, ensure the model is downloaded

**"Git repository required"**

- Aider works best in git repos
- Initialize with `git init` if needed
- Or use `--no-git` flag

**"Context too large"**

- Use `/drop` to remove unnecessary files
- Be selective about which files to `/add`
- Consider using a model with larger context

## Community Resources

- [Aider Discord](https://discord.gg/Tv2uQnR88V) - Active community
- [GitHub Discussions](https://github.com/paul-gauthier/aider/discussions)
- [Aider Blog](https://aider.chat/blog/)

______________________________________________________________________

Help Improve This Page

Know a tip that's not listed? Found a helpful video tutorial? [Contribute to this page](https://vibecoding-navy.vercel.app/community/contributing/index.md).

# Claude Code

> **Official Docs**: [docs.anthropic.com/claude-code](https://docs.anthropic.com/en/docs/claude-code) **Category**: CLI

Claude Code is Anthropic's official command-line interface for working with Claude. It provides a powerful terminal-based AI coding experience.

## Quick Links

- [Official Documentation](https://docs.anthropic.com/en/docs/claude-code)
- [GitHub Repository](https://github.com/anthropics/claude-code)
- [Anthropic Discord](https://discord.gg/anthropic)

Works With

Claude Code uses [Claude](https://vibecoding-navy.vercel.app/tools/cli/models/claude.md) models exclusively - Sonnet, Opus, and Haiku.

## Configuration

> See [Understanding Config Directories](https://vibecoding-navy.vercel.app/tools/config-directories/index.md) for general concepts.

Claude Code stores its configuration in `~/.claude/`:

| File/Directory        | Purpose                                |
| --------------------- | -------------------------------------- |
| `settings.json`       | User settings, API keys, preferences   |
| `settings.local.json` | Machine-specific settings (not synced) |
| `CLAUDE.md`           | Global agent instructions              |
| `agents/`             | Custom agent definitions               |
| `skills/`             | Custom skills and commands             |
| `statusline.sh`       | Custom statusline script               |
| `projects/`           | Project-specific settings              |

### Global Instructions (CLAUDE.md)

The `~/.claude/CLAUDE.md` file contains instructions that apply to all your Claude Code sessions:

```markdown
# My Development Preferences

- Use TypeScript with strict mode
- Prefer functional programming patterns
- Always include error handling
- Write tests for new functions
```

### Project Instructions

Create a `CLAUDE.md` in your project root for project-specific instructions:

```markdown
# Project: My App

This is a Next.js 14 app with:
- App Router
- Prisma + PostgreSQL
- Tailwind CSS

Follow the patterns in existing code.
```

## Tips & Tricks

Community Tips

This section collects tips from real users. [Contribute your tips](https://vibecoding-navy.vercel.app/community/contributing/index.md)!

**Useful commands:**

- `/help` - Show available commands
- `/clear` - Clear conversation
- `/compact` - Summarize conversation
- `/cost` - Show token usage

**Workflow tips:**

- Start sessions with clear context about what you're working on
- Use CLAUDE.md files to avoid repeating instructions
- The `/compact` command helps when conversations get long

**Custom statusline:**

Customize your terminal statusline to show model, tokens, and git info:

```bash
# ~/.claude/statusline.sh
echo "Claude | $MODEL | $TOKENS tokens | $GIT_BRANCH"
```

## Common Issues

**"API key not found"**

- Set `ANTHROPIC_API_KEY` environment variable
- Or add to `~/.claude/settings.json`

**"Context too long"**

- Use `/compact` to summarize
- Start a new session with `/clear`
- Be more specific in your requests

**"CLAUDE.md not loading"**

- Check file is in project root or `~/.claude/`
- Verify file permissions
- Restart Claude Code

## Community Resources

- [agents-environment-config](https://vibecoding-navy.vercel.app/resources/agents-environment-config/index.md) - Shared Claude configurations
- [Anthropic Discord](https://discord.gg/anthropic) - Official community

______________________________________________________________________

Help Improve This Page

Know a tip that's not listed? Found a helpful video tutorial? [Contribute to this page](https://vibecoding-navy.vercel.app/community/contributing/index.md).

# Codex CLI

> **Official Docs**: [openai.github.io/codex-cli](https://openai.github.io/codex-cli/) **Category**: CLI

OpenAI's Codex CLI is a command-line tool for AI-assisted coding using OpenAI's models.

## Quick Links

- [GitHub Repository](https://github.com/openai/codex-cli)
- [OpenAI Documentation](https://platform.openai.com/docs)
- [OpenAI Community](https://community.openai.com/)

Works With

Codex CLI uses [OpenAI models](https://vibecoding-navy.vercel.app/tools/models/openai/index.md) including GPT-4 and GPT-4 Turbo.

## Configuration

> See [Understanding Config Directories](https://vibecoding-navy.vercel.app/tools/config-directories/index.md) for general concepts.

Codex CLI stores its configuration in `~/.codex/`:

| File          | Purpose                          |
| ------------- | -------------------------------- |
| `config.toml` | Main configuration (TOML format) |

### Configuration File

```toml
# ~/.codex/config.toml
[model]
name = "gpt-4"
temperature = 0.7

[api]
key = "sk-..."  # Or use OPENAI_API_KEY env var
```

## Tips & Tricks

Community Tips

This section collects tips from real users. [Contribute your tips](https://vibecoding-navy.vercel.app/community/contributing/index.md)!

*Tips coming soon! [Be the first to contribute](https://vibecoding-navy.vercel.app/community/contributing/index.md).*

## Common Issues

**"API key invalid"**

- Check your OpenAI API key
- Verify billing is set up on OpenAI account
- Try regenerating the key

## Community Resources

- [OpenAI Community Forum](https://community.openai.com/)
- [OpenAI Discord](https://discord.gg/openai)

______________________________________________________________________

Help Improve This Page

Know a tip that's not listed? Found a helpful video tutorial? [Contribute to this page](https://vibecoding-navy.vercel.app/community/contributing/index.md).

# OpenAI / ChatGPT

> **Official Docs**: [platform.openai.com/docs](https://platform.openai.com/docs) **Category**: AI Model

OpenAI's GPT models power GitHub Copilot and many other AI coding tools.

## Quick Links

- [OpenAI Platform Documentation](https://platform.openai.com/docs)
- [API Reference](https://platform.openai.com/docs/api-reference)
- [OpenAI Developer Forum](https://community.openai.com/)
- [ChatGPT](https://chat.openai.com/)

Used By

OpenAI models power [GitHub Copilot](https://vibecoding-navy.vercel.app/tools/ides/vscode-copilot/index.md), [Cursor](https://vibecoding-navy.vercel.app/tools/ides/cursor/index.md), [Codex CLI](https://vibecoding-navy.vercel.app/tools/cli/codex/index.md), and [Aider](https://vibecoding-navy.vercel.app/tools/cli/aider/index.md).

## Model Variants

| Model       | Best For             | Context Window |
| ----------- | -------------------- | -------------- |
| GPT-4 Turbo | Complex coding tasks | 128K tokens    |
| GPT-4o      | Balanced performance | 128K tokens    |
| GPT-4o Mini | Cost-effective tasks | 128K tokens    |
| o1          | Complex reasoning    | Varies         |

## API Setup

### Get an API Key

1. Create an account at [platform.openai.com](https://platform.openai.com/)
1. Navigate to API Keys
1. Create a new key
1. Set up billing

### Set Environment Variable

```bash
export OPENAI_API_KEY="sk-..."
```

Or add to your shell profile:

```bash
echo 'export OPENAI_API_KEY="sk-..."' >> ~/.zshrc
```

## Tips & Tricks

Community Tips

This section collects tips from real users. [Contribute your tips](https://vibecoding-navy.vercel.app/community/contributing/index.md)!

**Model selection:**

- **GPT-4 Turbo**: Best for complex coding tasks
- **GPT-4o**: Good balance of speed and capability
- **GPT-4o Mini**: Cost-effective for simpler tasks
- **o1**: Use for problems requiring deep reasoning

**Prompting tips:**

- Be specific about the programming language and framework
- Provide examples of desired output format
- Use system prompts to set coding style preferences

## Common Issues

**"Rate limited"**

- Check your tier and limits at platform.openai.com
- Implement exponential backoff
- Consider upgrading your tier

**"Unexpected behavior"**

- GPT models can be more creative/variable than Claude
- Be more explicit in your instructions
- Consider using a system prompt for consistency

## Community Resources

- [OpenAI Developer Forum](https://community.openai.com/)
- [r/OpenAI](https://reddit.com/r/OpenAI)
- [OpenAI Discord](https://discord.gg/openai)

______________________________________________________________________

Help Improve This Page

Know a tip that's not listed? Found a helpful video tutorial? [Contribute to this page](https://vibecoding-navy.vercel.app/community/contributing/index.md).
# Local Development

# Local Development with AI

Working with AI coding assistants locally gives you the most control over your development environment. This section covers how to set up and optimize your local AI-assisted workflow.

## Getting Started

- **IDE vs CLI**

  ______________________________________________________________________

  Choose between graphical IDEs and terminal-based tools based on your workflow.

  [Compare approaches](https://vibecoding-navy.vercel.app/local-dev/ide-vs-cli/index.md)

- **Environment Setup**

  ______________________________________________________________________

  Configure your local environment for AI-assisted development.

  [Set up your environment](https://vibecoding-navy.vercel.app/local-dev/environment-setup/index.md)

- **Planning Your Work**

  ______________________________________________________________________

  Approaches to planning and organizing AI-assisted projects.

  [Planning strategies](https://vibecoding-navy.vercel.app/local-dev/planning/local-planning/index.md)

## Why Work Locally?

Working with AI tools on your local machine offers several advantages:

| Benefit           | Description                                         |
| ----------------- | --------------------------------------------------- |
| **Privacy**       | Your code stays on your machine (depending on tool) |
| **Speed**         | No network latency for file operations              |
| **Control**       | Full access to your development environment         |
| **Integration**   | Works with your existing tools and workflows        |
| **Customization** | Extensive configuration options                     |

## The Local AI Stack

A typical local AI development setup includes:

```text
┌─────────────────────────────────────────────┐
│              Your Codebase                  │
├─────────────────────────────────────────────┤
│     IDE (Cursor, VS Code, Windsurf)         │
│              or                              │
│     CLI (Claude Code, Aider, Codex)         │
├─────────────────────────────────────────────┤
│     Config (~/.cursor, ~/.claude, etc.)     │
├─────────────────────────────────────────────┤
│     AI Model API (Claude, GPT-4, etc.)      │
└─────────────────────────────────────────────┘
```

## Quick Comparison

| Approach      | Best For                              | Learning Curve | Flexibility |
| ------------- | ------------------------------------- | -------------- | ----------- |
| **IDE-based** | Visual learners, integrated workflows | Gentle         | Medium      |
| **CLI-based** | Power users, automation, scripting    | Steeper        | High        |
| **Hybrid**    | Complex projects, team collaboration  | Medium         | Highest     |

[Detailed comparison](https://vibecoding-navy.vercel.app/local-dev/ide-vs-cli/index.md)

## Essential Concepts

### Configuration Directories

AI tools store settings in your home directory (`~/.cursor`, `~/.claude`, etc.). Understanding these is key to customization.

[Config directory guide](https://vibecoding-navy.vercel.app/tools/config-directories/index.md)

### MCP (Model Context Protocol)

MCP servers extend what AI tools can do - from browsing documentation to controlling browsers.

[Learn about MCP](https://vibecoding-navy.vercel.app/tools/config-directories/#mcp-model-context-protocol)

### Project vs Global Config

Most tools support both global settings (your preferences) and project settings (team standards).

[Global vs project config](https://vibecoding-navy.vercel.app/tools/config-directories/#what-goes-where-global-vs-project)

## Planning Your Work

How you plan and organize your AI-assisted work significantly impacts results:

- **[Local Planning](https://vibecoding-navy.vercel.app/local-dev/planning/local-planning/index.md)** - Using markdown files, comments, and local tools
- **[BrainGrid](https://vibecoding-navy.vercel.app/local-dev/planning/braingrid/index.md)** - External tool for structured requirements

## Next Steps

1. **[Compare IDE vs CLI](https://vibecoding-navy.vercel.app/local-dev/ide-vs-cli/index.md)** - Decide which approach fits your workflow
1. **[Set up your environment](https://vibecoding-navy.vercel.app/local-dev/environment-setup/index.md)** - Get your local setup ready
1. **[Explore tools](https://vibecoding-navy.vercel.app/tools/index.md)** - Deep dive into specific tools
1. **[Community resources](https://vibecoding-navy.vercel.app/resources/index.md)** - Shared configurations and best practices

# IDE vs CLI: Choosing Your Workflow

Both graphical IDEs and command-line tools can supercharge your AI-assisted development. Understanding the tradeoffs helps you choose the right approach.

## Quick Comparison

| Aspect                   | IDE (Cursor, Windsurf)      | CLI (Claude Code, Aider)   |
| ------------------------ | --------------------------- | -------------------------- |
| **Learning curve**       | Gentle                      | Steeper                    |
| **Visual feedback**      | Rich UI, inline suggestions | Terminal output            |
| **Customization**        | Limited to IDE features     | Highly scriptable          |
| **Resource usage**       | Higher (full IDE)           | Lower (terminal only)      |
| **Workflow integration** | Built-in git, debugging     | Composable with Unix tools |
| **Speed for experts**    | Fast                        | Potentially faster         |

## IDE-Based Development

### Strengths

- **Visual context** - See code, AI suggestions, and diffs side-by-side
- **Familiar interface** - If you use VS Code, Cursor feels natural
- **Integrated features** - Git, debugging, extensions all in one place
- **Lower barrier** - Point and click, less to memorize

### Best For

- Developers who prefer visual interfaces
- Teams with mixed experience levels
- Projects requiring heavy debugging
- When you want everything in one window

### Popular Options

- [Cursor](https://vibecoding-navy.vercel.app/tools/ides/cursor/index.md) - VS Code fork with deep AI integration
- [Windsurf](https://vibecoding-navy.vercel.app/tools/ides/windsurf/index.md) - AI-native IDE from Codeium
- [VS Code + Copilot](https://vibecoding-navy.vercel.app/tools/ides/vscode-copilot/index.md) - Add AI to existing VS Code setup

## CLI-Based Development

### Strengths

- **Speed** - No GUI overhead, keyboard-only workflow
- **Scriptability** - Pipe output, chain commands, automate
- **Remote work** - Works great over SSH
- **Focus** - Fewer distractions, just you and the terminal
- **Resource efficiency** - Runs anywhere, even on minimal machines

### Best For

- Power users comfortable with terminals
- Remote development and SSH workflows
- Automation and scripting scenarios
- When you want maximum control

### Popular Options

- [Claude Code](https://vibecoding-navy.vercel.app/tools/cli/claude-code/index.md) - Anthropic's official CLI
- [Aider](https://vibecoding-navy.vercel.app/tools/cli/aider/index.md) - Open-source, multi-model support
- [Codex CLI](https://vibecoding-navy.vercel.app/tools/cli/codex/index.md) - OpenAI's command-line tool

## Hybrid Approach

Many developers use both:

```text
┌─────────────────────────────────────────────┐
│  Complex tasks, debugging    →   IDE        │
│  Quick edits, automation     →   CLI        │
│  Remote servers              →   CLI        │
│  Pair programming            →   IDE        │
│  Batch processing            →   CLI        │
└─────────────────────────────────────────────┘
```

### Example Workflow

1. **Planning**: Use CLI for quick iterations on requirements
1. **Implementation**: Use IDE for visual feedback while coding
1. **Debugging**: Use IDE's debugger with AI assistance
1. **Refactoring**: Use CLI for batch operations across files
1. **Review**: Use IDE for visual diff review

## Making the Choice

### Choose IDE If...

- You're new to AI coding tools
- Visual feedback helps you understand changes
- You work on projects requiring heavy debugging
- Your team standardizes on a specific IDE

### Choose CLI If...

- You live in the terminal
- You value scriptability and automation
- You work on remote servers frequently
- You want the lightest possible setup

### Try Both!

Nothing stops you from having both installed:

```bash
# Quick task in terminal
claude "add error handling to auth.ts"

# Complex feature in IDE
cursor .
```

## Configuration Considerations

Both approaches use similar configuration patterns:

| Tool Type | Global Config                | Project Config      |
| --------- | ---------------------------- | ------------------- |
| IDE       | `~/.cursor/`, `~/.windsurf/` | `project/.cursor/`  |
| CLI       | `~/.claude/`, `~/.aider/`    | `project/CLAUDE.md` |

[Understanding Config Directories](https://vibecoding-navy.vercel.app/tools/config-directories/index.md)

## Real-World Scenarios

### Scenario: Bug Fix

**IDE approach:**

1. Open project in Cursor
1. Navigate to buggy file
1. Select code, ask AI to fix
1. Review inline diff
1. Accept or iterate

**CLI approach:**

1. `cd project && claude "fix the null pointer in auth.ts"`
1. Review terminal output
1. `git diff` to see changes
1. Iterate if needed

### Scenario: New Feature

**IDE approach:**

1. Open Cursor, describe feature in chat
1. AI creates files, you review in editor
1. Use debugger to test
1. Iterate visually

**CLI approach:**

1. Write spec in markdown
1. `aider --message "implement feature per spec.md"`
1. Review changes, test in terminal
1. Iterate with follow-up commands

## Tips for Transitioning

### IDE → CLI

- Start with simple tasks (single-file edits)
- Learn the basic commands first
- Use `--help` liberally
- Keep IDE available as backup

### CLI → IDE

- Explore keyboard shortcuts
- Learn the AI chat interface
- Customize settings to match your terminal workflow
- Use command palette for quick actions

______________________________________________________________________

The Best Tool is the One You'll Use

There's no objectively "better" approach. Pick what fits your workflow and iterate from there.

# Environment Setup

Setting up your local environment for AI-assisted development involves configuring tools, API keys, and project settings.

## Prerequisites

Before starting, ensure you have:

- [ ] A code editor or IDE
- [ ] Terminal/command line access
- [ ] Git installed
- [ ] API keys for your chosen AI services

## API Keys

Most AI tools require API keys. Here's how to set them up:

### Anthropic (Claude)

1. Create account at [console.anthropic.com](https://console.anthropic.com/)
1. Generate API key
1. Set environment variable:

```bash
export ANTHROPIC_API_KEY="sk-ant-..."
```

### OpenAI

1. Create account at [platform.openai.com](https://platform.openai.com/)
1. Generate API key and set up billing
1. Set environment variable:

```bash
export OPENAI_API_KEY="sk-..."
```

### Google (Gemini)

1. Go to [Google AI Studio](https://aistudio.google.com/)
1. Generate API key
1. Set environment variable:

```bash
export GOOGLE_API_KEY="..."
```

## Persisting Environment Variables

Add keys to your shell profile so they persist:

```bash
# Add to ~/.zshrc
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."

# Reload
source ~/.zshrc
```

```bash
# Add to ~/.bashrc or ~/.bash_profile
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."

# Reload
source ~/.bashrc
```

```fish
# Add to ~/.config/fish/config.fish
set -gx ANTHROPIC_API_KEY "sk-ant-..."
set -gx OPENAI_API_KEY "sk-..."
```

```powershell
# Add to $PROFILE
$env:ANTHROPIC_API_KEY = "sk-ant-..."
$env:OPENAI_API_KEY = "sk-..."

# Or set system-wide via System Properties
```

Security Note

Never commit API keys to git. Use environment variables or `.env` files (and add `.env` to `.gitignore`).

## Tool Installation

### IDEs

```bash
# Download from cursor.com
# Or via Homebrew (macOS)
brew install --cask cursor
```

```bash
# Install VS Code
brew install --cask visual-studio-code

# Install Copilot extension from marketplace
```

```bash
# Download from codeium.com/windsurf
```

### CLI Tools

```bash
# Install via npm
npm install -g @anthropic-ai/claude-code

# Or via Homebrew
brew install anthropic/tap/claude-code
```

```bash
# Install via pip
pip install aider-chat

# Or via pipx (recommended)
pipx install aider-chat
```

```bash
# Install via npm
npm install -g @openai/codex-cli
```

## Configuration Directories

After installation, create your configuration directories:

```bash
# Create config directories
mkdir -p ~/.claude
mkdir -p ~/.cursor/rules

# Create global instructions
touch ~/.claude/CLAUDE.md
```

[Config Directory Reference](https://vibecoding-navy.vercel.app/tools/config-directories/index.md)

## Project Setup

### Initialize a Project

```bash
# Create project directory
mkdir my-project && cd my-project

# Initialize git
git init

# Create AI instructions
touch CLAUDE.md  # For Claude Code
mkdir -p .cursor/rules  # For Cursor
```

### Project Instructions Template

Create a `CLAUDE.md` (or similar) in your project root:

```markdown
# Project: My App

## Tech Stack
- Next.js 14 with App Router
- TypeScript (strict mode)
- Prisma + PostgreSQL
- Tailwind CSS

## Conventions
- Use functional components with hooks
- Prefer server components where possible
- Follow existing code patterns

## Important Files
- `src/app/` - App router pages
- `src/lib/` - Shared utilities
- `prisma/schema.prisma` - Database schema
```

## Verification

Test your setup:

### Test API Keys

```bash
# Test Anthropic
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-3-haiku-20240307","max_tokens":10,"messages":[{"role":"user","content":"Hi"}]}'
```

### Test Tools

```bash
# Test Claude Code
claude --version

# Test Aider
aider --version

# Open Cursor
cursor .
```

## Troubleshooting

### "API key not found"

1. Verify the key is set: `echo $ANTHROPIC_API_KEY`
1. Check for typos in variable name
1. Reload shell config: `source ~/.zshrc`

### "Command not found"

1. Verify installation: `which claude` or `which aider`
1. Check PATH includes install location
1. Try reinstalling the tool

### "Permission denied"

1. Check file permissions: `ls -la ~/.claude/`
1. Fix if needed: `chmod 755 ~/.claude/`

## Next Steps

- [Compare IDE vs CLI workflows](https://vibecoding-navy.vercel.app/local-dev/ide-vs-cli/index.md)
- [Explore available tools](https://vibecoding-navy.vercel.app/tools/index.md)
- [Set up shared configurations](https://vibecoding-navy.vercel.app/resources/agents-environment-config/index.md)

# BrainGrid

BrainGrid is an AI-powered tool for transforming vague ideas into structured specifications and development tasks.

Support Our Community

Support community members by using their affiliate links:

- **Matt Bernier**: [braingrid.link/matt-bernier](https://braingrid.link/matt-bernier)

*Want to add your affiliate link? [Edit this page on GitHub](https://github.com/mbernier/vibecoding/edit/main/docs/local-dev/planning/braingrid.md) and submit a PR!*

## What is BrainGrid?

BrainGrid helps you go from "I want to build X" to actionable development tasks:

```text
Vague idea → Structured specification → AI-ready tasks
```

It's particularly useful when:

- You have a fuzzy idea that needs structure
- You want AI to help refine requirements
- You need tasks formatted for AI coding agents
- You're working with non-technical stakeholders

## Local Planning vs BrainGrid

| Aspect            | Local Planning                   | BrainGrid                   |
| ----------------- | -------------------------------- | --------------------------- |
| **Setup**         | Just markdown files              | External service            |
| **AI assistance** | Manual prompting                 | Built-in refinement         |
| **Collaboration** | Git-based                        | Web-based                   |
| **Structure**     | Flexible                         | Standardized                |
| **Cost**          | Free                             | Subscription                |
| **Best for**      | Individual devs, simple projects | Teams, complex requirements |

## When to Use BrainGrid

**Good fit:**

- Complex features with many requirements
- Cross-functional teams
- When you need AI help structuring thoughts
- Projects requiring formal documentation

**May be overkill:**

- Quick bug fixes
- Personal projects
- Simple, well-understood features
- When you prefer local control

## BrainGrid Workflow

### 1. Start with a Prompt

```text
/specify "Add user authentication with OAuth support"
```

BrainGrid uses AI to ask clarifying questions and structure your requirements.

### 2. Get Structured Specification

The output is a detailed spec including:

- Goals and success criteria
- Technical requirements
- Edge cases
- Testing requirements

### 3. Break Down into Tasks

```text
/breakdown REQ-123
```

Creates AI-ready tasks that can be fed to coding agents.

### 4. Execute Tasks

Each task is formatted to work with AI coding tools like Claude Code, Cursor, or Aider.

## Integration with Local Development

BrainGrid complements local workflows:

```text
┌─────────────────────────────────────────────┐
│  BrainGrid                                  │
│  ├─ Define requirements                     │
│  ├─ Generate tasks                          │
│  └─ Export specs                            │
├─────────────────────────────────────────────┤
│  Local Development                          │
│  ├─ Import specs to plans/                  │
│  ├─ Execute with AI tools                   │
│  └─ Track progress locally                  │
└─────────────────────────────────────────────┘
```

### Example Integration

1. Define requirement in BrainGrid
1. Export specification as markdown
1. Save to `plans/` in your project
1. Reference in CLAUDE.md
1. Execute with your preferred tool

## Getting Started

1. **Sign up** at [braingrid.io](https://braingrid.link/matt-bernier) (affiliate link)
1. **Install CLI** (optional): `npm install -g @braingrid/cli`
1. **Link project**: `braingrid init`
1. **Start specifying**: `/specify "your idea"`

## CLI Commands Reference

```bash
# Authentication
braingrid login                    # OAuth login
braingrid whoami                   # Show current user

# Specifications
braingrid specify --prompt "..."   # Create requirement
braingrid requirement show REQ-123 # View requirement
braingrid requirement build REQ-123 --format markdown

# Tasks
braingrid requirement breakdown REQ-123  # Generate tasks
braingrid task list -r REQ-123          # List tasks
braingrid task update TASK-456 --status COMPLETED
```

## Tips

- Start broad, then refine
- Use `/specify` for initial ideation
- Use `/breakdown` when requirements are stable
- Export to markdown for local reference
- Combine with git branches for traceability

## Alternatives

If BrainGrid isn't right for you, consider:

- **[Local Planning](https://vibecoding-navy.vercel.app/local-dev/planning/local-planning/index.md)** - Markdown files in your repo
- **Linear/Jira** - Traditional project management
- **Notion** - Flexible documentation
- **GitHub Issues** - Native to your repository

## Related Resources

- [Local Planning Guide](https://vibecoding-navy.vercel.app/local-dev/planning/local-planning/index.md) - Markdown-based planning
- [Environment Setup](https://vibecoding-navy.vercel.app/local-dev/environment-setup/index.md) - Set up your dev environment
- [AI Tools Overview](https://vibecoding-navy.vercel.app/tools/index.md) - Coding tools to execute tasks

______________________________________________________________________

Affiliate Disclosure

Some links on this page are affiliate links. Using them supports the vibecoding community at no extra cost to you.

# Local Planning

Effective planning is crucial for AI-assisted development. This guide covers approaches to planning your work locally, without external tools.

## Why Plan?

AI coding assistants work best when given clear direction:

- **Better results** - Clear plans lead to more accurate AI output
- **Less iteration** - Upfront planning reduces back-and-forth
- **Maintainable code** - Planned architecture beats ad-hoc decisions
- **Team alignment** - Documented plans help collaboration

## Planning Approaches

### 1. Markdown Planning Files

The simplest approach: write plans in markdown files in your project.

```text
project/
├── plans/
│   ├── feature-auth.md
│   ├── refactor-api.md
│   └── bug-fix-123.md
├── src/
└── ...
```

**Example plan file:**

```markdown
# Feature: User Authentication

## Goal
Add email/password authentication with session management.

## Requirements
- [ ] Sign up with email/password
- [ ] Sign in with existing account
- [ ] Password reset flow
- [ ] Session management with JWT

## Technical Approach
- Use NextAuth.js for auth handling
- Store users in PostgreSQL via Prisma
- JWT tokens for API authentication

## Files to Create/Modify
- `src/app/api/auth/[...nextauth]/route.ts`
- `src/lib/auth.ts`
- `prisma/schema.prisma` (add User model)

## Open Questions
- Should we support OAuth providers initially?
- What's the session duration?
```

### 2. In-File Planning with Comments

For smaller tasks, plan directly in the code:

```typescript
// TODO: Implement user authentication
//
// Requirements:
// - Sign up with email/password
// - Sign in with existing account
// - Session management
//
// Approach:
// 1. Add User model to Prisma schema
// 2. Create auth API routes
// 3. Add session middleware

export async function signUp(email: string, password: string) {
  // Implementation coming...
}
```

### 3. CLAUDE.md as a Planning Tool

Use your project's `CLAUDE.md` to communicate plans to AI:

```markdown
# Project: My App

## Current Focus
Working on authentication feature. See `plans/feature-auth.md` for details.

## Conventions
...

## Recent Decisions
- Using NextAuth.js for auth (decided 2024-01-15)
- JWT for API tokens, sessions for web
```

### 4. Git Branch + Plan Pairing

Pair each feature branch with a planning document:

```bash
# Create branch
git checkout -b feature/user-auth

# Create plan
touch plans/feature-user-auth.md
```

## Planning Templates

### Feature Template

```markdown
# Feature: [Name]

## Problem
What problem does this solve?

## Solution
High-level approach.

## Requirements
- [ ] Requirement 1
- [ ] Requirement 2

## Technical Design
How will it be built?

## Files Affected
- `path/to/file.ts` - description
- `path/to/other.ts` - description

## Testing Strategy
How will it be tested?

## Rollout Plan
How will it be deployed?
```

### Bug Fix Template

```markdown
# Bug: [Description]

## Symptoms
What's happening?

## Root Cause
Why is it happening?

## Fix
What change will fix it?

## Files to Change
- `path/to/file.ts`

## Testing
How to verify the fix?

## Regression Prevention
How to prevent this in future?
```

### Refactoring Template

```markdown
# Refactor: [Name]

## Current State
What exists now?

## Desired State
What should it look like?

## Motivation
Why refactor?

## Approach
Step-by-step plan.

## Risk Assessment
What could go wrong?

## Rollback Plan
How to undo if needed?
```

## Working with AI

When planning with AI tools:

### Give Context First

```text
I'm planning to add user authentication. Here's my plan:
[paste plan]

Please review and suggest improvements before we start coding.
```

### Use Plans as Checkpoints

```text
We've completed steps 1-3 of the auth plan.
Current status: [describe]
Let's move to step 4: [describe]
```

### Update Plans Based on AI Feedback

AI might identify issues or improvements. Update your plans:

```markdown
## Technical Design

### Original Plan
- Use JWT stored in localStorage

### Updated (AI recommendation)
- Use HTTP-only cookies for better security
- Reasoning: Prevents XSS attacks from accessing tokens
```

## Organization Tips

### Folder Structure

```text
plans/
├── completed/          # Done plans (for reference)
├── in-progress/        # Current work
│   ├── feature-auth.md
│   └── refactor-api.md
└── backlog/            # Future work
    ├── feature-notifications.md
    └── feature-analytics.md
```

### Naming Conventions

- `feature-[name].md` - New features
- `bug-[id]-[description].md` - Bug fixes
- `refactor-[name].md` - Refactoring
- `spike-[name].md` - Research/exploration

### Version Control

Commit plans alongside code:

```bash
git add plans/feature-auth.md
git commit -m "docs: add authentication feature plan"
```

## When to Use External Tools

Local planning works well for:

- Individual developers
- Small teams
- Simple to medium complexity
- When you want full control

Consider external tools like [BrainGrid](https://vibecoding-navy.vercel.app/local-dev/planning/braingrid/index.md) when:

- You need structured requirement management
- Working with non-technical stakeholders
- Complex multi-phase projects
- When you want AI-assisted planning itself

[Learn about BrainGrid](https://vibecoding-navy.vercel.app/local-dev/planning/braingrid/index.md)

## Related Resources

- [Environment Setup](https://vibecoding-navy.vercel.app/local-dev/environment-setup/index.md) - Set up your local environment
- [IDE vs CLI](https://vibecoding-navy.vercel.app/local-dev/ide-vs-cli/index.md) - Choose your workflow
- [Config Directories](https://vibecoding-navy.vercel.app/tools/config-directories/index.md) - Tool configuration
# Guides

# Prompting Strategies

Effective prompting is the foundation of vibecoding. This guide covers strategies to get better results from AI coding assistants.

## The Anatomy of a Good Prompt

A well-structured prompt typically includes:

1. **Context** - Background information the AI needs
1. **Task** - What you want to accomplish
1. **Constraints** - Limitations or requirements
1. **Format** - How you want the response structured

### Template

```text
[CONTEXT]
I'm working on [project type] using [tech stack].
[Any relevant background or existing code]

[TASK]
I need to [specific goal].

[CONSTRAINTS]
- [Requirement 1]
- [Requirement 2]
- [Limitation]

[FORMAT]
Please provide [code/explanation/both] and [any specific formatting].
```

## Strategy 1: Be Specific

Vague prompts lead to generic responses. Compare:

Vague Prompt

"Write a function to handle users"

Specific Prompt

"Write a Python function that validates user registration data. It should check that the email is valid, the password is at least 8 characters with at least one number and one special character, and the username contains only alphanumeric characters."

## Strategy 2: Provide Context

Context helps the AI understand your specific situation:

```text
I'm building a REST API with FastAPI. The project uses SQLAlchemy
for the ORM and PostgreSQL as the database. We follow the repository
pattern for data access.

I need to add a new endpoint for user authentication. The endpoint
should accept email and password, verify against the database,
and return a JWT token.
```

## Strategy 3: Show Examples

When you have specific formatting or patterns in mind, show them:

```text
I need a function similar to this style:

def existing_function(data: dict) -> Result:
    """Process the data and return a Result object."""
    validated = validate(data)
    processed = transform(validated)
    return Result(success=True, data=processed)

Create a similar function for handling payment processing.
```

## Strategy 4: Chain Your Prompts

Break complex tasks into a series of smaller prompts:

1. "Help me design the data model for a todo list app"
1. "Now let's create the database schema based on this model"
1. "Create CRUD operations for the Task model"
1. "Add an endpoint to get all tasks for a user"
1. "Add filtering and pagination to the tasks endpoint"

## Strategy 5: Ask for Explanations

Don't just ask for code - ask for understanding:

```text
Create a function to debounce user input.
Please explain:
1. What debouncing is and why it's useful
2. How the implementation works
3. When I should use this pattern
```

## Strategy 6: Iterate with Feedback

Treat the AI as a collaborator:

```text
That looks good, but I need a few changes:
1. Add type hints to all function parameters
2. Include error handling for network failures
3. Add logging for debugging purposes
```

## Strategy 7: Request Multiple Options

When you're not sure of the best approach:

```text
I need to implement caching for my API responses.
Can you show me 2-3 different approaches with their pros and cons?
```

## Common Patterns

### Code Review

```text
Please review this code and suggest improvements:
[paste code]

Focus on:
- Performance
- Readability
- Error handling
- Security
```

### Debugging

```text
This code is throwing [error]. Here's the code:
[paste code]

And here's the full error:
[paste error]

What's causing this and how can I fix it?
```

### Refactoring

```text
Here's a function that works but is hard to read:
[paste code]

Please refactor it to:
1. Be more readable
2. Follow [language] best practices
3. Add appropriate error handling
```

### Learning

```text
I'm trying to understand [concept]. Can you:
1. Explain it in simple terms
2. Show a basic example
3. Show a more complex real-world example
4. Explain common mistakes to avoid
```

## Anti-Patterns to Avoid

Don't Do This

- **Too vague**: "Make it better"
- **Too broad**: "Build me a complete e-commerce platform"
- **Ambiguous**: "Fix the bug" (which bug?)
- **Missing context**: Asking about code the AI hasn't seen
- **Assuming knowledge**: Referencing project-specific terms without explanation

# AI Coding Assistants

A comprehensive guide to the AI coding assistants available for vibecoding. Each tool has its strengths and ideal use cases.

## Overview

| Assistant      | Best For                        | Integration       | Pricing          |
| -------------- | ------------------------------- | ----------------- | ---------------- |
| Claude         | Complex reasoning, long context | Web, API, CLI     | Free tier + paid |
| GitHub Copilot | Inline completions              | Editor extension  | Subscription     |
| Cursor         | Full IDE experience             | Standalone editor | Free tier + paid |
| ChatGPT        | General coding help             | Web, API          | Free tier + paid |

## Claude

[Claude](https://claude.ai) by Anthropic excels at understanding complex requirements and maintaining context over long conversations.

### Strengths

- Long context window (handles large codebases)
- Strong reasoning about architecture and design
- Excellent at explaining code and concepts
- [Claude Code CLI](https://claude.ai/claude-code) for terminal-based development

### Best Used For

- Architecture discussions and planning
- Code review and refactoring
- Complex debugging sessions
- Learning new concepts
- Working with multiple files

### Tips

```text
When working with Claude on code:
- Paste relevant code directly in your prompt
- Ask for explanations alongside code
- Use follow-up questions to dive deeper
- Request alternative approaches
```

## GitHub Copilot

[GitHub Copilot](https://github.com/features/copilot) integrates directly into your editor for real-time code suggestions.

### Strengths

- Seamless inline completions
- Learns from your codebase
- Fast suggestions while typing
- Good for boilerplate and patterns

### Best Used For

- Writing repetitive code
- Autocompleting function bodies
- Generating test cases
- Implementing standard patterns

### Tips

- Write descriptive function names and docstrings first
- Accept suggestions with Tab, reject with Esc
- Use comments to guide suggestions
- Open related files for better context

## Cursor

[Cursor](https://cursor.sh) is an AI-native code editor built for vibecoding workflows.

### Strengths

- Chat integrated into the editor
- Can read and modify files directly
- Understands project structure
- Combines chat and inline completion

### Best Used For

- Full development workflows
- Multi-file changes
- Project-wide refactoring
- Developers who want AI built into their editor

### Tips

- Use `Cmd+K` / `Ctrl+K` for inline chat
- Use `Cmd+L` / `Ctrl+L` for sidebar chat
- Add files to context with `@filename`
- Use codebase search for project-wide queries

## ChatGPT

[ChatGPT](https://chat.openai.com) with GPT-4 is a versatile option for coding assistance.

### Strengths

- Widely accessible
- Good for quick questions
- Plugin ecosystem
- Code interpreter for running Python

### Best Used For

- Quick coding questions
- Learning and tutorials
- Data analysis with Code Interpreter
- General programming help

### Tips

- Be explicit about language and framework
- Paste error messages completely
- Ask for step-by-step explanations
- Use system prompts for consistent behavior

## Choosing the Right Tool

### Decision Matrix

```text
Need inline completions while typing?
  --> GitHub Copilot or Cursor

Need to discuss architecture and design?
  --> Claude or ChatGPT

Want AI built into your editor?
  --> Cursor

Need to work with very large codebases?
  --> Claude (long context) or Cursor (codebase indexing)

Just getting started with AI coding?
  --> Start with ChatGPT free tier
```

### Combining Tools

Many developers use multiple tools together:

1. **Claude** for planning and complex reasoning
1. **Copilot/Cursor** for writing code
1. **ChatGPT** for quick questions and learning

## Best Practices Across All Tools

General Tips

1. **Verify generated code** - Always review before committing
1. **Understand what you commit** - Don't ship code you don't understand
1. **Test thoroughly** - AI can generate plausible but incorrect code
1. **Consider security** - Review for vulnerabilities
1. **Keep learning** - Use AI to accelerate learning, not replace it

# Best Practices

Guidelines for effective and responsible vibecoding. These practices will help you get better results while maintaining code quality and security.

## Code Quality

### Always Review Generated Code

AI can generate code that looks correct but has subtle issues:

- **Logic errors** - The code runs but doesn't do what you expect
- **Performance issues** - Inefficient algorithms or unnecessary operations
- **Security vulnerabilities** - SQL injection, XSS, insecure defaults
- **Missing edge cases** - Happy path works, error cases don't

Never Commit Without Review

Treat AI-generated code like code from a junior developer - it needs review before going to production.

### Understand What You Ship

If you can't explain how code works, you shouldn't ship it:

```text
Good: "I used this caching decorator because it memoizes expensive
      function calls and invalidates after 5 minutes."

Bad:  "The AI suggested this and it seems to work."
```

### Test Thoroughly

AI-generated code needs the same (or more) testing as human-written code:

- Unit tests for individual functions
- Integration tests for component interactions
- Edge case testing (empty inputs, large inputs, invalid data)
- Security testing for user-facing code

## Security

### Review for Vulnerabilities

Always check generated code for common security issues:

| Vulnerability | What to Look For                |
| ------------- | ------------------------------- |
| SQL Injection | String concatenation in queries |
| XSS           | Unescaped user input in HTML    |
| CSRF          | Missing token validation        |
| Auth bypass   | Missing permission checks       |
| Secrets       | Hardcoded API keys or passwords |

### Don't Share Sensitive Data

Be careful what you include in prompts:

Never Include in Prompts

- API keys and secrets
- Production database credentials
- Customer data or PII
- Proprietary business logic you don't want shared
- Access tokens

### Sanitize Before Sharing

When pasting code for review, remove or redact:

```python
# Before
api_key = "sk-abc123realkey456"
db_url = "postgresql://user:realpassword@prod.server.com/db"

# After
api_key = "sk-REDACTED"  # Replace with your API key
db_url = "postgresql://user:password@localhost/db"
```

## Efficiency

### Break Down Large Tasks

Instead of asking for an entire application, break it down:

```text
Step 1: "Help me design the data model"
Step 2: "Create the database schema"
Step 3: "Build the authentication system"
Step 4: "Add the core API endpoints"
Step 5: "Implement the frontend components"
```

### Provide Relevant Context

Give the AI what it needs, but not more:

```text
Good: "I have a FastAPI app using SQLAlchemy. Here's my User model:
      [paste model]. I need to add an endpoint to update user profiles."

Bad:  [Pastes entire codebase of 50 files]
```

### Iterate Quickly

Don't try to get everything perfect in one prompt:

1. Get a working version
1. Test it
1. Refine with follow-up prompts
1. Repeat until satisfied

## Learning

### Ask for Explanations

Use AI to learn, not just to generate:

```text
"Can you explain why you used a generator here instead of returning
a list? What are the trade-offs?"
```

### Compare Approaches

Learn about different solutions:

```text
"Show me how to implement this using:
1. A class-based approach
2. A functional approach
3. Using a library

What are the pros and cons of each?"
```

### Document Your Learnings

Keep notes on patterns that work well:

```markdown
## Vibecoding Notes

### Effective Patterns
- Using docstrings first helps generate better implementations
- Breaking authentication into steps: validation, verification, token generation
- Asking for error handling separately improves code structure

### Lessons Learned
- Always verify regex patterns with edge cases
- Generated SQL needs review for N+1 queries
- Date handling needs explicit timezone specification
```

## Workflow

### Version Control Everything

Commit frequently so you can revert if needed:

```bash
git add .
git commit -m "feat: add user validation (AI-assisted)"
```

### Use Descriptive Commits

Indicate when AI assisted with the code:

```text
feat: add email validation

- Validates email format using regex
- Checks for common typo domains
- AI-assisted implementation, reviewed for security
```

### Maintain Your Standards

AI should adapt to your codebase, not the other way around:

```text
"Here's our code style guide: [summary]
Please follow these conventions in all code you generate."
```

## Checklist

Before shipping AI-generated code:

- [ ] I understand how this code works
- [ ] I've reviewed for security vulnerabilities
- [ ] I've tested with normal inputs
- [ ] I've tested with edge cases
- [ ] I've tested with invalid inputs
- [ ] The code follows project conventions
- [ ] The code is properly documented
- [ ] I've removed any sensitive data
- [ ] The code passes all existing tests
- [ ] I can explain this code in a code review
# Resources

# Community Resources

The vibecoding community shares tools, configurations, and knowledge to help everyone work more effectively with AI coding assistants.

## Featured Resources

- **agents-environment-config**

  ______________________________________________________________________

  A complete configuration system for managing Claude, Cursor, Gemini, Qwen, and Codex settings in one place.

  [Usage guide](https://vibecoding-navy.vercel.app/resources/agents-environment-config/index.md)

- **Cursor Rules Guide**

  ______________________________________________________________________

  Learn how to create and customize Cursor rules to enforce coding standards and improve AI responses.

  [Cursor rules](https://vibecoding-navy.vercel.app/resources/cursor-rules/index.md)

## What's Available

### Configuration & Setup

| Resource                  | Description                  | Link                                                                                     |
| ------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------- |
| agents-environment-config | Multi-tool config management | [Guide](https://vibecoding-navy.vercel.app/resources/agents-environment-config/index.md) |
| Cursor Rules              | 43+ development rules        | [Guide](https://vibecoding-navy.vercel.app/resources/cursor-rules/index.md)              |

### Learning Resources

Check back as the community grows! We're collecting:

- Video tutorials from YouTube creators
- Blog posts and articles
- Example projects
- Workflow templates

## Contributing Resources

Have a resource to share? We welcome contributions!

- Configuration files and rules
- Tutorials and guides
- Tips and tricks
- Tool comparisons

[How to contribute](https://vibecoding-navy.vercel.app/community/contributing/index.md)

## Stay Updated

The AI coding landscape changes rapidly. These resources are maintained by the community:

- **GitHub Issues** - Report outdated information
- **Pull Requests** - Contribute updates directly
- **Discussions** - Share discoveries and ask questions

[Join the community](https://vibecoding-navy.vercel.app/community/contributing/index.md)

# agents-environment-config

A community resource for managing AI tool configurations across Claude, Cursor, Gemini, Qwen, and Codex.

> **Repository**: [github.com/bernierllc/agents-environment-config](https://github.com/bernierllc/agents-environment-config)
>
> **Full Documentation**: See the repo README for complete details

## What This Solves

Managing configurations across multiple AI tools is tedious:

- Each tool has its own config directory
- Rules and settings need to be synced
- Sharing configurations across machines is manual
- Keeping everything updated is error-prone

This repository provides:

- **One place** to manage all tool configs
- **Pre-built rules** you can use or customize
- **Automation scripts** to keep things in sync
- **MCP configurations** for multiple tools

## Quick Start

### Option 1: Clone and Symlink (Recommended)

```bash
# Clone the repository
git clone https://github.com/bernierllc/agents-environment-config ~/agents-environment-config

# Create symlinks to your home directory
ln -s ~/agents-environment-config/.claude ~/.claude
ln -s ~/agents-environment-config/.cursor ~/.cursor
ln -s ~/agents-environment-config/.gemini ~/.gemini
ln -s ~/agents-environment-config/.qwen ~/.qwen
ln -s ~/agents-environment-config/.codex ~/.codex
```

This approach means updates to the repo automatically apply to your tools.

### Option 2: Copy What You Need

```bash
# Clone temporarily
git clone https://github.com/bernierllc/agents-environment-config /tmp/agent-config

# Copy just what you need
cp -r /tmp/agent-config/.cursor/rules ~/.cursor/
cp /tmp/agent-config/.cursor/mcp.json ~/.cursor/

# Clean up
rm -rf /tmp/agent-config
```

### Option 3: Fork and Customize

1. Fork the repository on GitHub
1. Clone your fork
1. Customize for your needs
1. Symlink to your home directory

## What's Included

| Component              | Description                                      |
| ---------------------- | ------------------------------------------------ |
| **Cursor Rules**       | 43+ development rules in `.cursor/rules/`        |
| **MCP Configs**        | Pre-configured MCP servers for each tool         |
| **Agent Instructions** | `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `QWEN.md` |
| **Agents**             | Reusable agent definitions (via submodule)       |
| **Skills**             | Custom skills for Claude Code (via submodule)    |
| **Sync Scripts**       | Automation for keeping configs in sync           |
| **Statusline**         | Custom Claude Code statusline scripts            |

### Agents & Skills (Submodules)

The repository includes two Git submodules that provide reusable agents and skills:

#### Agents ([bernierllc/agency-agents](https://github.com/bernierllc/agency-agents))

Custom agent definitions that extend Claude Code's capabilities. Agents are reusable personalities/behaviors you can invoke for specific tasks.

- Located in `.claude/agents/`
- Synced to Cursor commands automatically
- See the [agency-agents README](https://github.com/bernierllc/agency-agents) for available agents and usage

#### Skills ([bernierllc/skills](https://github.com/bernierllc/skills))

Custom skills that add new capabilities to Claude Code. Skills are like plugins that teach Claude new workflows.

- Located in `.claude/skills/`
- Can be invoked during Claude Code sessions
- See the [skills README](https://github.com/bernierllc/skills) for available skills and how to create your own

Submodule Updates

When you `git pull` the main repo, also update submodules:

```bash
git pull
git submodule update --init --recursive
```

### Directory Structure

```text
agents-environment-config/
├── .claude/
│   ├── agents/           # Custom agents
│   ├── skills/           # Custom skills
│   ├── statusline.sh     # Statusline customization
│   └── CLAUDE.md         # Global instructions
├── .cursor/
│   ├── mcp.json          # MCP server config
│   ├── commands/         # Custom commands
│   └── rules/            # Development rules (43+ files)
├── .gemini/
│   └── settings.json     # Gemini MCP config
├── .qwen/
│   └── settings.json     # Qwen MCP config
├── .codex/
│   └── config.toml       # Codex config
└── scripts/
    ├── generate-agent-files.py
    └── sync-agents-skills.py
```

## Cursor Rules

The repository includes 43+ cursor rules organized by category:

### Categories

| Category       | Rules     | Examples                              |
| -------------- | --------- | ------------------------------------- |
| **General**    | 9 rules   | Architecture, workflow, documentation |
| **Languages**  | 2 rules   | Python, TypeScript                    |
| **Stacks**     | 3 rules   | Next.js, FastAPI, React Native        |
| **Frameworks** | 8 rules   | Prisma, Supabase, Tailwind            |
| **Topics**     | 11+ rules | API design, Git, Testing              |

[Full Cursor Rules Guide](https://vibecoding-navy.vercel.app/resources/cursor-rules/index.md)

## MCP Configuration

Pre-configured MCP servers for enhanced AI capabilities:

```json
// .cursor/mcp.json example
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@context7/mcp"]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-playwright"]
    }
  }
}
```

## Automation Scripts

### generate-agent-files.py

Generates tool-specific instruction files from cursor rules:

```bash
python scripts/generate-agent-files.py
# Creates: CLAUDE.md, AGENTS.md, GEMINI.md, QWEN.md
```

### sync-agents-skills.py

Syncs agents and skills to Cursor commands:

```bash
python scripts/sync-agents-skills.py
```

## Keeping Updated

If you used the symlink approach:

```bash
cd ~/agents-environment-config
git pull
```

Your tools automatically get the updates.

## Customization

### Adding Your Own Rules

Create rules in `.cursor/rules/`:

```markdown
---
description: My custom rule
alwaysApply: true
---

# My Rule

[Your rule content]
```

### Modifying MCP Config

Edit `.cursor/mcp.json` to add/remove MCP servers for your needs.

### Local Overrides

Create `settings.local.json` files (gitignored) for machine-specific settings.

## Troubleshooting

### "Symlink already exists"

```bash
# Remove existing symlink/directory first
rm -rf ~/.cursor
ln -s ~/agents-environment-config/.cursor ~/.cursor
```

### "Rules not loading"

1. Check symlinks are correct: `ls -la ~/.cursor`
1. Restart your tool
1. Verify file permissions

### "MCP server not starting"

1. Install required npm packages: `npm install -g @context7/mcp`
1. Check server logs
1. Verify configuration syntax

## Related Pages

- [Cursor Rules Guide](https://vibecoding-navy.vercel.app/resources/cursor-rules/index.md) - How to write and use rules
- [Config Directories](https://vibecoding-navy.vercel.app/tools/config-directories/index.md) - Where configs live
- [Cursor Setup](https://vibecoding-navy.vercel.app/tools/ides/cursor/index.md) - Cursor-specific setup

______________________________________________________________________

> For complete documentation and the latest updates, see the [GitHub repository](https://github.com/bernierllc/agents-environment-config).

# Cursor Rules Guide

Cursor rules (`.mdc` files) customize how Cursor's AI behaves in your projects. They define coding standards, patterns, and instructions that the AI follows.

## What Are Cursor Rules?

Cursor rules are markdown files with special frontmatter that tell Cursor how to behave:

```markdown
---
description: TypeScript strict mode standards
alwaysApply: false
globs:
  - "**/*.ts"
  - "**/*.tsx"
---

# TypeScript Standards

- Use strict mode
- No `any` types
- Explicit return types on public functions
```

## Rule Locations

| Location                 | Scope   | Use For                 |
| ------------------------ | ------- | ----------------------- |
| `~/.cursor/rules/`       | Global  | Your personal standards |
| `project/.cursor/rules/` | Project | Team/project standards  |

Project rules take precedence when they conflict with global rules.

## Anatomy of a Rule

```markdown
---
description: Brief description of what this rule does
alwaysApply: true          # Apply to all files?
globs:                      # Or apply to specific patterns
  - "**/*.ts"
  - "**/*.tsx"
tags:
  - typescript
  - frontend
---

# Rule Title

Your rule content in markdown...

## Section 1
Guidelines...

## Section 2
More guidelines...
```

### Frontmatter Options

| Field         | Type    | Description                                 |
| ------------- | ------- | ------------------------------------------- |
| `description` | string  | Brief description (shown in UI)             |
| `alwaysApply` | boolean | If true, applies to all files               |
| `globs`       | array   | File patterns to match (if not alwaysApply) |
| `tags`        | array   | Categorization tags                         |

## Creating Rules

### Step 1: Create the Directory

```bash
mkdir -p ~/.cursor/rules
# or for project-specific
mkdir -p .cursor/rules
```

### Step 2: Create a Rule File

```bash
touch ~/.cursor/rules/my-standards.mdc
```

### Step 3: Write Your Rule

```markdown
---
description: My coding standards
alwaysApply: true
---

# My Coding Standards

## Code Style
- Use 2-space indentation
- Prefer const over let
- Use descriptive variable names

## Comments
- Comment complex logic
- Use JSDoc for public functions
```

### Step 4: Restart Cursor

Rules are loaded when Cursor starts. Restart to pick up changes.

## Rule Examples

### TypeScript Standards

```markdown
---
description: TypeScript strict typing standards
alwaysApply: false
globs:
  - "**/*.ts"
  - "**/*.tsx"
---

# TypeScript Standards

## Zero Tolerance for `any`
- NEVER use `any` type
- Prefer `unknown` when type is truly unknown
- Always define explicit types for function parameters

## Type Safety
- Enable strict mode in tsconfig.json
- Explicit return types on public functions
- Use proper interface/type definitions

## React Components
- All props must be typed
- Use `React.FC<Props>` or explicit prop types
```

### Python Style

```markdown
---
description: Python code style and conventions
alwaysApply: false
globs:
  - "**/*.py"
---

# Python Standards

## Formatting
- Follow PEP 8
- Use Black formatter (line length 88)
- Use type hints everywhere

## Imports
- Group: standard library, third-party, local
- Use absolute imports

## Documentation
- Google-style docstrings
- Document all public functions
```

### Project Architecture

```markdown
---
description: Project architecture and patterns
alwaysApply: true
---

# Architecture Guidelines

## Directory Structure
- `src/app/` - Next.js app router pages
- `src/components/` - React components
- `src/lib/` - Utilities and helpers
- `src/types/` - TypeScript types

## Patterns
- Use server components by default
- Client components only when needed (state, effects)
- Prefer composition over inheritance

## Naming
- PascalCase for components
- camelCase for functions and variables
- SCREAMING_SNAKE for constants
```

## Organization

### Recommended Structure

```text
.cursor/rules/
├── general/
│   ├── architecture.mdc
│   ├── documentation.mdc
│   └── security.mdc
├── languages/
│   ├── typescript.mdc
│   └── python.mdc
├── frameworks/
│   ├── nextjs.mdc
│   └── react.mdc
└── project/
    └── conventions.mdc
```

### Naming Conventions

- Use descriptive, lowercase names
- Use hyphens for spaces
- Group related rules in directories

## Community Rules

The [agents-environment-config](https://vibecoding-navy.vercel.app/resources/agents-environment-config/index.md) repository includes 43+ pre-built rules:

- Architecture and design patterns
- Language-specific standards (TypeScript, Python)
- Framework patterns (Next.js, FastAPI, React Native)
- Testing standards
- Security guidelines
- Git workflow

[Get community rules](https://vibecoding-navy.vercel.app/resources/agents-environment-config/index.md)

## Best Practices

### Keep Rules Focused

❌ One giant rule file with everything

✅ Multiple focused rules by topic

### Be Specific

❌ "Write good code"

✅ "Use TypeScript strict mode, no `any` types, explicit return types"

### Include Examples

````markdown
## Naming Conventions

### Good
```typescript
const userProfile = getUserProfile();
const isAuthenticated = checkAuth();
````

### Bad

```typescript
const x = getUP();
const flag = check();
```

````

### Update Regularly

Rules should evolve with your codebase. Review and update periodically.

## Troubleshooting

### "Rule not being applied"

1. Check file extension is `.mdc`
2. Verify glob patterns match your files
3. Restart Cursor
4. Check for syntax errors in frontmatter

### "Conflicting rules"

Project rules override global rules. Be intentional about what goes where.

### "Rules too verbose"

The AI reads entire rules. Keep them concise but complete.

## Related Resources

- [Cursor Setup](https://vibecoding-navy.vercel.app/tools/ides/cursor/index.md) - Full Cursor configuration
- [agents-environment-config](https://vibecoding-navy.vercel.app/resources/agents-environment-config/index.md) - Pre-built rules
- [Config Directories](https://vibecoding-navy.vercel.app/tools/config-directories/index.md) - Where configs live```
````
# Community

# Contributing to Vibecoding

We welcome contributions from everyone in the vibecoding community! This guide will help you get started.

## Ways to Contribute

### Documentation

The most impactful way to contribute is by improving our docs:

- **Fix typos and errors** - Even small corrections help!
- **Add examples** - Share prompts and patterns that work for you
- **Improve clarity** - Help make complex topics more accessible
- **Translate content** - Help make vibecoding accessible in more languages

### Share Your Knowledge

- **Write guides** - Share your expertise on specific topics
- **Add to the FAQ** - Contribute answers to common questions
- **Document tools** - Write about AI assistants we haven't covered

### Community Support

- **Answer questions** - Help others in discussions
- **Review pull requests** - Provide feedback on contributions
- **Report issues** - Let us know about problems or gaps

## Getting Started

### 1. Fork the Repository

```bash
# Fork via GitHub UI, then clone your fork
git clone https://github.com/YOUR-USERNAME/vibecoding.git
cd vibecoding
```

### 2. Set Up the Environment

```bash
# Create a virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
```

### 3. Run Locally

```bash
# Start the development server
mkdocs serve
```

Open http://localhost:8000 to see your changes live.

### 4. Make Your Changes

- Edit files in the `docs/` directory
- Add new pages by creating `.md` files
- Update `mkdocs.yml` to add new pages to navigation

### 5. Submit a Pull Request

```bash
# Create a branch for your changes
git checkout -b add-prompting-example

# Make your changes, then commit
git add .
git commit -m "docs: add example for debugging prompts"

# Push to your fork
git push origin add-prompting-example
```

Then open a Pull Request on GitHub.

## Writing Guidelines

### Style

- **Be concise** - Get to the point quickly
- **Use examples** - Show, don't just tell
- **Be inclusive** - Write for all skill levels
- **Stay practical** - Focus on actionable advice

### Formatting

Use MkDocs Material features for better readability:

````markdown
!!! tip "Pro Tip"

    Use admonitions to highlight important information.

=== "Python"

    ```python
    print("Use tabs for language-specific examples")
    ```

=== "JavaScript"

    ```javascript
    console.log("Like this!");
    ```
````

### Code Examples

- Include language identifiers in code blocks
- Make examples runnable when possible
- Use realistic, practical scenarios

## What We're Looking For

### High Priority

- [ ] More prompting examples and patterns
- [ ] Guides for specific programming languages
- [ ] Troubleshooting common issues
- [ ] Real-world case studies

### Always Welcome

- Typo fixes and clarity improvements
- Additional FAQ entries
- Tool comparisons and reviews
- Tips from your vibecoding experience

## Code of Conduct

All contributors must follow our [Code of Conduct](https://vibecoding-navy.vercel.app/community/code-of-conduct/index.md). We're committed to maintaining a welcoming, inclusive community.

## Questions?

- Open a [Discussion](https://github.com/letsvibe/vibecoding/discussions) for questions
- Open an [Issue](https://github.com/letsvibe/vibecoding/issues) for bugs or suggestions
- Tag maintainers if you need help with your PR

Thank you for contributing to the vibecoding community!

# Code of Conduct

## Our Pledge

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

## Our Standards

### Positive Behaviors

Examples of behavior that contributes to a positive environment:

- **Being welcoming** - Use inclusive language and be friendly to newcomers
- **Being respectful** - Respect differing viewpoints and experiences
- **Being constructive** - Give and gracefully accept constructive feedback
- **Being collaborative** - Focus on what is best for the community
- **Being empathetic** - Show kindness and understanding to others

### Unacceptable Behaviors

Examples of unacceptable behavior:

- Trolling, insulting or derogatory comments, and personal or political attacks
- Public or private harassment
- Publishing others' private information without explicit permission
- The use of sexualized language or imagery, and unwelcome sexual attention
- Other conduct which could reasonably be considered inappropriate in a professional setting

## Enforcement

### Reporting

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at [INSERT CONTACT METHOD].

All complaints will be reviewed and investigated promptly and fairly.

All community leaders are obligated to respect the privacy and security of the reporter of any incident.

### Consequences

Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:

#### 1. Correction

**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.

**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate.

#### 2. Warning

**Community Impact**: A violation through a single incident or series of actions.

**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved for a specified period of time.

#### 3. Temporary Ban

**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.

**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time.

#### 4. Permanent Ban

**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.

**Consequence**: A permanent ban from any sort of public interaction within the community.

## Scope

This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces.

## Attribution

This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1, available at <https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.

Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
# FAQ

# Frequently Asked Questions

Common questions about vibecoding and this community resource.

## General Questions

### What is vibecoding?

Vibecoding is a development approach that embraces AI-assisted coding as a conversational, collaborative practice. Instead of writing code line-by-line, you describe what you want to build and iterate with AI to create solutions. See [What is Vibecoding?](https://vibecoding-navy.vercel.app/getting-started/what-is-vibecoding/index.md) for more details.

### Is vibecoding just for beginners?

No! Developers at all levels benefit from vibecoding:

- **Beginners** - Learn patterns and best practices while building
- **Intermediate** - Accelerate development and learn new technologies
- **Senior** - Focus on architecture while delegating implementation details
- **All levels** - Reduce time on boilerplate and research

### Will AI replace developers?

No. AI coding assistants are tools that augment human developers, not replace them. You still need to:

- Understand the problem you're solving
- Make architectural decisions
- Review and validate generated code
- Consider security and performance
- Maintain and evolve the codebase

### Is it cheating to use AI for coding?

No more than using Stack Overflow, documentation, or autocomplete. The key is to:

- Understand the code you're using
- Review it thoroughly before shipping
- Continue learning the fundamentals
- Use AI to accelerate, not bypass, learning

## Using AI Assistants

### Which AI assistant should I use?

It depends on your needs:

- **For inline completions**: GitHub Copilot or Cursor
- **For complex reasoning**: Claude
- **For an AI-native editor**: Cursor
- **For quick questions**: ChatGPT

See [AI Coding Assistants](https://vibecoding-navy.vercel.app/guides/ai-coding-assistants/index.md) for detailed comparisons.

### How do I get better results from AI?

1. Be specific about what you want
1. Provide relevant context
1. Show examples when possible
1. Iterate with follow-up prompts
1. Break large tasks into smaller pieces

See [Prompting Strategies](https://vibecoding-navy.vercel.app/guides/prompting-strategies/index.md) for detailed guidance.

### Can I trust AI-generated code?

Treat it like code from an unfamiliar source - review it carefully. Always:

- Understand what the code does
- Test with various inputs
- Check for security vulnerabilities
- Verify it follows your project conventions

### What should I NOT share with AI assistants?

Never include in prompts:

- API keys and secrets
- Production credentials
- Customer data or PII
- Proprietary algorithms you want to protect

## This Documentation

### How do I contribute?

See our [Contributing Guide](https://vibecoding-navy.vercel.app/community/contributing/index.md) for detailed instructions. In short:

1. Fork the repository
1. Make your changes
1. Submit a pull request

### Can I use this content elsewhere?

This project is open source - check the LICENSE file in the repository for specific terms.

### I found an error - how do I report it?

Options:

1. [Open an issue](https://github.com/letsvibe/vibecoding/issues) on GitHub
1. Submit a pull request with the fix
1. Start a [discussion](https://github.com/letsvibe/vibecoding/discussions)

### How do I run this documentation locally?

```bash
# Clone the repository
git clone https://github.com/letsvibe/vibecoding.git
cd vibecoding

# Set up Python environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run locally
mkdocs serve
```

Then open http://localhost:8000 in your browser.

## Community

### How can I connect with other vibecoders?

- Join [GitHub Discussions](https://github.com/mbernier/vibecoding/discussions)
- Contribute to this documentation

### I have a question not covered here

Feel free to:

1. [Open a discussion](https://github.com/mbernier/vibecoding/discussions) for general questions
1. [Open an issue](https://github.com/mbernier/vibecoding/issues) for documentation improvements
1. Contribute a new FAQ entry via pull request

______________________________________________________________________

Don't see your question? [Ask in Discussions](https://github.com/letsvibe/vibecoding/discussions) and we may add it here!