Что такое WORKSPACE.md
WORKSPACE.md — третий конфигурационный файл OpenClaw, дополняющий AGENTS.md и SOUL.md. Если AGENTS.md описывает «что делать», а SOUL.md — «как общаться», то WORKSPACE.md отвечает на вопрос «где мы находимся и как устроен проект».
Без WORKSPACE.md агент при каждой сессии вынужден самостоятельно изучать структуру проекта: читать файлы, исследовать директории, задавать уточняющие вопросы. Это тратит контекст, время и токены.
С WORKSPACE.md агент сразу знает:
- Где находятся ключевые файлы
- Какие команды используются для запуска, тестов, деплоя
- Какие соглашения приняты в проекте
- С кем и как взаимодействует система
Чем WORKSPACE.md отличается от AGENTS.md
| AGENTS.md | WORKSPACE.md | |
|---|---|---|
| Отвечает на | Что делать и как себя вести | Где что находится |
| Содержимое | Роли, правила, ограничения | Структура, команды, соглашения |
| Меняется | Редко | При изменении структуры проекта |
| Переносимость | Можно использовать в разных проектах | Специфичен для конкретного проекта |
AGENTS.md универсален — один файл для всех задач одного человека. WORKSPACE.md уникален для каждого проекта.
Базовая структура
# [Название проекта]
## Обзор проекта
[Одним абзацем: что это за проект, технологический стек, текущий статус]
## Структура директорий
[Дерево папок с кратким описанием каждой]
## Ключевые файлы
[Файлы, которые агент должен знать в первую очередь]
## Команды
[Как запускать, тестировать, деплоить]
## Соглашения
[Принятые в проекте стандарты: именование, форматирование, процессы]
## Внешние зависимости
[API, базы данных, сервисы с которыми работает проект]Примеры WORKSPACE.md
Для веб-приложения (React + Node.js)
# Проект: CRM-система для агентства
## Обзор
Внутренняя CRM для управления клиентами агентства недвижимости.
Стек: React 18 + TypeScript (фронт), Fastify + PostgreSQL (бэк).
Монорепо. Статус: production, ~200 активных пользователей.
## Структура директорий
apps/
web/ — React-приложение (порт 5173 в dev)
api/ — Fastify API (порт 3000 в dev)
packages/
shared/ — общие типы TypeScript
ui/ — UI-компоненты (Storybook: порт 6006)
utils/ — вспомогательные функции
## Ключевые файлы
- apps/api/src/routes/ — все API-эндпоинты
- apps/api/src/db/schema.ts — схема базы данных (Drizzle ORM)
- apps/web/src/pages/ — страницы приложения
- apps/web/src/store/ — глобальное состояние (Zustand)
- .env.example — список всех переменных окружения
- docker-compose.yml — локальная инфраструктура (PostgreSQL, Redis)
## Команды
# Запуск
pnpm dev — запустить всё (web + api)
pnpm dev:web — только фронт
pnpm dev:api — только бэк
docker-compose up -d — поднять инфраструктуру
# Тесты
pnpm test — все тесты
pnpm test:web — только фронт (Vitest)
pnpm test:api — только бэк (тоже Vitest)
pnpm test:e2e — end-to-end (Playwright)
# Сборка и деплой
pnpm build — собрать все пакеты
pnpm deploy:staging — деплой на staging
pnpm deploy:prod — деплой на production (требует подтверждения)
## Соглашения
- Коммиты: Conventional Commits (feat:, fix:, refactor:, docs:)
- Ветки: feature/*, fix/*, hotfix/*; merge в main через PR
- Компоненты: PascalCase, один компонент = один файл
- API: RESTful, v1 в пути (/api/v1/...)
- Ошибки API: { error: string, code: string, details?: object }
- TypeScript: строгий режим, no-any правило
## Внешние зависимости
- PostgreSQL 15 (локально через Docker, прод: Supabase)
- Redis (кеш и сессии)
- SendGrid (email: API_KEY в .env)
- Яндекс.Карты API (геокодирование)
- Telegram Bot API (уведомления для команды)
## Что не трогать без согласования
- apps/api/src/db/migrations/ — только через CLI (pnpm db:migrate)
- .env файлы — не коммитить, редактировать только локальные копии
- apps/web/public/ — статические ассеты, изменения через дизайнераДля контент-проекта (Astro + Markdown)
# Проект: infoclaw.ru
## Обзор
Информационный сайт об OpenClaw на русском языке.
Astro + Markdown контент. Деплой через GitHub Actions на Beget.
Текущий объём: 83 статьи в 13 категориях.
## Структура директорий
src/
content/articles/ — все статьи сайта (Markdown)
bezopasnost/ — категория "Безопасность"
chto-takoe-openclaw/ — категория "Что такое OpenClaw"
ustanovka/ — категория "Установка"
navyki/ — категория "Навыки"
[и др. категории]
components/ — Astro компоненты
layouts/ — шаблоны страниц
pages/ — роутинг сайта
public/
og/ — OG-изображения (генерируются автоматически)
favicon.svg — логотип
scripts/
generate-og-images.mjs — генерация OG через fal.ai
docs/
semantic-cocoon-plan.md — контент-стратегия
## Ключевые файлы
- src/content/config.ts — схема frontmatter (обязательные поля)
- src/content.config.ts — то же (Astro v5 формат)
- .github/workflows/deploy.yml — CI/CD pipeline
- astro.config.mjs — конфигурация сайта
## Команды
npm run dev — локальный сервер (порт 4321)
npm run build — сборка статики в dist/
npm run preview — предпросмотр сборки
git push — автоматически запускает деплой через GitHub Actions
## Frontmatter статьи (обязательные поля)
---
title: "Заголовок"
description: "150-160 символов"
category: [категория из списка]
pubDate: 2026-03-23
tags: ["тег1", "тег2"]
schemaType: Article | HowTo | FAQPage
relatedSlugs: ["slug1", "slug2"] # минимум 3
---
## Соглашения
- Статьи: 1200-2000 слов, slug на транслите
- Категории: строго из списка в config.ts
- После создания статьи: git add → git commit → git push
- OG-изображения: создаются автоматически в CI/CD
- Не создавать файлы вне src/content/articles/Для Python-проекта / Data Science
# Проект: Анализ продаж
## Обзор
Аналитический пайплайн для обработки данных продаж интернет-магазина.
Python 3.11, Pandas, SQLAlchemy, Airflow. Данные: PostgreSQL + S3.
## Структура директорий
data/
raw/ — сырые данные (не коммитятся, .gitignore)
processed/ — обработанные данные
exports/ — готовые экспорты для отчётов
src/
etl/ — скрипты ETL
models/ — модели данных и трансформации
reports/ — генерация отчётов
utils/ — вспомогательные функции
notebooks/ — Jupyter notebooks для исследований
tests/ — тесты (pytest)
## Команды
python -m pytest — запустить тесты
python src/etl/run.py --daily — запустить дневной ETL
python src/reports/weekly.py — сгенерировать недельный отчёт
jupyter notebook — запустить Jupyter
## Соглашения
- Данные: никогда не коммитить в git, хранить в S3/локально
- Функции: docstring обязательны для публичных функций
- Импорты: абсолютные пути от корня проекта
- Конфиг: все константы в src/config.py
## Переменные окружения
DB_URL — строка подключения к PostgreSQL
AWS_BUCKET — S3 bucket для данных
SLACK_WEBHOOK — для уведомленийСоветы по написанию эффективного WORKSPACE.md
Пишите для агента, а не для человека. Команда уже знает структуру проекта. WORKSPACE.md нужен агенту чтобы не тратить токены на исследование. Будьте конкретны: полные пути, точные команды.
Указывайте «почему», а не только «что». «Не коммитить data/raw/ — там персональные данные клиентов» лучше, чем просто «не коммитить data/raw/».
Обновляйте при изменениях. Устаревший WORKSPACE.md хуже его отсутствия — агент будет следовать неверным инструкциям. Добавьте обновление файла в checklist при рефакторинге структуры проекта.
Не дублируйте README.md. Если в проекте есть README, в WORKSPACE.md достаточно сослаться на него для деталей: «Полная документация: README.md, раздел “Architecture”».
Размер имеет значение. WORKSPACE.md загружается в каждый запрос. Файл на 500 строк — это ~7 000 токенов постоянной нагрузки. Держите в пределах 150-200 строк.
WORKSPACE.md работает в связке с AGENTS.md и SOUL.md — подробнее о полной системе конфигурации: AGENTS.md и SOUL.md. Если файлы конфигурации разрастаются — читайте о context overflow.