Загрузка...

Архитектура AI-инструкций в проекте (AGENTS.md + Rules + Skills)

AI
AI 3 минуты 233

Главная идея

Нужно разделить инструкции на 3 уровня:

Level 1 — Global rules
Level 2 — Task workflows (skills)
Level 3 — Deep documentation

Это называется progressive disclosure — агент получает только тот контекст, который нужен для текущей задачи.

Если засунуть всё в один AGENTS.md, агент будет:

  • игнорировать половину инструкций
  • путаться
  • жрать токены.

Правильная архитектура проекта

Рекомендуемая структура:

project/
│
├── AGENTS.md
├── CLAUDE.md
├── .agents/
│   ├── skills/
│   │   ├── commit/
│   │   │   └── SKILL.md
│   │   ├── build-test/
│   │   │   └── SKILL.md
│   │   ├── laravel-feature/
│   │   │   └── SKILL.md
│   │   └── review-checklist/
│   │       └── SKILL.md
│   │
│   ├── commands/
│   │   ├── create-pr.md
│   │   ├── refactor.md
│   │   └── debug.md
│   │
│   └── agents/
│       ├── coder.md
│       ├── reviewer.md
│       └── architect.md
│
├── docs/
│   └── agent-guides/
│       ├── project-architecture.md
│       ├── coding-standards.md
│       ├── testing.md
│       └── deployment.md
│
├── .claude/
│   └── skills -> ../.agents/skills
│
├── .opencode/
│   └── agents -> ../.agents/agents
│
├── .windsurf/
│   └── rules.md
│
└── .cursor/
    └── rules.md

1. AGENTS.md — главный файл проекта

Это точка входа для всех агентов.

Он должен быть:

  • короткий (50-120 строк)
  • без деталей
  • с ссылками на skills.

Причина:

AI-агенты стартуют без памяти о проекте, и именно этот файл даёт базовый контекст.

Пример хорошего AGENTS.md

# AI Agent Guide

This repository uses AI agents for development tasks.

## Project Overview

Laravel application using:

- Laravel 11
- Livewire 3
- Tailwind CSS
- PostgreSQL
- Docker

Architecture: Feature-first modules.

Full architecture:
docs/agent-guides/project-architecture.md

---

## Core Rules

Always follow:

- existing project patterns
- feature-first architecture
- Laravel conventions

Never:

- introduce new frameworks
- duplicate existing abstractions
- bypass tests

---

## Skills

Load skills when appropriate:

Build / test:
.agents/skills/build-test

Commits:
.agents/skills/commit

Feature development:
.agents/skills/laravel-feature

Code review:
.agents/skills/review-checklist

---

## Development Workflow

1. Implement feature
2. Run tests
3. Run linter
4. Self-review
5. Create PR

2. Rules — глобальные правила

Rules — это политика проекта.

Они должны отвечать на вопросы:

Как писать код
Как коммитить
Как запускать тесты
Как делать PR

Обычно их кладут:

docs/agent-guides/core-conventions.md

или

.rules/

Пример rules

# Coding Rules

## PHP

- Follow PSR-12
- Prefer readonly classes
- Avoid static helpers

## Laravel

- Use Service classes
- Avoid fat controllers
- Use FormRequest

## Database

- Use migrations
- Never edit schema manually

## Git

Commits must follow:

type(scope): message

Example:

feat(auth): add login throttling

3. Skills — ключевой механизм

Skills — это reusable workflow для агента.

Например:

create-commit
create-pr
run-tests
write-feature
fix-bug

Их можно использовать во многих агентах:

  • Claude
  • Cursor
  • Codex
  • Windsurf
  • Copilot
  • OpenCode

Структура skill

.agents/skills/git-commit/SKILL.md

Пример:

---
name: git-commit
description: Create commit following project conventions
---

# Git Commit Skill

Steps:

1. Analyze changed files
2. Group logical changes
3. Generate commit message

Format:

type(scope): message

Examples:

feat(auth): add login rate limiter
fix(api): correct pagination bug
refactor(user): simplify service layer

4. Commands — reusable prompts

Commands — это шорткаты для агента.

Примеры:

/create-feature
/refactor
/debug
/write-tests

Пример:

.agents/commands/create-feature.md
# Create Feature

Steps:

1. Analyze request
2. Create feature folder
3. Implement service
4. Add tests
5. Update routes

5. Agents — специализированные роли

Можно создавать несколько агентов:

coder
reviewer
architect

Пример:

.agents/agents/reviewer.md
# Code Reviewer Agent

Focus:

- bugs
- security
- performance

Ignore:

- minor style issues

Как совместить разные IDE

Каждая IDE использует свои файлы.

Нужно просто сделать прокси-файлы.

Claude

CLAUDE.md
See AGENTS.md

Cursor

.cursorrules
Refer to AGENTS.md

Windsurf

.windsurf/rules.md
Follow AGENTS.md

Copilot

.github/copilot-instructions.md
See AGENTS.md

OpenCode

OpenCode читает:

AGENTS.md
.agents/

Лучший трюк: единый AI-репозиторий

Сделай отдельный репозиторий с настройками AI:

~/ai-config
ai-config/
├── AGENTS.md
├── skills/
├── commands/
└── agents/

И в проектах делай symlink.

Это избавляет от копирования инструкций.

Как не запутаться (5 правил)

1. AGENTS.md < 120 строк

Это оглавление, а не документация.

2. Skills — только workflow

НЕ надо писать туда архитектуру.

3. Документация отдельно

docs/agent-guides

4. Один source of truth

AGENTS.md

Остальные файлы должны ссылаться на него.

5. Всё должно быть в git

Skills и rules — это часть инфраструктуры проекта.

Минимальный production-набор

Рекомендую минимум:

AGENTS.md

.agents/
   skills/
      build-test
      git-commit
      create-pr
      self-review
      feature-dev

docs/agent-guides/
   architecture
   conventions
   testing

Что реально улучшает работу AI

Из практики:

1️⃣ skill «build-test-verify»

агент всегда запускает тесты.

2️⃣ skill «self-review»

AI проверяет свой код.

3️⃣ skill «project-map»

помогает агенту понять архитектуру.

4️⃣ skill «commit»

генерирует нормальные коммиты.

Реальная проблема 2026

Большинство репозиториев делают так:

CLAUDE.md = 800 строк

И агент игнорирует половину файла.

Итоговая схема

AGENTS.md
   ↓

Skills
   ↓

Agent Guides
Global rules
   ↓

Task workflow
   ↓

Deep documentation

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *