AI Efficiency Handbooks

Do not rely on the ephemeral chat window for project state. Instead, offload memory to specific files that act as the project's "brain". Use these files to maintain context across sessions:

For maximum effectiveness, do not put all rules in one place. Use a layered approach to ensure the AI respects both personality and technical context.

Note: Avoid using the legacy .cursorrules file at the root, as it is often ignored or diluted compared to the modern .mdc system.

Understanding how Cursor injects rules is critical for troubleshooting why instructions are ignored or causing context issues:

1. Selective Injection: Rules are only added to the LLM's system prompt if the globs pattern matches the currently active file or if the rule has alwaysApply: true set in its frontmatter.
2. Context Dilution: Using overly broad patterns like globs: "**/*" can flood the context window. This causes weaker or longer rules to be truncated or pushed out of the model's immediate attention.
3. Hierarchy Priority:
   • Global Rules (Settings): Highest priority; treated as fundamental system instructions.
   • .mdc files: Project-specific context.
   • Legacy .cursorrules: Lowest priority.

Vibe coding is a high-velocity development approach that balances momentum with engineering discipline. It relies on three distinct modes of operation:

• Farmer Mode (The Setup): Prepare a 'Boring' stack (e.g., Next.js, Python/Node, Tailwind) that the AI has extensive training data for. This ensures the AI operates within predictable logical bounds.
• Chef Mode (The Flow): Provide high-level goals and let the AI propose implementation details. Avoid micromanaging implementation to allow the AI's 'native' solutions to shine.
• Review Mode (The Taste): Actively taste and adjust. If the AI suggests a bad pattern, fix it immediately to prevent technical debt from compounding.

Follow a Plan → Execute → Critique → Iterate state machine for complex features:

1. Planning (High-Energy/Human): Manually plan complex features, data models, and core logic. Ensure architecture is solid before coding.
2. Execution (Low-Energy/AI Agent): Switch to Agent Mode once the plan is set. The AI acts as a high-speed junior developer for implementation details.
3. The "Roast" Critique Loop: After the AI writes code, do not run it immediately. Use a self-review prompt to catch bugs.
   • Prompt: "Roast this code. Critique it for bugs, security holes, and readability like a senior engineer."

For optimal results, every prompt should contain these four elements:

1. Role: Define the persona (e.g., "Act as a Senior React Engineer").
2. Task: Define the specific action (e.g., "Create a reusable DatePicker component").
3. Constraints: Define the tech stack and rules (e.g., "Use Tailwind, TypeScript, and date-fns").
4. Format: Define the output style (e.g., "Output only the code file, no explanation").

Effective Cursor rule management relies on a layered architecture that separates Behavior from Knowledge:

1. Global Rules (Behavior Layer): Set in Cursor Settings. These define how the AI thinks and communicates (e.g., 'Think step-by-step', 'Never use placeholders'). They are injected into every request.
2. Project Rules (Knowledge Layer): Stored as .mdc files in .cursor/rules/. These define what the AI knows about your specific project (e.g., 'Use Next.js 14', 'Use PascalCase for components'). They are loaded selectively based on file context/globs to keep the context window clean.

By separating these, you avoid 'context dilution' where specific project knowledge gets buried by general instructions.

To prevent context loss and hallucinations, use a single persistent markdown file named project-memory.md. This acts as the AI's long-term memory.

File Structure

Include these sections in project-memory.md:

• Architecture: Core tech stack and folder duties.
• Patterns: Coding standards (e.g., "Use Server Actions", "Use strict Types").
• Decisions: Rationale for tech choices (e.g., "Why we chose Prisma over Drizzle").
• Lessons: Learned mistakes (e.g., "Never use any in API routes").
• Tech Debt: Known hacks to fix later.

Workflow Routine

• Start of Session: Reference the file and the task: @project-memory.md + Current Task: [Describe]. Follow patterns exactly.
• End of Session: Instruct the AI to update the file: Summarize today's progress, key decisions, and new lessons. Append to @project-memory.md.

When deciding where to place instructions, use the following hierarchy to ensure maximum compliance from the AI:

1. Global "Rules for AI" (Highest Reliability ⭐⭐⭐⭐⭐): Best for Personality & Thinking Style. Use this for high-level instructions like "Think step-by-step" or "Explain before code."
2. .cursor/rules/*.mdc (High Reliability ⭐⭐⭐⭐): Best for Knowledge & Context. Use these modular files for tech stacks, architecture patterns, naming conventions, and library-specific usage.
3. Legacy .cursorrules (Low Reliability ⭐⭐): Best for Legacy Root Config. This is still supported but is often deprioritized by the model compared to the modular .mdc system.

To prevent context rot and hallucinations, organize project knowledge into a hierarchy of specialized markdown files. This allows the AI to access high-level architecture and low-level implementation details without overloading the active context window.

• CLAUDE.md (The "Bible"): Repository-level configuration. Store build commands, test commands, and code style guidelines here.
• ARCHITECTURE.md (The Brain): A single-page source of truth for architectural patterns and major technical decisions.
• PROJECT_INTELLIGENCE.md: A living document to track technical debt, recent decisions, and evolving patterns. Reference this at the start of every session.
• thoughts/ Directory: A persistent directory for the AI to perform