Skip to content

Commit bfcf059

Browse files
valkirilovvalkirilov
committed
docs: add AGENTS.md for AI agent instructions and project overview
- Introduce AGENTS.md as a comprehensive guide for AI coding agents working on RedisInsight. - Include project overview, setup commands, testing instructions, and development standards. - Outline boundaries for development practices, emphasizing code quality and testing protocols. - Update .ai/README.md and GitHub Copilot instructions to reference AGENTS.md for essential commands and guidelines.
1 parent c6aa4ec commit bfcf059

File tree

3 files changed

+199
-69
lines changed

3 files changed

+199
-69
lines changed

‎.ai/README.md‎

Lines changed: 67 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,74 @@
11
# RedisInsight AI Development Rules
22

3-
This directory contains the **single source of truth** for AI-assisted development rules and workflows in RedisInsight. These rules are used by multiple AI coding assistants:
3+
This directory contains the **single source of truth** for AI-assisted development rules and workflows in RedisInsight.
4+
5+
## Overview
6+
7+
This repository uses a centralized approach to AI development rules:
8+
9+
- **`AGENTS.md`** (at repository root) - Entry point for AI agents with essential commands, testing instructions, and quick reference
10+
- **`.ai/rules/`** - Detailed development standards organized by topic
11+
- **`.ai/commands/`** - AI workflow commands and templates
12+
13+
These rules are used by multiple AI coding assistants:
414

515
- **Cursor** (via symlinks: `.cursor/rules/` and `.cursor/commands/`)
616
- **Augment** (via symlink: `.augment/`)
717
- **Windsurf** (via symlink: `.windsurfrules`)
818
- **GitHub Copilot** (via file: `.github/copilot-instructions.md`)
919

20+
## Structure
21+
22+
```
23+
AGENTS.md # 🎯 AI agent entry point
24+
.ai/ # Single source of truth
25+
├── README.md # This file (human-readable overview)
26+
├── rules/ # Development standards (modular)
27+
│ ├── code-quality.md # Linting, TypeScript standards
28+
│ ├── frontend.md # React, Redux, UI patterns
29+
│ ├── backend.md # NestJS, API patterns
30+
│ ├── testing.md # Testing standards
31+
│ ├── branches.md # Branch naming conventions
32+
│ ├── commits.md # Commit message guidelines
33+
│ └── pull-requests.md # Pull request process
34+
└── commands/ # AI workflow commands
35+
├── pr-plan.md # JIRA ticket implementation planning
36+
├── commit-message.md # Commit message generation
37+
└── pull-request-review.md # PR review workflow
38+
39+
# Symlinks (all AI tools read from .ai/)
40+
.cursor/
41+
├── rules/ -> ../.ai/rules/ # Cursor AI (rules)
42+
└── commands/ -> ../.ai/commands/ # Cursor AI (commands)
43+
.augment/ -> .ai/ # Augment AI
44+
.windsurfrules -> .ai/ # Windsurf AI
45+
.github/copilot-instructions.md # GitHub Copilot
46+
```
47+
48+
## For AI Agents
49+
50+
**Start here**: Read `AGENTS.md` at the repository root for:
51+
52+
- Setup and build commands
53+
- Code quality standards
54+
- Testing instructions
55+
- Git workflow guidelines
56+
- Boundaries and best practices
57+
58+
**Then refer to**: `.ai/rules/` for detailed guidelines on specific topics.
59+
60+
## For Human Developers
61+
62+
This directory contains comprehensive development standards that are automatically used by AI coding assistants. The rules are organized into modular files for easy maintenance:
63+
64+
- **Code Quality Standards**: `.ai/rules/code-quality.md` - TypeScript standards, import organization, best practices
65+
- **Frontend Patterns**: `.ai/rules/frontend.md` - React, Redux, styled-components, UI component usage
66+
- **Backend Patterns**: `.ai/rules/backend.md` - NestJS, dependency injection, API patterns
67+
- **Testing Standards**: `.ai/rules/testing.md` - Testing patterns, faker usage, test helpers
68+
- **Branch Naming**: `.ai/rules/branches.md` - Branch naming conventions
69+
- **Commit Messages**: `.ai/rules/commits.md` - Commit message guidelines (Conventional Commits)
70+
- **Pull Request Process**: `.ai/rules/pull-requests.md` - PR creation and review guidelines
71+
1072
## MCP (Model Context Protocol) Setup
1173

1274
AI tools can access external services (JIRA, Confluence, GitHub) via MCP configuration.
@@ -25,7 +87,7 @@ AI tools can access external services (JIRA, Confluence, GitHub) via MCP configu
2587
- Create a classic token by pressing the first "Create Token" button
2688
- Copy the token
2789

28-
3. **Edit `.env.mcp` with your credentials:**
90+
3. **Edit `.env.mcp` with your credentials**
2991

3092
4. **Verify your setup:**
3193

@@ -56,69 +118,13 @@ The `mcp.json` file configures these services:
56118
- **context-7** - Advanced context management
57119
- **atlassian** - JIRA (RI-XXX tickets) and Confluence integration
58120

59-
## Structure
60-
61-
```
62-
.ai/ # 🎯 Single source of truth
63-
├── README.md # Overview & quick reference
64-
├── rules/ # Development standards (modular)
65-
│ ├── code-quality.md # Linting, TypeScript standards
66-
│ ├── frontend.md # React, Redux, UI patterns
67-
│ ├── backend.md # NestJS, API patterns
68-
│ ├── testing.md # Testing standards
69-
│ ├── branches.md # Branch naming conventions
70-
│ ├── commits.md # Commit message guidelines
71-
│ └── pull-requests.md # Pull request process
72-
└── commands/ # AI workflow commands
73-
├── commit-message.md # Commit message generation
74-
└── pull-request-review.md # PR review workflow
75-
76-
# Symlinks (all AI tools read from .ai/)
77-
.cursor/
78-
├── rules/ -> ../.ai/rules/ # Cursor AI (rules)
79-
└── commands/ -> ../.ai/commands/ # Cursor AI (commands)
80-
.augment/ -> .ai/ # Augment AI
81-
.windsurfrules -> .ai/ # Windsurf AI
82-
.github/copilot-instructions.md # GitHub Copilot
83-
```
84-
85-
## Project Overview
86-
87-
**RedisInsight** is a desktop application for Redis database management built with:
88-
89-
- **Frontend**: React 18, TypeScript, Redux Toolkit, Elastic UI, Monaco Editor, Vite
90-
- **Backend**: NestJS, TypeScript, Node.js
91-
- **Desktop**: Electron for cross-platform distribution
92-
- **Testing**: Jest, Testing Library, Playwright
93-
94-
**Architecture**:
95-
96-
```
97-
redisinsight/
98-
├── ui/ # React frontend (Vite + TypeScript)
99-
├── api/ # NestJS backend (TypeScript)
100-
├── desktop/ # Electron main process
101-
└── tests/ # E2E tests (Playwright)
102-
```
103-
104-
## Detailed Guidelines
105-
106-
All detailed development standards, coding practices, and workflows are maintained in modular files:
107-
108-
- **Code Quality Standards**: See `.ai/rules/code-quality.md`
109-
- **Frontend Patterns**: See `.ai/rules/frontend.md`
110-
- **Backend Patterns**: See `.ai/rules/backend.md`
111-
- **Testing Standards**: See `.ai/rules/testing.md`
112-
- **Branch Naming**: See `.ai/rules/branches.md`
113-
- **Commit Messages**: See `.ai/rules/commits.md`
114-
- **Pull Request Process**: See `.ai/rules/pull-requests.md`
115-
116121
## Updating These Rules
117122

118123
To update AI rules:
119124

120125
1. **Edit files in `.ai/` only** (never edit symlinked files directly)
121-
2. Changes automatically propagate to all AI tools
122-
3. Commit changes to version control
126+
2. **Update `AGENTS.md`** if you change commands, testing instructions, or boundaries
127+
3. Changes automatically propagate to all AI tools via symlinks
128+
4. Commit changes to version control
123129

124130
**Remember**: These rules exist to maintain code quality and consistency. Follow them, but also use good judgment.

‎.github/copilot-instructions.md‎

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,19 @@
11
# GitHub Copilot Instructions for RedisInsight
22

3-
> **📚 All development rules and guidelines are in the `.ai/` directory**
3+
> **🎯 Start here: Read `AGENTS.md` at the repository root for essential commands, testing instructions, and quick reference**
44
5-
This project uses a centralized AI rules structure. All detailed guidelines, standards, and workflows are maintained in the `.ai/` directory as the single source of truth.
5+
This project uses a centralized AI rules structure:
6+
7+
- **`AGENTS.md`** (repository root) - Entry point with commands, testing, and boundaries
8+
- **`.ai/rules/`** - Detailed development standards organized by topic
9+
- **`.ai/commands/`** - AI workflow commands and templates
610

711
## 📂 Rules Structure
812

913
### Core Development Rules
1014

1115
- **Code Quality**: `.ai/rules/code-quality.md`
1216

13-
- ESLint configuration (Airbnb base)
14-
- Prettier formatting standards
1517
- TypeScript best practices
1618
- Import organization
1719
- SonarJS complexity rules
@@ -56,8 +58,9 @@ This project uses a centralized AI rules structure. All detailed guidelines, sta
5658

5759
### Commands and Workflows
5860

59-
- **Commit Message Generation**: `.ai/commands/commit-message.md`
60-
- **PR Review**: `.ai/commands/pull-request-review.md`
61+
- **PR Plan**: `.ai/commands/pr-plan.md` - Analyze JIRA tickets (RI-XXX) and create detailed implementation plans
62+
- **Commit Message Generation**: `.ai/commands/commit-message.md` - Generate commit messages following Conventional Commits
63+
- **PR Review**: `.ai/commands/pull-request-review.md` - Review pull requests and provide feedback
6164

6265
## 🎯 Project Overview
6366

@@ -76,8 +79,9 @@ This project uses a centralized AI rules structure. All detailed guidelines, sta
7679

7780
## 📖 Additional Documentation
7881

79-
For a comprehensive introduction and quick reference, see: `.ai/README.md`
82+
- **For AI agents**: Start with `AGENTS.md` at repository root
83+
- **For human developers**: See `.ai/README.md` for setup and overview
8084

8185
---
8286

83-
**Note**: This is a minimal reference file. GitHub Copilot cannot read the referenced files directly, but developers can access the full guidelines in the `.ai/` directory. Other AI tools (Cursor, Augment, Windsurf) access these rules via symlinks.
87+
**Note**: This is a minimal reference file. GitHub Copilot cannot read the referenced files directly, but developers can access the full guidelines. Other AI tools (Cursor, Augment, Windsurf) access these rules via symlinks and can read `AGENTS.md` directly.

‎AGENTS.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# RedisInsight AI Agent Instructions
2+
3+
This file provides essential context and instructions for AI coding agents working on RedisInsight.
4+
5+
## Project Overview
6+
7+
**RedisInsight** is a desktop application for Redis database management built with:
8+
9+
- **Frontend**: React 18, TypeScript, Redux Toolkit, styled-components, Monaco Editor, Vite
10+
- **Backend**: NestJS, TypeScript, Node.js
11+
- **Desktop**: Electron for cross-platform distribution
12+
- **Testing**: Jest, Testing Library, Playwright
13+
14+
**Architecture**:
15+
16+
```
17+
redisinsight/
18+
├── ui/ # React frontend (Vite + TypeScript)
19+
├── api/ # NestJS backend (TypeScript)
20+
├── desktop/ # Electron main process
21+
└── tests/ # E2E tests (Playwright)
22+
```
23+
24+
## Setup Commands
25+
26+
### Development
27+
28+
```bash
29+
# Frontend development (web)
30+
yarn dev:ui
31+
32+
# Backend development
33+
yarn dev:api
34+
35+
# Desktop app development (runs all: API + UI + Electron)
36+
yarn dev:desktop
37+
38+
# Frontend with coverage
39+
yarn dev:ui:coverage
40+
```
41+
42+
## Testing Instructions
43+
44+
### Run Tests
45+
46+
```bash
47+
# Frontend tests
48+
yarn test # Run all UI tests
49+
50+
# Backend tests
51+
yarn test:api # Run all API tests
52+
53+
# E2E tests
54+
yarn --cwd tests/e2e test
55+
```
56+
57+
### Before Committing
58+
59+
**ALWAYS run these before committing:**
60+
61+
```bash
62+
# Lint check
63+
yarn lint # All code
64+
yarn lint:ui # Frontend only
65+
yarn lint:api # Backend only
66+
67+
# Type checking
68+
yarn type-check:ui # Frontend TypeScript
69+
70+
# Tests
71+
yarn test # Frontend tests
72+
yarn test:api # Backend tests
73+
```
74+
75+
**Fix any linting errors, type errors, or test failures before committing.**
76+
77+
All detailed development standards are maintained in `.ai/rules/`:
78+
79+
- **Code Quality**: `.ai/rules/code-quality.md` - Linting, TypeScript standards
80+
- **Frontend**: `.ai/rules/frontend.md` - React, Redux, UI patterns, styled-components
81+
- **Backend**: `.ai/rules/backend.md` - NestJS, API patterns, dependency injection
82+
- **Testing**: `.ai/rules/testing.md` - Testing standards, faker usage, test patterns
83+
- **Branches**: `.ai/rules/branches.md` - Branch naming conventions
84+
- **Commits**: `.ai/rules/commits.md` - Commit message guidelines
85+
- **Pull Requests**: `.ai/rules/pull-requests.md` - PR process and review guidelines
86+
87+
**Refer to these files for comprehensive guidelines on each topic.**
88+
89+
## Boundaries
90+
91+
### ✅ Always Do
92+
93+
- Write to `src/` and `tests/` directories
94+
- Run `yarn lint` and `yarn test` before commits
95+
- Follow naming conventions (camelCase, PascalCase, UPPER_SNAKE_CASE)
96+
- Use faker library for test data generation
97+
- Use `renderComponent` helper in component tests
98+
- Extract duplicate strings to constants
99+
- Use semantic colors from theme (not CSS variables)
100+
- Use layout components (Row/Col/FlexGroup) instead of div
101+
- Pass layout props as component props (not hardcoded in styles)
102+
103+
### ⚠️ Ask First
104+
105+
- Database schema changes
106+
- Adding new dependencies
107+
- Modifying CI/CD configuration (`.github/workflows/`)
108+
- Changes to build configuration
109+
- Breaking changes to APIs
110+
111+
### 🚫 Never Do
112+
113+
- Commit secrets or API keys
114+
- Edit `node_modules/` or `vendor/` directories
115+
- Use fixed time waits in tests (use `waitFor` instead)
116+
- Use `!important` in styled-components
117+
- Import directly from `@redis-ui/*` (use internal wrappers from `uiSrc/components/ui`)
118+
- Use Elastic UI for new code (migrating to Redis UI)
119+
- Use hardcoded pixel values (use theme spacing)
120+
- Use `any` type without reason

0 commit comments

Comments
 (0)