architect/standards/arh/project-creation-system.md

type: standard
aspect: guidance
title: "Система создания проектов"
version: 1.0.0
date: 2026-02-19
status: active


Система создания проектов

Версия: 1.0.0
Дата: 2026-02-14
Статус: Active


Концепция

Автоматизированная система создания новых проектов с:
- Единообразной структурой
- Автоматической валидацией
- Использованием переменных вместо хардкода
- Синхронизацией workspace ↔ dataspace

Проблема (до системы):
- Ручное создание проектов → ошибки, несоответствие стандартам
- Хардкод путей → сложность переноса
- Разная структура workspace и dataspace → потеря данных
- Нет валидации → нарушения стандартов

Решение:
- CLI скрипт для создания проектов
- Шаблоны с переменными
- Автоматическая валидация
- Единый источник правды (platform-vars.sh)


Принципы

1. Одинаковая иерархия

Workspace и dataspace ДОЛЖНЫ быть зеркальными:

$WORKSPACE/projects/org/{name}/    $DATASPACE/projects/org/{name}/
├── CLAUDE.md                      ├── prices/
├── PROJECT.md                     ├── images/
├── config/                        ├── exports/
└── services/                      └── _inbox/

Правило: $PROJECTS_NAMESPACE идентичен в обоих пространствах.

2. Переменные вместо хардкода

ЗАПРЕЩЕНО:

cd /opt/claude-workspace/projects/org/myproject
cp /mnt/beget-s3/projects/org/myproject/data.xlsx .

ПРАВИЛЬНО:

cd $(project_ws myproject)
cp $(project_data myproject)/data.xlsx .

Или:

source $WORKSPACE/system/config/platform-vars.sh
cd $WORKSPACE/$PROJECTS_NAMESPACE/myproject

3. Валидация при создании

Обязательные проверки:
- [ ] Имя проекта корректно (только a-z0-9-_)
- [ ] Проект не существует
- [ ] Workspace и dataspace доступны
- [ ] Переменные платформы загружены
- [ ] Git инициализирован в workspace
- [ ] NocoDB база создана (опционально)

4. Атомарность

Создание проекта = транзакция:
- Все шаги выполняются или откатываются целиком
- При ошибке — автоматическая очистка
- Лог всех действий для отладки


Компоненты системы

1. Переменные платформы

Файл: system/config/platform-vars.sh

# Базовые пространства
export WORKSPACE=/opt/claude-workspace
export DATASPACE=/mnt/beget-s3
export INFRA=/mnt/beget-infra

# Namespace проектов
export PROJECTS_NAMESPACE="projects/org"

# Функции
project_ws() { echo "$WORKSPACE/$PROJECTS_NAMESPACE/$1"; }
project_data() { echo "$DATASPACE/$PROJECTS_NAMESPACE/$1"; }
project_infra() { echo "$INFRA/$PROJECTS_NAMESPACE/$1"; }

Использование:

source $WORKSPACE/system/config/platform-vars.sh
PROJECT_WS=$(project_ws myproject)
PROJECT_DATA=$(project_data myproject)

2. Функции управления путями

Файл: system/config/project-paths.sh

Функции:
- project_ws NAME — путь в workspace
- project_data NAME — путь в dataspace
- project_infra NAME — путь в infra
- set_project NAME — экспорт переменных проекта
- validate_project NAME — проверка соответствия
- validate_all_projects — проверка всех проектов

См.: system/config/project-paths.sh

3. CLI скрипт создания

Файл: system/scripts/create-project.sh

Использование:

# Интерактивный режим
create-project

# Прямое создание
create-project myproject

# С параметрами
create-project myproject --type=commercial --nocodb

Процесс:
1. Валидация имени и параметров
2. Проверка что проект не существует
3. Создание структуры в workspace
4. Создание структуры в dataspace
5. Инициализация git
6. Создание базы NocoDB (опционально)
7. Валидация результата
8. Вывод отчёта

См.: Реализация

4. Шаблоны проектов

Папка: architect/templates/

Типы проектов:
- PROJECT_COMMERCIAL.md — коммерческий проект
- PROJECT_INTERNAL.md — внутренний инструмент
- PROJECT_RESEARCH.md — исследовательский проект
- PROJECT_PLATFORM.md — компонент платформы

Использование:

# Шаблон подставляется при создании
create-project myproject --template=commercial
# → использует templates/PROJECT_COMMERCIAL.md

5. Валидатор платформы

Файл: system/scripts/validate-platform.sh

Проверки:
- Соответствие workspace ↔ dataspace
- Наличие обязательных файлов (CLAUDE.md, index.yaml)
- Отсутствие хардкодов в проектах
- Отсутствие больших файлов в workspace (>10MB)
- Соответствие стандартам именования

Запуск:

# Ручная проверка
validate-platform

# Проверка конкретного проекта
validate-platform myproject

# Автоматическая проверка (через scheduler)
# Расписание: ежедневно 04:00

См.: Реализация


Процесс создания проекта

Шаг 1: Планирование

Определить:
- Имя проекта (только a-z0-9-_, без заглавных)
- Тип проекта (commercial/internal/research/platform)
- Нужна ли база данных NocoDB
- Нужна ли интеграция с внешними API

Документ: Заполнить бриф по шаблону templates/project-start/00_INTAKE.md

Шаг 2: Создание структуры

Автоматически (через CLI):

# Интерактивный режим
create-project

# Или прямое создание
create-project myproject --type=commercial --nocodb

Вручную (если нужен контроль):

source $WORKSPACE/system/config/platform-vars.sh

# Создать в workspace
mkdir -p $(project_ws myproject)
cd $(project_ws myproject)

# Создать базовые файлы из шаблонов
cp $WORKSPACE/architect/templates/PROJECT_COMMERCIAL.md PROJECT.md
cp $WORKSPACE/architect/templates/CLAUDE_TEMPLATE.md CLAUDE.md

# Создать в dataspace
mkdir -p $(project_data myproject)/{prices,images,exports,_inbox}

# Git init
git init
git add .
git commit -m "Initial commit: myproject"

Шаг 3: Конфигурация

Заполнить файлы:
- PROJECT.md — описание бизнеса
- CLAUDE.md — контекст для Claude
- index.yaml — индекс проекта
- config/ — конфигурации сервисов

Создать credentials:

# НЕ коммитить в git!
touch .credentials.md
echo ".credentials.md" >> .gitignore

# Формат .credentials.md
cat > .credentials.md << 'EOF'
# Credentials: myproject

## Database
- Host: localhost
- Name: myproject_db
- User: myproject_user
- Password: [см. 1Password]

## API Keys
- Service: xxx-yyy-zzz
EOF

Шаг 4: Валидация

Проверить соответствие:

# Проверить структуру проекта
validate-project myproject

# Проверить всю платформу
validate-platform

# Проверить что нет хардкодов
grep -r "/opt/claude-workspace\|/mnt/beget-s3" $(project_ws myproject)
# → Не должно быть результатов

Шаг 5: Документация

Обновить индекс:

# Добавить в architect/templates/project.index.yaml
echo "  - name: myproject
    type: commercial
    status: active
    path: projects/org/myproject" >> architect/templates/project.index.yaml

Ссылки в docs:
- Добавить в http://docs.0kt.ru/projects/
- Создать базу в NocoDB: http://docs.0kt.ru:8085


CLI скрипт create-project.sh

Спецификация:

#!/bin/bash
# ═══════════════════════════════════════════════════════════════════════════════
# CREATE PROJECT
# Автоматическое создание нового проекта
# ═══════════════════════════════════════════════════════════════════════════════

source $WORKSPACE/system/config/platform-vars.sh

# Валидация имени
validate_name() {
    local name=$1
    if [[ ! "$name" =~ ^[a-z0-9_-]+$ ]]; then
        echo "❌ Имя проекта может содержать только: a-z 0-9 _ -"
        return 1
    fi

    if [ -d "$(project_ws $name)" ]; then
        echo "❌ Проект $name уже существует"
        return 1
    fi

    return 0
}

# Создание структуры workspace
create_workspace() {
    local name=$1
    local type=${2:-commercial}

    local ws=$(project_ws $name)

    echo "📁 Создание workspace: $ws"
    mkdir -p "$ws"/{config,services,scripts}

    # Копирование шаблонов
    cp "$ARCHITECT/templates/PROJECT_${type^^}.md" "$ws/PROJECT.md"
    cp "$ARCHITECT/templates/CLAUDE_TEMPLATE.md" "$ws/CLAUDE.md"

    # Замена плейсхолдеров
    sed -i "s/{PROJECT_NAME}/$name/g" "$ws/PROJECT.md"
    sed -i "s/{PROJECT_NAME}/$name/g" "$ws/CLAUDE.md"

    # Git init
    cd "$ws"
    git init
    echo ".credentials.md" > .gitignore

    echo "✅ Workspace создан"
}

# Создание структуры dataspace
create_dataspace() {
    local name=$1
    local data=$(project_data $name)

    echo "📁 Создание dataspace: $data"
    mkdir -p "$data"/{prices,images,exports,_inbox}

    # Создание README для каждой папки
    echo "# Прайсы поставщиков" > "$data/prices/README.md"
    echo "# Изображения товаров" > "$data/images/README.md"
    echo "# Выгрузки" > "$data/exports/README.md"
    echo "# Входящие файлы" > "$data/_inbox/README.md"

    echo "✅ Dataspace создан"
}

# Валидация результата
validate_result() {
    local name=$1

    echo "🔍 Валидация..."

    if ! validate_project $name; then
        echo "❌ Валидация не прошла"
        return 1
    fi

    echo "✅ Валидация пройдена"
    return 0
}

# Главная функция
main() {
    local name=$1
    local type=${2:-commercial}

    echo "═══════════════════════════════════════════════════════════"
    echo "Создание проекта: $name"
    echo "Тип: $type"
    echo "═══════════════════════════════════════════════════════════"

    # Валидация
    if ! validate_name "$name"; then
        exit 1
    fi

    # Создание
    create_workspace "$name" "$type" || exit 1
    create_dataspace "$name" || exit 1

    # Валидация
    validate_result "$name" || exit 1

    echo ""
    echo "✅ Проект $name создан успешно!"
    echo ""
    echo "Workspace: $(project_ws $name)"
    echo "Dataspace: $(project_data $name)"
    echo ""
    echo "Следующие шаги:"
    echo "1. Заполнить PROJECT.md и CLAUDE.md"
    echo "2. Создать .credentials.md (НЕ коммитить!)"
    echo "3. Проверить: validate-project $name"
}

# Запуск
if [ $# -eq 0 ]; then
    echo "Использование: create-project <name> [type]"
    echo "Пример: create-project myproject commercial"
    exit 1
fi

main "$@"

Расположение: system/scripts/create-project.sh


Валидатор validate-platform.sh

Спецификация:

#!/bin/bash
# ═══════════════════════════════════════════════════════════════════════════════
# VALIDATE PLATFORM
# Проверка соответствия проектов стандартам платформы
# ═══════════════════════════════════════════════════════════════════════════════

source $WORKSPACE/system/config/platform-vars.sh

# Проверка одного проекта
check_project() {
    local name=$1
    local ws=$(project_ws $name)
    local data=$(project_data $name)
    local errors=0

    echo "Проверка: $name"

    # 1. Workspace существует
    if [ ! -d "$ws" ]; then
        echo "  ❌ Workspace не существует: $ws"
        ((errors++))
    fi

    # 2. Dataspace существует
    if [ ! -d "$data" ]; then
        echo "  ❌ Dataspace не существует: $data"
        ((errors++))
    fi

    # 3. Обязательные файлы
    for file in CLAUDE.md PROJECT.md; do
        if [ ! -f "$ws/$file" ]; then
            echo "  ❌ Отсутствует файл: $file"
            ((errors++))
        fi
    done

    # 4. Хардкоды
    if [ -d "$ws" ]; then
        local hardcodes=$(grep -r "/opt/claude-workspace\|/mnt/beget-s3" "$ws" \
            --exclude-dir=.git \
            --exclude-dir=node_modules \
            --exclude="*.log" 2>/dev/null | wc -l)

        if [ "$hardcodes" -gt 0 ]; then
            echo "  ⚠️  Найдено хардкодов: $hardcodes"
            ((errors++))
        fi
    fi

    # 5. Большие файлы в workspace
    if [ -d "$ws" ]; then
        local big_files=$(find "$ws" -type f -size +10M \
            -not -path "*/.git/*" 2>/dev/null | wc -l)

        if [ "$big_files" -gt 0 ]; then
            echo "  ⚠️  Найдено больших файлов (>10MB): $big_files"
            echo "     Переместить в dataspace!"
            ((errors++))
        fi
    fi

    # Результат
    if [ $errors -eq 0 ]; then
        echo "  ✅ OK"
        return 0
    else
        echo "  ❌ Ошибок: $errors"
        return 1
    fi
}

# Проверка всех проектов
check_all() {
    echo "═══════════════════════════════════════════════════════════"
    echo "Валидация платформы"
    echo "═══════════════════════════════════════════════════════════"
    echo ""

    local total=0
    local failed=0

    if [ ! -d "$WORKSPACE/$PROJECTS_NAMESPACE" ]; then
        echo "❌ $WORKSPACE/$PROJECTS_NAMESPACE не существует!"
        return 1
    fi

    for project in $(ls "$WORKSPACE/$PROJECTS_NAMESPACE" 2>/dev/null); do
        ((total++))
        if ! check_project "$project"; then
            ((failed++))
        fi
        echo ""
    done

    echo "═══════════════════════════════════════════════════════════"
    echo "Проверено проектов: $total"
    echo "С ошибками: $failed"

    if [ $failed -eq 0 ]; then
        echo "✅ Все проекты соответствуют стандартам"
        return 0
    else
        echo "❌ Найдены нарушения стандартов"
        return 1
    fi
}

# Главная функция
main() {
    local project=$1

    if [ -z "$project" ]; then
        # Проверить все проекты
        check_all
    else
        # Проверить конкретный проект
        check_project "$project"
    fi
}

main "$@"

Расположение: system/scripts/validate-platform.sh


Правила работы

1. Всегда через переменные

При создании скриптов:

# ВСЕГДА в начале
source $WORKSPACE/system/config/platform-vars.sh

# ВСЕГДА использовать функции или переменные
cd $(project_ws myproject)  # ✅
cd /opt/claude-workspace/projects/org/myproject  # ❌

2. Валидация обязательна

Перед началом работы с проектом:

validate-project myproject

Перед коммитом изменений:

# Проверить что нет хардкодов
grep -r "/opt/claude-workspace" $(project_ws myproject)

# Проверить что больших файлов нет
find $(project_ws myproject) -size +10M

3. Данные только в dataspace

НИКОГДА не хранить в workspace:
- Изображения (.jpg, .png, .gif)
- Документы (.pdf, .docx, .xlsx)
- Видео (.mp4)
- Большие архивы (.tar.gz >10MB)
- Бинарные файлы

Хранить в dataspace:

# Правильно
cp large-file.xlsx $(project_data myproject)/_inbox/

# Неправильно
cp large-file.xlsx $(project_ws myproject)/

4. Credentials отдельно

Создать .credentials.md:

cd $(project_ws myproject)
touch .credentials.md
echo ".credentials.md" >> .gitignore

Не хранить в коде:
- Пароли БД
- API ключи
- Токены
- Приватные ключи SSH

Ссылаться через комментарии:

# config/database.yaml
host: localhost
user: myproject_user
password: # см. .credentials.md

Автоматизация

Ежедневная валидация

Расписание: Через system/scheduler/

# system/scheduler/schedule.yaml
validate_platform:
  description: "Ежедневная валидация платформы"
  command: "bash system/scripts/validate-platform.sh"
  cron: "0 4 * * *"  # Каждый день в 04:00
  enabled: true

Pre-commit hook

Файл: .git/hooks/pre-commit

#!/bin/bash
# Проверка перед коммитом

# Проверить хардкоды
if git diff --cached | grep -E "/opt/claude-workspace|/mnt/beget-s3"; then
    echo "❌ Найдены хардкоды! Используйте переменные."
    exit 1
fi

# Проверить большие файлы
for file in $(git diff --cached --name-only); do
    if [ -f "$file" ]; then
        size=$(stat -f%z "$file" 2>/dev/null || stat -c%s "$file" 2>/dev/null)
        if [ "$size" -gt 10485760 ]; then  # 10MB
            echo "❌ Файл $file слишком большой ($(($size/1024/1024))MB)"
            echo "   Переместите в dataspace!"
            exit 1
        fi
    fi
done

echo "✅ Pre-commit проверки пройдены"

Связи

Стандарты

Конфигурация

Инструменты


История


Версия: 1.0.0