Створення ефективних файлів CLAUDE.md

Розробка ПЗ з Claude Code

Dani Zysman

AI Curriculum Manager @ DataCamp

Найкращі практики CLAUDE.md

Почніть з /init, далі ітерації
- Додавайте контекст, коли Claude помиляється
- Фіксуйте зміни домовленостей
Мета: живий документ, що розвивається разом із проєктом

Поточний стан проєкту

music-analytics-api/
  app.py           # Точка входу застосунку
  routes.py        # Кінцеві точки API
  models.py        # Моделі Artist/Album
  analytics.py     # Функції статистики
  middleware.py    # Логування запитів
  config.py        # Налаштування сесії
  CLAUDE.md        # <- Файл пам'яті проєкту

Що додаємо в CLAUDE.md, а що ні

recraft: Що включати, а що ні в CLAUDE.md

Правило: якщо текст довший за стікер, йому тут не місце.

Ітерації над CLAUDE.md

> Add error handling to the /artists endpoint.

Готово. Додано обробку помилок для /artists (routes.py:9-19):
- Блок try-except навколо отримання та серіалізації
- Обробка AttributeError, якщо сховище даних не ініціалізоване
- Загальний обробник винятків, що повертає деталі помилки зі статусом 500

return jsonify({'error': f'Failed to retrieve artists: {str(e)}'}), 500

> Don't expose exception details to users, that's a security risk. Log internally 
and return a generic message.  Update CLAUDE.md.

Оновлено /artists: помилки логуються внутрішньо, 
користувачу повертається загальне повідомлення 500. У CLAUDE.md додано правило: 
ніколи не розкривати деталі винятків у відповідях.

Добре vs. роздуте CLAUDE.md

Надто роздуте (200+ рядків)

# Inventory API
This is an Inventory Management 
API built with Flask...

## Full Source Code
### routes.py
from flask import jsonify...
[entire file pasted]

### models.py
[entire file pasted]

## API Documentation
GET /items returns...

Добре (15 рядків)

# Inventory API
Flask REST API for inventory.

## Commands
- Run: flask run --port 5001
- Test: pytest tests/

## Conventions
- Use type hints
- Keep routes thin

Посилання на файли — використання @

> @routes.py what endpoints does this API have?

Кінцеві точки API (6 маршрутів GET)

Artists
- GET /artists              Усі артисти
- GET /artists/<id>         Артист за ID
- GET /artists/<id>/albums  Альбоми артиста
Albums
- GET /albums               Усі альбоми
- GET /stats/albums         Статистика популярності альбомів
- GET /stats/average-tracks Середня кількість треків на альбом

Усі кінцеві точки повертають JSON.

CLAUDE.md + @ разом

# CLAUDE.md - Music Analytics API
A Flask-based REST API for music data analytics, providing endpoints for artists,
albums, and statistics.
...


## Key Files
@routes.py - API endpoint definition
@models.py - Artist and Album data models with in-memory store
...

CLAUDE.md надає постійний контекст. Використовуйте @, щоб Claude завжди знав про ключові файли.

Три рівні контексту

Три рівні контексту CLAUDE.md

Коли що використовувати

CLAUDE.md (проєкт, спільний)
- Команди для тестів, кодові домовленості, структура проєкту
CLAUDE.local.md (проєкт, особистий)
- Локальні шляхи, ключі API, особисті вподобання у роботі
~/.claude/CLAUDE.md (глобальний, особистий)
- Стильові вподобання для всіх проєктів
- Типові поведінки, які ви завжди хочете

Підсумок розділу 1

/init та CLAUDE.md → постійний контекст проєкту
Shift+Tab або /plan → перемикання режиму Plan
think ... ultrathink → глибоке міркування (5 рівнів)

Давайте потренуємось!

Розробка ПЗ з Claude Code