Пам'ять проєкту для ШІ: Markdown-файли просто в репозиторії

Рано чи пізно кожен розробник, який працює з ШІ-асистентом, упирається в ту саму стіну. Просите зробити автентифікацію для застосунку на Next.js — відповідь добра. Потім кажете «а тепер під'єднай це до моєї наявної схеми користувачів», і він поводиться так, ніби вперше бачить проєкт. Він нічого не знає про:

• структуру ваших тек
• схему бази даних
• ваші стандарти коду
• ухвалені рішення щодо функцій
• навіщо існують ті чи інші файли
• чого ви свідомо уникали

І ви пояснюєте все наново, і ще раз. У якийсь момент стає зрозуміло: проблема не в моделі. Проблема в пам'яті.

Розв'язок дешевий: зберігати пам'ять проєкту в Markdown-файлах усередині репозиторію, щоб асистент починав кожну сесію, вже знаючи, як влаштовано проєкт. Це не прив'язано до Claude від Anthropic. Моделі OpenAI, Gemini і будь-який інший асистент для коду можуть читати ті самі файли.

Що таке пам'ять проєкту

Це постійний шар знань про кодову базу. Історія чату зникає, тому структуровані знання про проєкт ви зберігаєте в самому репозиторії:

• чим займається бізнес і навіщо
• як влаштована система
• які функції вийшли і коли
• як файли пов'язані між собою
• домовленості щодо коду
• логіку минулих рішень
• контракти API
• схеми баз даних

По суті репозиторій починає документувати сам себе у вигляді, який може прочитати ШІ. Це важливо: без контексту модель вгадує, а з контекстом стає значно кориснішою.

Навіщо це потрібно

Згадайте, що ви дали б новому сеньйору першого дня: документацію з архітектури, гайд із налаштування, структуру тек, документацію API, пояснення бізнес-логіки, роадмап, відомі проблеми, домовленості щодо коду. ШІ потрібне те саме, і засвоює він це миттєво.

Порівняйте промпти. Без пам'яті можна запитати тільки щось загальне на кшталт «поясни мій платіжний процес». З пам'яттю — «додай повторні спроби для вебхуків Razorpay, що впали, в межах нашої наявної подієвої архітектури». Один запит розмитий, інший точний.

Тека пам'яті

Покладіть приховану теку в корінь репозиторію, поруч із теками вихідного коду:

/project-root
 ├── src
 ├── components
 ├── services
 ├── .ai-memory

А всередині .ai-memory:

.ai-memory/
├── project-overview.md
├── architecture.md
├── folder-structure.md
├── database-schema.md
├── api-contracts.md
├── coding-guidelines.md
├── feature-history.md
├── active-tasks.md
├── known-issues.md
├── decision-log.md

Просто, читабельно і під контролем версій. Це мозок проєкту. Кожен файл має своє завдання.

project-overview.md

Найважливіший файл. У ньому сказано, що робить проєкт, хто ним користується, яку проблему він розв'язує і які в нього ключові функції. Наприклад:

# Project Overview

Project Name: DevResume AI
Purpose:
A SaaS platform where developers create digital resumes,
ATS-friendly resumes, and portfolio profiles.
Primary Users:
- Developers
- Students
- Recruiters
Core Features:
- Resume builder
- Portfolio generator
- Job tracker
- AI interview prep

Без нього ШІ бачить лише код. З ним він розуміє, навіщо цей код потрібен, і це змінює якість усіх його пропозицій.

architecture.md

Опишіть, як зібрано застосунок:

# Architecture

Frontend:
- Next.js 16
- React 19
- Tailwind CSS
Backend:
- Node.js
- Express
Database:
- PostgreSQL
Authentication:
- NextAuth
Storage:
- AWS S3
Deployment:
- Vercel

Так ШІ перестане пропонувати не той стек, і виправляти доведеться значно менше.

folder-structure.md

Поясніть зв'язки між файлами, з коротким коментарем до кожної теки:

src/
 ├── app/
 ├── modules/
 ├── shared/
 ├── services/
 ├── hooks/

/modules = feature-based architecture
/shared = reusable UI
/services = API integrations
/hooks = custom hooks

Тоді асистент знає, куди класти новий код, і файли перестають з'являтися будь-де.

database-schema.md

Цей файл на вагу золота:

User
- id
- name
- email
- role
Resume
- id
- userId
- templateId
- content
Portfolio
- id
- userId
- slug

Коли схема під рукою, ШІ точно пише запити, міграції, джойни й валідацію.

api-contracts.md

Задокументуйте свої API:

POST /api/auth/login
Request:
{
 email: string
 password: string
}

Response:
{
 token: string
 user: object
}

Нагорода — фронтенд-код, готовий до інтеграції, що спирається на реальні контракти, а не на здогадки.

feature-history.md

Відстежуйте, що вже вийшло:

# Feature History

v1.0
- Authentication
- Resume Builder
v1.1
- Portfolio Export
v1.2
- AI Resume Suggestions

Так ШІ не будуватиме наново те, що у вас уже є, — великий і недооцінений виграш.

decision-log.md

Записуйте, чому ухвалювалися рішення:

Decision:
Used PostgreSQL instead of MongoDB.

Reason:
Need relational joins for resume templates.

Тепер асистент не запропонує архітектуру, яку ви вже відкинули. Лише цей файл може зекономити години.

Пам'ять для кожної функції

Для більшої деталізації заведіть кожній функції власний файл пам'яті:

/features/auth/auth.memory.md
/features/payments/payments.memory.md
/features/profile/profile.memory.md

Типовий файл виглядає так:

# Auth Feature

Purpose:
Handles login/signup.
Flow:
Signup → Verify Email → Create Profile → Generate JWT
Files:
- auth.service.ts
- auth.controller.ts
- auth.routes.ts
Known edge cases:
- Duplicate emails
- Expired tokens

Це дає дуже локальний контекст, майже на рівні знань про компонент.

Промпти, які створюють і підтримують пам'ять

Щоб завести пам'ять для вже наявного проєкту, скористайтеся таким промптом:

Analyze my entire project and generate AI memory files.

Create:
1. project-overview.md
2. architecture.md
3. folder-structure.md
4. database-schema.md
5. api-contracts.md
6. feature-history.md
7. known-issues.md
8. coding-guidelines.md
9. decision-log.md
Rules:
- Read all folders
- Understand relationships
- Summarize clearly
- Keep markdown structured
- Mention business logic
- Mention important dependencies
- Mention reusable patterns

Для однієї функції за раз цей промпт створює її файл, і він добре масштабується:

Analyze this feature folder and create featureName.memory.md.

Include:
- Feature purpose
- Business logic
- File roles
- API dependencies
- Database dependencies
- Edge cases
- Future improvements
- Current limitations

Після того як нову роботу влито, запустіть промпт оновлення. Це критично, бо застаріла пам'ять небезпечна:

Update my AI memory files based on the new changes.

Check:
- New files
- Modified APIs
- Schema changes
- New feature flows
- New dependencies
- New business logic
Update only relevant markdown files.

Звички, які зберігають користь

• Пишіть стисло. Не пишіть романів: моделі краще працюють із ясним, коротким текстом.
• Версіонуйте в Git. Комітьте, рев'юйте й розвивайте пам'ять як код.
• Оновлюйте після кожної великої функції. Правило просте: функція вийшла — пам'ять оновлено. Без винятків.
• Використовуйте звичайний Markdown. Він універсальний, переносний і читається будь-де.

Не лише для Claude

Та сама схема працює з Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Google Gemini CLI і Windsurf. Працює вона не завдяки моделі. Завдяки пам'яті.

Суть

Багато розробників поводяться з ШІ як із чат-ботом. Колегам потрібен контекст, і простої теки .ai-memory досить, щоб повторювані промпти перетворилися на справжню співпрацю. Коли проєкт має пам'ять, асистент перестає поводитися як стажер і починає поводитися радше як архітектор. Найпевніше, за кілька років це стане звичайною інженерною практикою, тож почати варто вже зараз.