Память проекта для ИИ: 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 достаточно, чтобы повторяющиеся промпты превратились в настоящее сотрудничество. Когда у проекта есть память, ассистент перестаёт вести себя как стажёр и начинает вести себя скорее как архитектор. Скорее всего, через пару лет это станет обычной инженерной практикой, так что начать стоит уже сейчас.