# Использование промптов - Практические примеры

Практическое руководство по использованию промптов в diffray.

## 🔄 Как промпты загружаются и используются

### Автоматическое включение (output-format.md)

Промпт `output-format.md` автоматически добавляется ко всем агентам:

```typescript
// В executors/utils.ts
export async function loadOutputFormat(): Promise<string> {
  return getCached(CACHE_KEYS.OUTPUT_FORMAT, async () => {
    try {
      const formatPath = getDefaultPath('prompts', 'output-format.md');
      return await readFile(formatPath, 'utf-8');
    } catch {
      return DEFAULT_OUTPUT_FORMAT; // Fallback
    }
  });
}

// Использование в executors/cli.ts
const format = await loadOutputFormat();
const fullPrompt = buildPrompt(systemPrompt, ctx.input, format);
// Результат: systemPrompt + "\n\n# Input:\n" + input + "\n\n" + format
```

**Что происходит**:
1. `loadOutputFormat()` загружает `output-format.md`
2. `buildPrompt()` объединяет systemPrompt агента + input (диффы) + format
3. Итоговый промпт отправляется в LLM

---

## 📝 Использование специализированных промптов

### Вариант 1: Прямое включение в агента

Агент может включать содержимое промпта напрямую:

```markdown
---
name: i18n
description: Checks for internationalization issues
enabled: true
---

You are an internationalization specialist reviewing code for i18n issues.

**Focus Areas**:
- Hardcoded strings
- Missing translation keys
- Locale format issues
- RTL support

[Содержимое из prompts/i18n.md можно включить здесь]
```

### Вариант 2: Ссылка на промпт

Агент может ссылаться на промпт:

```markdown
---
name: database
description: Detects database issues
enabled: true
---

You are a database specialist.

See ../prompts/database.md for detailed review guidelines.

Focus on:
- N+1 queries
- Missing indexes
- Migration safety
```

### Вариант 3: Комбинирование промптов

Агент может комбинировать несколько промптов:

```markdown
---
name: full-stack-reviewer
description: Comprehensive code review
enabled: true
---

You are a full-stack code reviewer.

**Database Review**: See ../prompts/database.md
**API Design**: See ../prompts/api-design.md
**Observability**: See ../prompts/observability.md

Review code for issues in all these areas.
```

---

## 🎯 Примеры использования

### Пример 1: Агент с автоматическим форматом

```typescript
// Агент: bug-hunter.md
// System prompt: "You are a bug detection specialist..."
// Input: Git diffs
// Format: Автоматически добавляется из output-format.md

// Итоговый промпт:
const finalPrompt = `
You are a bug detection specialist focused on identifying logic errors.

# Input:
File: src/utils.ts
+ function processData(data) {
+   return data.map(item => item.value);
+ }

# Output Format
Return your findings as a JSON array wrapped in <json>...</json> XML tags:
...
`;
```

### Пример 2: Агент валидации

```typescript
// Агент: validation.md
// Использует промпт validation.md напрямую
// Stage: validation (отдельный этап)

const validationPrompt = `
You are a strict code review validation agent.
Your task is to validate issues found by other agents...

[Содержимое из prompts/validation.md]
`;
```

### Пример 3: Специализированный агент

```typescript
// Агент: database.md
// System prompt включает фокус на базы данных
// Format: Автоматически добавляется

const databasePrompt = `
You are a database specialist reviewing code for SQL/ORM issues.

**Focus Areas**:
- N+1 query problems
- Missing indexes
- Migration issues
...

# Input:
[Git diffs с изменениями в database коде]

# Output Format
[Автоматически из output-format.md]
`;
```

---

## 🔧 Создание нового промпта и агента

### Шаг 1: Создать промпт

```bash
# Создать файл промпта
touch src/defaults/prompts/my-domain.md
```

```markdown
# My Domain Review Prompt

You are a specialist reviewing code for [domain] issues.

## Your Mission
Identify [specific problems] that will cause [impact].

## Focus Areas
- Area 1: Description
- Area 2: Description

## Quality Standards
- Only flag issues with actual impact
- Verify before reporting
- Be concise and actionable

## Instructions
- Provide specific examples
- Suggest concrete fixes
- Only report real problems
```

### Шаг 2: Создать агента

```bash
# Создать файл агента
touch src/defaults/agents/my-domain.md
```

```markdown
---
name: my-domain
description: Reviews code for [domain] issues
enabled: true
---

You are a [domain] specialist reviewing code.

**Focus Areas**:
- [Area 1]
- [Area 2]

[Можно включить содержимое из prompts/my-domain.md или ссылаться на него]
```

### Шаг 3: Обновить документацию

Обновите `README.md`, `INDEX.md`, и `SUMMARY.md` с информацией о новом промпте.

---

## 📊 Структура промпта

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

```markdown
# [Domain] Review Prompt

## Your Mission
[Четкое описание цели]

## Focus Areas
### 1. [Area 1]
- [Подпункты]

### 2. [Area 2]
- [Подпункты]

## Quality Standards
- [Критерии качества]

## Instructions
- [Инструкции по использованию]

## Examples of Issues to Report
✅ **Report**: [Пример проблемы]
❌ **Don't Report**: [Пример того, что не нужно флажить]
```

---

## 🚀 Best Practices

1. **Будьте конкретны**: Четкие инструкции дают лучшие результаты
2. **Приводите примеры**: Показывайте, что флажить, а что нет
3. **Фокус на impact**: Только реальные проблемы, не микро-оптимизации
4. **Обновляйте регулярно**: Улучшайте промпты на основе реального использования
5. **Документируйте**: Обновляйте README при создании новых промптов

---

## 🔗 Связанные файлы

- **Загрузка промптов**: `src/executors/utils.ts` → `loadOutputFormat()`
- **Использование**: `src/executors/cli.ts` → `buildPrompt()`
- **Агенты**: `src/defaults/agents/` - Агенты, использующие промпты
- **Документация**: `README.md`, `INDEX.md`, `SUMMARY.md`