Rules & Workflows

Why Rules Matter

Without rules, the agent makes its best guess about how you want things done. With rules, it follows your exact preferences — every time.

Rules are defined in a GEMINI.md file at your project root. The agent reads this file at the start of every conversation.

Writing Effective Rules

Basic Structure

# GEMINI.md

## Project Overview

This is a Next.js 16 e-commerce app using TypeScript,
Tailwind CSS v4, and Cloudflare Workers.

## Code Style Rules

- Use functional components with TypeScript
- Prefer `const` over `let`
- Use early returns to reduce nesting
- All components must have explicit prop types

## Testing Rules

- Write tests for all new functions
- Use Vitest for unit tests
- Use Playwright for E2E tests

## Forbidden

- Never use `any` type
- Never use inline styles
- Never install packages without asking first

Advanced: Trigger-Based Rules

Rules can be conditional using frontmatter triggers:

---
trigger: always_on
---

# Always Active Rules

These rules apply to EVERY conversation.

---

## trigger: when_editing "\*.tsx"

# React-Specific Rules

Only active when editing React files.

Workflows: Reusable Task Recipes

Workflows are step-by-step instructions stored as .md files in .agent/workflows/. They’re triggered via slash commands.

Creating a Workflow

Create .agent/workflows/deploy.md:

---
description: Build and deploy to production
---

1. Run the linter
   // turbo
2. Run `pnpm build`
3. Check for build errors
   // turbo
4. Run `./deploy.sh`
5. Verify deployment URL returns 200

Now type /deploy in the agent chat to trigger it.

The // turbo Annotation

Lines marked with // turbo auto-execute without asking for approval. Use for safe, idempotent commands.

// turbo-all at the top makes every step auto-execute.

Real-World Workflow Examples

/add-blog-post — Create bilingual blog posts

---
description: Add a new blog post in both languages
---

1. Ask the user for: title, topic, key points
2. Create `src/content/blog/en/{slug}.md` with frontmatter
3. Create `src/content/blog/vi/{slug}.md` (translated)
4. Verify both files have matching structure
   // turbo
5. Run `pnpm build` to verify

/debug — Systematic debugging

---
description: Debug an issue systematically
---

1. Ask the user to describe the issue
2. Check terminal output for errors
3. Search codebase for related files
4. Identify the root cause
5. Propose a fix and ask for approval
6. Implement the fix
   // turbo
7. Run `pnpm dev` and verify

Combining Rules + Workflows

The real power comes from combining rules with workflows:

GEMINI.md (rules)
├── Sets coding standards
├── Defines project structure
└── Enforces patterns

.agent/workflows/ (actions)
├── /deploy → Automated deployment
├── /test → Run test suites
├── /add-feature → Feature scaffolding
└── /review → Code review checklist

Example flow:

1. You type /add-feature
2. Workflow asks for feature details
3. Agent checks GEMINI.md for coding standards
4. Generates code following YOUR patterns
5. Runs tests per YOUR testing rules
6. Deploys following YOUR deployment workflow

Best Practices

1. Start small — Add rules as you discover preferences
2. Be specific — “Use Tailwind v4” is better than “use modern CSS”
3. Include examples — Show the agent what you want
4. Update regularly — Rules should evolve with your project
5. Version control — Commit GEMINI.md and workflows to git

What’s Next

Rules tell the agent WHAT to do. Skills tell it HOW to do specific things with deep expertise. Let’s explore how Skills supercharge the agent.