agent-rules

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# React Native Expo AI Agent Rules

An opinionated set of AI coding guidelines and commands for React Native Expo projects. These rules help AI assistants (like Cursor, Claude, ChatGPT) generate consistent, high-quality code following best practices.

## Quick Start

### Automated Installation

Run this one-liner in your React Native Expo project root:

```bash
curl -fsSL https://raw.githubusercontent.com/dtsvetkov1/agent-rules/main/setup.sh | bash
```

Or download and run the script manually:

```bash
curl -fsSL https://raw.githubusercontent.com/dtsvetkov1/agent-rules/main/setup.sh -o setup.sh
chmod +x setup.sh
./setup.sh
```

### Manual Installation

If you prefer to install manually, just download the needed files from the repository and put them in your project

## What Gets Installed

After installation, your project will have:

```
your-project/
├── AGENTS.md                           # Main AI coding guidelines (https://agents.md/)
├── .cursor/
│   ├── rules/
│   │   └── react-native-expo-guidelines.mdc  # Cursor-specific rules
│   ├── commands/                       # Command templates for common workflows (https://cursor.com/docs/agent/chat/commands)
│   │   ├── code-review-checklist.md    # Review checklist
│   │   ├── ...
│   ├── hooks.json                      # Hook configuration
│   └── hooks/                          # Hook scripts that run automatically after certain actions (https://cursor.com/docs/agent/hooks)
│       ├── audit.sh                    # Audit agent actions
│       ├── ...
```

## What's Inside

### Core Guidelines (AGENTS.md)

Comprehensive guidelines covering:

- **Tech Stack**: Bun, TypeScript, Expo Router, Zustand, Reanimated
- **Project Structure**: Directory organization and naming conventions
- **Component Patterns**: Best practices for React Native components
- **State Management**: Zustand patterns and store organization
- **Animations**: React Native Reanimated guidelines
- **Performance**: Optimization techniques and best practices
- **Security**: Secure coding practices and data protection
- **Testing**: Unit, integration, and E2E testing strategies

### Quick Reference

#### Must-Use Technologies

- Bun (package manager)
- TypeScript (all files)
- Expo Router (navigation)
- Zustand (state management)
- React Native Reanimated (animations)
- expo/fetch (HTTP requests)
- Uniwind (styling)

### Command Templates

Pre-built workflows for common tasks:

- **setup-new-feature**: Systematic feature development
- **code-review-checklist**: Ensure code quality before PR
- **security-audit**: Security best practices validation
- **build-deploy**: Build and deployment workflows
- **run-tests-fix-failures**: Testing and debugging
- **code-quality**: Code quality analysis
- **update-documentation**: Documentation maintenance

### Cursor Hooks

AI agent lifecycle hooks for safety and quality:

- **format.sh**: Auto-formats edited files with Prettier/ESLint
- **audit.sh**: Logs all agent actions to `~/.cursor/audit/agent-audit.log`
- **block-dangerous-git.sh**: Prevents force pushes to main/master and other risky git operations
- **check-secrets.sh**: Scans prompts for API keys, tokens, and secrets before submission

Hooks run automatically and require a Cursor restart after installation. Check the Hooks tab in Cursor Settings to debug.

### Agent Skills

Agent skills are specialized instruction sets that provide the AI with deep knowledge and specific procedures for complex tasks. Think of them as "plugins" for your AI agent's brain that ensure expert-level handling of specific domains.

**How to apply them:**
Simply ask the agent to use a specific skill (e.g., "Use the mobile-perf skill to analyze this component") or let the agent autonomously select the relevant skill based on your task.

**Example skills included in `skills/`:**
- **api-expert**: Standards for API route implementation and data fetching
- **change-writer**: Structured format for generating changelogs and commit messages
- **mobile-perf**: React Native performance profiling and optimization techniques
- **navigation-architect**: Deep knowledge of Expo Router and navigation patterns
- **security-audit**: Comprehensive security checklist for mobile apps

#### Recommended Skills

We recommend enhancing your agent with these external skill sets:

- **React Native Skills**: [callstackincubator/agent-skills](https://github.com/callstackincubator/agent-skills) - Specialized skills for React Native development
- **React Skills**: [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills/) - Vercel's engineering best practices
- **Architecture Decision Records**: [ADR Skill](https://github.com/wshobson/agents/blob/main/plugins/documentation-generation/skills/architecture-decision-records/SKILL.md) - For documenting architectural choices
- **Agent Memory**: [Agent Memory](https://github.com/yamadashy/repomix/blob/main/.claude/skills/agent-memory/SKILL.md) - Techniques for maintaining long-term context

### Installation

You can install skills at the **Project Level** or **System Level** (bigger-picture rules).

#### 1. Project Level (Recommended)
This makes the skills available to everyone working on the project and ensures consistent behavior across the team.

-   **Location:** `.claude/skills/`, `.cursor/skills/` or `.opencode/skills/` 
-   **Purpose:** Skills specific to the project's tech stack (e.g., `api-expert`, `navigation-architect`) or shared team workflows.
-   **Setup:**
    ```bash
    mkdir skills
    # Copy specific skills
    cp -r path/to/agent-rules/skills/mobile-perf ./skills/
    ```

#### 2. System Level
Use this for generic skills you want to use across multiple projects without cluttering each repository.

-   **Location:** A central directory like `~/.cursor/skills/`,  `~/.claude/skills/` or  `~/.config/opencode/skills/` 
-   **Purpose:** Generic tools you use everywhere
-   **Setup:**
    1.  Create a central folder (if not exists)
    2.  Clone or copy skills there.

### Configuration by Tool

-   **Cursor**:
    -   **Project Level:** Cursor will index the `./skills/` folder automatically.
    -   **System Level:** Add the folder to your "Codebase" in settings or reference files using `@` (default  `~/.cursor/skills/`).
    -   **Tip:** Add a rule in `.cursor/rules` explicitly telling the agent: *"Always check `./skills/` for relevant capabilities before starting a task."*
-   **Claude Code**:
    -   **Project Level:** Ensure the `.claude/skills/` directory is included in your context.
    -   **System Level:** You must pass the skill file path argument when running Claude or add it to the context manually.
    -   **Config:** make sure `skills/` is **not** ignored.
-   **OpenCode**:
    -   **Project Level:** OpenCode agents automatically scan the project root for a `skills/` directory and parse `SKILL.md` files.
    -   **System Level:** Configuration depends on the specific OpenCode runtime environment.

## Usage

### With Cursor AI

1. Install the rules using the setup script
2. Open your project in Cursor
3. Start coding - the AI will automatically follow `react-native-expo-guidelines.mdc` rules (its configured to always apply, feel free to change it if needed)
4. Use command templates from `.cursor/commands/` for common workflows with `/` prefix, like `/run-tests-fix-failures` for running tests and fixing failures, or `/update-documentation` for updating documentation

### With Other AI Assistants

1. Share the `AGENTS.md` file with your AI assistant (Claude, ChatGPT, Cursor, etc.)
2. Reference specific sections when asking for code generation
3. Use the guidelines as a reference for code reviews (if needed)

## Customization

After installation, feel free to customize the rules for your specific project:

1. Edit `AGENTS.md` to match your project structure or specific needs
2. Update `.cursor/rules/` for Cursor-specific preferences
3. Modify command templates in `.cursor/commands/`
4. Commit changes to your repository if needed

---

Created for React Native Expo projects to ensure consistent, high-quality AI-assisted development.

## TODO/improvements

- dont duplicate agent md for cursor?
- less comments, start from small letter
- mcp servers config
- add option to download only certain files or directories
- add additional configs for claude code (subagents, hooks, output styles etc)

React Native Expo AI Agent Rules

An opinionated set of AI coding guidelines and commands for React Native Expo projects. These rules help AI assistants (like Cursor, Claude, ChatGPT) generate consistent, high-quality code following best practices.

Quick Start

Automated Installation

Run this one-liner in your React Native Expo project root:

curl -fsSL https://raw.githubusercontent.com/dtsvetkov1/agent-rules/main/setup.sh | bash

Or download and run the script manually:

curl -fsSL https://raw.githubusercontent.com/dtsvetkov1/agent-rules/main/setup.sh -o setup.sh
chmod +x setup.sh
./setup.sh

Manual Installation

If you prefer to install manually, just download the needed files from the repository and put them in your project

What Gets Installed

After installation, your project will have:

your-project/
├── AGENTS.md                           # Main AI coding guidelines (https://agents.md/)
├── .cursor/
│   ├── rules/
│   │   └── react-native-expo-guidelines.mdc  # Cursor-specific rules
│   ├── commands/                       # Command templates for common workflows (https://cursor.com/docs/agent/chat/commands)
│   │   ├── code-review-checklist.md    # Review checklist
│   │   ├── ...
│   ├── hooks.json                      # Hook configuration
│   └── hooks/                          # Hook scripts that run automatically after certain actions (https://cursor.com/docs/agent/hooks)
│       ├── audit.sh                    # Audit agent actions
│       ├── ...

What's Inside

Core Guidelines (AGENTS.md)

Comprehensive guidelines covering:

Tech Stack: Bun, TypeScript, Expo Router, Zustand, Reanimated
Project Structure: Directory organization and naming conventions
Component Patterns: Best practices for React Native components
State Management: Zustand patterns and store organization
Animations: React Native Reanimated guidelines
Performance: Optimization techniques and best practices
Security: Secure coding practices and data protection
Testing: Unit, integration, and E2E testing strategies

Quick Reference

Must-Use Technologies

Bun (package manager)
TypeScript (all files)
Expo Router (navigation)
Zustand (state management)
React Native Reanimated (animations)
expo/fetch (HTTP requests)
Uniwind (styling)

Command Templates

Pre-built workflows for common tasks:

setup-new-feature: Systematic feature development
code-review-checklist: Ensure code quality before PR
security-audit: Security best practices validation
build-deploy: Build and deployment workflows
run-tests-fix-failures: Testing and debugging
code-quality: Code quality analysis
update-documentation: Documentation maintenance

Cursor Hooks

AI agent lifecycle hooks for safety and quality:

format.sh: Auto-formats edited files with Prettier/ESLint
audit.sh: Logs all agent actions to ~/.cursor/audit/agent-audit.log
block-dangerous-git.sh: Prevents force pushes to main/master and other risky git operations
check-secrets.sh: Scans prompts for API keys, tokens, and secrets before submission

Hooks run automatically and require a Cursor restart after installation. Check the Hooks tab in Cursor Settings to debug.

Agent Skills

Agent skills are specialized instruction sets that provide the AI with deep knowledge and specific procedures for complex tasks. Think of them as "plugins" for your AI agent's brain that ensure expert-level handling of specific domains.

How to apply them: Simply ask the agent to use a specific skill (e.g., "Use the mobile-perf skill to analyze this component") or let the agent autonomously select the relevant skill based on your task.

Example skills included in skills/:

api-expert: Standards for API route implementation and data fetching
change-writer: Structured format for generating changelogs and commit messages
mobile-perf: React Native performance profiling and optimization techniques
navigation-architect: Deep knowledge of Expo Router and navigation patterns
security-audit: Comprehensive security checklist for mobile apps

Recommended Skills

We recommend enhancing your agent with these external skill sets:

React Native Skills: callstackincubator/agent-skills - Specialized skills for React Native development
React Skills: vercel-labs/agent-skills - Vercel's engineering best practices
Architecture Decision Records: ADR Skill - For documenting architectural choices
Agent Memory: Agent Memory - Techniques for maintaining long-term context

Installation

You can install skills at the Project Level or System Level (bigger-picture rules).

1. Project Level (Recommended)

This makes the skills available to everyone working on the project and ensures consistent behavior across the team.

Location: .claude/skills/, .cursor/skills/ or .opencode/skills/
Purpose: Skills specific to the project's tech stack (e.g., api-expert, navigation-architect) or shared team workflows.

Setup:

mkdir skills
# Copy specific skills
cp -r path/to/agent-rules/skills/mobile-perf ./skills/

2. System Level

Use this for generic skills you want to use across multiple projects without cluttering each repository.

Location: A central directory like ~/.cursor/skills/, ~/.claude/skills/ or ~/.config/opencode/skills/
Purpose: Generic tools you use everywhere
Setup:
1. Create a central folder (if not exists)
2. Clone or copy skills there.

Configuration by Tool

Cursor:
- Project Level: Cursor will index the ./skills/ folder automatically.
- System Level: Add the folder to your "Codebase" in settings or reference files using @ (default ~/.cursor/skills/).
- Tip: Add a rule in .cursor/rules explicitly telling the agent: "Always check ./skills/ for relevant capabilities before starting a task."
Claude Code:
- Project Level: Ensure the .claude/skills/ directory is included in your context.
- System Level: You must pass the skill file path argument when running Claude or add it to the context manually.
- Config: make sure skills/ is not ignored.
OpenCode:
- Project Level: OpenCode agents automatically scan the project root for a skills/ directory and parse SKILL.md files.
- System Level: Configuration depends on the specific OpenCode runtime environment.

Usage

With Cursor AI

Install the rules using the setup script
Open your project in Cursor
Start coding - the AI will automatically follow react-native-expo-guidelines.mdc rules (its configured to always apply, feel free to change it if needed)
Use command templates from .cursor/commands/ for common workflows with / prefix, like /run-tests-fix-failures for running tests and fixing failures, or /update-documentation for updating documentation

With Other AI Assistants

Share the AGENTS.md file with your AI assistant (Claude, ChatGPT, Cursor, etc.)
Reference specific sections when asking for code generation
Use the guidelines as a reference for code reviews (if needed)

Customization

After installation, feel free to customize the rules for your specific project:

Edit AGENTS.md to match your project structure or specific needs
Update .cursor/rules/ for Cursor-specific preferences
Modify command templates in .cursor/commands/
Commit changes to your repository if needed

Created for React Native Expo projects to ensure consistent, high-quality AI-assisted development.

TODO/improvements

dont duplicate agent md for cursor?
less comments, start from small letter
mcp servers config
add option to download only certain files or directories
add additional configs for claude code (subagents, hooks, output styles etc)