ИНЖЕНЕРНЫЙ СТАНДАРТ v1.0 (FastAPI Foundry Edition)

Предыдущая версия: v0.3.1
Статус: ✅ Production Ready
Авторское право: © 2026 hypo69

📋 Содержание

Введение и область применения
Нормативные ключевые слова (RFC 2119)
Фундаментальные принципы архитектуры
Общие правила проектирования и устранение Code Smells
Стандарты комментирования и документирования
Языковые стандарты разработки
Работа с конфигурацией, файлами и логированием
Правила для искусственного интеллекта (AI Coding Rules)
Приложения и шаблоны

1. Введение и область применения

Настоящий документ определяет Единый инженерный стандарт разработки (Engineering Standard v1.0) для экосистемы интеллектуального помощника. Стандарт спроектирован как руководящий технический регламент для разработчиков и как системная инструкция для ИИ-ассистентов (LLM), участвующих в написании, рефакторинге и аудите кодовой базы.

1.1 Область действия

Требования стандарта распространяются на:

Все новые и существующие исходные файлы во всех репозиториях проекта.
Архитектурные решения, структуру каталогов, форматы хранения конфигураций и секретов.
Форматирование кода, структуру комментариев и генерацию автодокументации.

2. Нормативные ключевые слова (RFC 2119)

Для однозначной интерпретации требований в стандарте используются ключевые слова в соответствии со спецификацией RFC 2119:

MUST (НЕОБХОДИМО / ОБЯЗАТЕЛЬНО): Абсолютное требование к реализации. Нарушение данного требования делает кодовую базу неприемлемой для интеграции.
MUST NOT (НЕ ДОПУСКАЕТСЯ / ЗАПРЕЩЕНО): Абсолютный запрет на использование конструкции, метода или паттерна.
SHOULD (СЛЕДУЕТ / РЕКОМЕНДУЕТСЯ): Означает, что в конкретных обстоятельствах могут существовать веские причины для отклонения от правила, но разработчик (или ИИ) обязан полностью оценить последствия такого выбора, задокументировать его обоснование и взвесить все риски.
SHOULD NOT (НЕ РЕКОМЕНДУЕТСЯ): Означает нежелательность применения практики, требующую детального технического обоснования при реализации.
MAY (ДОПУСКАЕТСЯ / ВОЗМОЖНО): Полностью опциональное действие или выбор инструмента.

3. Фундаментальные принципы архитектуры

Все технические решения в рамках проекта MUST подчиняться следующим приоритетным принципам:

3.1 Читаемость важнее краткости (Readability Over Cleverness)

Код пишется для последующего чтения человеком или анализа ИИ. Использование скрытых трюков синтаксиса, ухудшающих читаемость, MUST NOT допускаться ради экономии нескольких строк кода.

3.2 Принцип единственной ответственности (Single Responsibility Principle)

Каждый модуль, класс и функция MUST решать только одну логическую задачу. Если функция выполняет несколько несвязанных действий, она SHOULD быть разделена.

3.3 Явное лучше неявного (Explicit is Better than Implicit)

Передача зависимостей MUST выполняться явно (Dependency Injection).
Глобальное состояние кодовой базы MUST NOT использоваться; все общие параметры MUST передаваться через контролируемый конфигурационный объект Config (или аналогичный синглтон-контекст).

3.4 Ранний возврат и отказоустойчивость (Early Return & Fail-Fast)

Функции MUST завершать выполнение сразу после обнаружения невалидных входных данных или невыполнения предусловий.

# ✅ Рекомендованный формат (Ранний возврат)
def process_user_data(data: dict) -> bool:
    if not data:
         return False
    # Выполнение основной логики
    return True

# ❌ Нежелательный формат (Глубокая вложенность)
def process_user_data(data: dict) -> bool:
    if data:
         # Выполнение основной логики
         return True
    return False

3.5 Конфигурация вместо жесткого кодирования (Configuration over Hardcode)

Использование жестко закодированных параметров (hardcoded parameters) в исходном коде приложения MUST NOT допускаться. Все параметры, включая номера сетевых портов, сетевые адреса (URL/IP), таймауты, пути к директориям, лимиты и режимы работы, MUST считываться из внешнего конфигурационного файла JSON (через объект config) или переменных окружения.

❌ Неправильно:
```
port = 8000
```
✅ Правильно:
```
port = config.port
```

3.6 Категорический запрет использования и ссылок на `None`

Использование ключевого слова None, а также любые явные или неявные ссылки на него в исходном коде КАТЕГОРИЧЕСКИ ЗАПРЕЩЕНЫ (MUST NOT). Исключение данного объекта из кодовой базы является фундаментальным требованием стабильности типов.

3.6.1 Абсолютный запрет `None` в сигнатурах функций (Параметры по умолчанию)

Аргументы функций MUST NOT принимать None in качестве значения по умолчанию. Сигнатура функции MUST использовать пустые (дефолтные) значения соответствующих типов данных. Использование конструкции Optional[...] допускается исключительно при условии, что значение по умолчанию строго определено типом, отличным от None (например, Optional[int] = 0).

❌ Плохо (Bad):

def execute_connection(self, timeout: Optional[int] = None, input_str: Optional[str] = None) -> Self:

✅ Хорошо (Good):

def execute_connection(self, timeout: Optional[int] = 0, input_str: Optional[str] = '') -> Self:

3.6.2 Запрет в инициализации переменных и свойствах классов

Локальные, глобальные переменные и свойства классов КАТЕГОРИЧЕСКИ ЗАПРЕЩЕНЫ (MUST NOT) инициализироваться значением None. Переменные MUST инициализироваться только пустыми значениями соответствующих типов:

Числовые типы (int, float): 0 или 0.0.
Строковые типы (str): '' (пустая строка).
Булевы типы (bool): False.
Коллекции (list, dict): [] или {}.
❌ Плохо (Bad):
```
str_output = None
dict_output = None
```
✅ Хорошо (Good):
```
str_output = ''
dict_output = {}
```

3.6.3 Запрет в операторах сравнения и возвращаемых значениях

Операторы сравнения is None и is not None КАТЕГОРИЧЕСКИ ЗАПРЕЩЕНЫ (MUST NOT). Проверка состояния объектов должна выполняться на предмет их истинности (boolean truthiness) или через явную валидацию значений по умолчанию.
Функции MUST NOT возвращать значение None или использовать пустой оператор return (который неявно возвращает None). При обработке ошибочных сценариев, отсутствии данных, раннем выходе или сбое функции MUST явно возвращать False (или false для JS/PHP/HTML).

❌ Плохо (Bad):
```
if connection is None:
    ...
```
✅ Хорошо (Good):
```
if not connection:
    ...
```

4. Общие правила проектирования и устранение Code Smells

Для поддержания качества архитектуры устанавливаются следующие ограничения на структурную сложность кода:

4.1 Ограничение вложенности (Nesting Limit)

Глубина вложенности циклов и условий внутри одной функции SHOULD NOT превышать 3 уровней. Если вложенность выше — это явный сигнал о необходимости декомпозиции кода на отдельные функции.

4.2 Избегание дублирования (DRY)

Дублирование аналогичной логики в нескольких модулях MUST NOT допускаться. Идентичные операции (например, запросы к OpenAI-совместимым API различных провайдеров) MUST объединяться в универсальные коннекторы, параметризуемые через конфигурацию.

4.3 Мертвый код (Dead Code)

Неиспользуемые переменные, импорты, функции и мертвые файлы MUST удаляться сразу после рефакторинга. Оставление закомментированного кода "на будущее" MUST NOT допускаться.

4.4 Ограничение размера функций (Function Size Limit)

Физический размер любой функции (без учета строк комментариев и docstrings) MUST NOT превышать 300 строк кода. Если объем тела функции превышает лимит, она ОБЯЗАНА (MUST) быть декомпозирована. Весь процесс должен быть разбит на несколько изолированных и легко тестируемых вспомогательных функций меньшего размера, а основная функция должна выполнять роль координатора (диспетчера), вызывая их последовательно согласно сценарию (workflow).

5. Стандарты комментирования и документирования

5.1 Философия комментариев: «Почему», а не «Что»

Комментарии в коде SHOULD объяснять инженерное решение и логические предпосылки выбора конкретного пути реализации, а не дублировать синтаксис языка.

// ✅ Correct: explanation of structural choices and performance reasoning
// Usage of Set instead of Array to ensure unique IDs in O(1) complexity
const activeConnections = new Set();

// ❌ Incorrect: redundant syntax description
// Creation of a new set of active connections
const activeConnections = new Set();

5.2 Использование отглагольных существительных в комментариях

При написании русскоязычных комментариев (разрешено для Python и PowerShell) вместо глагольных форм (глаголов, деепричастий) MUST использоваться отглагольные существительные, выражающие процесс или состояние.

Плохо: // Отправляет запрос, // Суммаризирует текст, // Объединяет данные
Хорошо: // Отправка запроса, // Суммаризация текста, // Объединение данных

Для англоязычных комментариев (весь Web-стек и PHP) SHOULD использоваться существительные или отглагольные формы (Noun/Gerund), выражающие процесс: Initialization, Verification, Loading, Execution (вместо глаголов вроде Initializes, Verifies, Loads).

5.3 Языковые зоны комментариев

Ограничения на использование языков в комментариях введены для предотвращения сбоев Юникода (Unicode breakage), повреждения кодировки файлов и критических ошибок интерпретации в веб-среде и PHP-окружении.

Тип расширения файлов	Комментарии в коде	Документирование (Docstrings / JSDoc)	Заголовок файла (Header Blocks)	Обоснование ограничения
`.js`, `.ts`, `.jsx`, `.tsx`	English only	English only	English only	MUST NOT содержать кириллицу во избежание поломки Юникода в веб-окружении.
`.css`, `.scss`, `.sass`	English only	English only	English only	MUST NOT содержать кириллицу во избежание поломки Юникода при сборке ассетов.
`.html`	English only	—	English only	MUST NOT содержать кириллицу во избежание проблем с кодировкой при рендеринге страниц.
`.php`	English only	English only	English only	MUST NOT содержать кириллицу во избежание ошибок парсинга и сбоев Юникода в PHP-окружении.
`.py`, `.ps1`	Russian / English	Russian / English	Russian / English	Допускается использование кириллицы (строго UTF-8 без BOM).

5.4 Стандарт документирования функций (`hypo69 docblock`)

Для всех публичных методов, функций и классов во всех языках программирования MUST использоваться единый унифицированный формат описания секций.

Исключение Sphinx и reStructuredText

Использование конструкций Sphinx/reST (таких как .. module::, :platform:, :synopsis:, :param:, :returns:) MUST NOT допускаться. Если такие блоки обнаруживаются в существующем коде, они MUST быть удалены и заменены на стандартный формат.

Структура секций

Порядок и наименование секций в Docstring/Docblock MUST строго соответствовать следующей схеме:

Short Description        ← Однострочное описание сути сущности
Long Description         ← (Опционально) Детальное объяснение причин реализации

Args:
    param_name (type): Описание параметра, ограничения, значения по умолчанию.

Returns:
    type: Описание возвращаемого значения и условий возврата.

Exceptions:
    ErrorType: Условия генерации исключения.

Examples:
    Пример вызова функции в виде работающего кода.

Секции Args:, Returns:, Exceptions:, Examples: — MUST присутствовать для каждой публичной функции. Если секция неприменима (например, нет исключений или параметров), она просто опускается.
Порядок секций MUST NOT изменяться.
Слово Params: — ЗАПРЕЩЕНО, используется только Args:.
Слово Raises: — ЗАПРЕЩЕНО, используется только Exceptions:.
В секции Examples: MUST содержаться минимально рабочий пример вызова кода, который можно скопировать и протестировать.

6. Языковые стандарты разработки

6.1 Python Style Guide (v3.12+)

Разработка на Python MUST использовать современные возможности версий 3.12+ (использование pathlib, enum.StrEnum, match, @override, typing.Self, Protocol, TypedDict).

Шапка файла Python

Каждый файл Python MUST начинаться со следующего структурированного заголовка:

# -*- coding: utf-8 -*-
# =============================================================================
# Название процесса: Интеграция с локальным сервером Foundry
# =============================================================================
# Описание:
#   Организация взаимодействия с API Foundry через HTTP-протокол.
#   Выполнение проверок доступности портов и управление процессами.
#
# Примеры:
#   >>> from src.foundry import FoundryConnector
#   >>> connector = FoundryConnector(port=config.port)
#   >>> connector.verify_status()
#
# File: foundry_connector.py
# Project: Наш интеллектуальный помощник
# Package: FoundryIntegration
# Module: Core
# Class: FoundryConnector
# Function: verify_status
# Author: hypo69
# Copyright: © 2026 hypo69
# =============================================================================

Группировка импортов

Импорты MUST упорядочиваться по алфавиту и разделяться на три четких логических блока пустой строкой:

Системные библиотеки (stdlib).
Сторонние библиотеки (third-party).
Модули текущего проекта (project imports), начиная с корневого импорта.

import os
import sys
from pathlib import Path

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

from header import __root__
from src import gs
from src.logger import logger
from src.utils.printer import pprint

Пример реализации класса и функции на Python

from typing import Self, Optional

class FoundryConnector:
    """Обеспечение соединения с API-интерфейсом Foundry.

    Управление локальными процессами и мониторинг состояния портов.

    Attributes:
        port (int): Номер сетевого порта сервера.
        status (str): Текущее состояние подключения.
    """

    def __init__(self, port: int) -> None:
        """Инициализация объекта подключения."""
        self.port: int = port
        self.status: str = "disconnected"

    def execute_connection(self, timeout: Optional[int] = 0, input_str: Optional[str] = '') -> Self:
        """Запуск процесса подключения к серверу.

        Args:
            timeout (Optional[int]): Максимальное время ожидания ответа в секундах.
                                     Значение по умолчанию: 0.
            input_str (Optional[str]): Входная строка инициализации.
                                       Значение по умолчанию: ''.

        Returns:
            Self: Текущий экземпляр объекта для поддержки цепочки вызовов.

        Exceptions:
            ConnectionError: Ошибка инициализации сетевого сокета при недоступности порта.

        Examples:
            >>> connector = FoundryConnector(port=config.port)
            >>> connector.execute_connection(timeout=10, input_str='init')
            <FoundryConnector object at 0x...>
        """
        # Проверка инициализации порта перед запуском соединения
        if self.port <= 0:
            raise ConnectionError("Неверный номер порта")

        self.status = "connected"
        return self

6.2 PHP & WordPress Style Guide (v8.3+)

Разработка на PHP ориентирована на современную версию PHP 8.3+ и стандарты разработки WordPress.

Запрещается использование устаревшего кода; вся логика плагинов SHOULD упаковываться в Singleton-классы.
Обязательно использование nonce-проверок, санитизации и экранирования вывода.
Кириллица полностью запрещена в исходном коде PHP файлов (включая шапки и комментарии) во избежание повреждения Юникода.

Шапка файла PHP

<?php
# -*- coding: utf-8 -*-
# =============================================================================
# Process Name: WordPress Post Metadata Processing
# =============================================================================
# Description:
#   Registration of custom metadata fields for plugin post types.
#   Sanitization of incoming requests and escaping output in templates.
#
# Examples:
#   1. Hook registration:
#        add_action('save_post', [Post_Metadata::get_instance(), 'save_meta']);
#
# File: class-post-metadata.php
# Project: Our Intelligent Assistant
# Package: PluginMeta
# Class: Post_Metadata
# Author: hypo69
# Copyright: © 2026 hypo69
# =============================================================================

Пример безопасного класса PHP / WordPress

<?php
defined( 'ABSPATH' ) || exit;

class Post_Metadata {
    /**
     * Singleton instance.
     *
     * @var Post_Metadata|null
     */
    private static ?Post_Metadata $instance = null;

    /**
     * Instance retrieval.
     *
     * @return Post_Metadata
     */
    public static function get_instance(): Post_Metadata {
        if ( null === self::$instance ) {
            self::$instance = new self();
        }

        return self::$instance;
    }

    /**
     * Constructor.
     */
    private function __construct() {
        $this->init_hooks();
    }

    /**
     * Hook initialization.
     */
    private function init_hooks() {
        add_action( 'save_post', [ $this, 'save_custom_fields' ], 10, 2 );
    }

    /**
     * Saving of custom metadata fields on post save action.
     *
     * Args:
     *   post_id (int) — Current WordPress post ID.
     *   post (WP_Post) — Post object.
     *
     * Returns:
     *   bool — Verification success.
     *
     * Exceptions:
     *   RuntimeException — Thrown on security verification failure.
     *
     * Examples:
     *   $meta_manager = Post_Metadata::get_instance();
     *   // Triggered automatically via save_post action hooks
     */
    public function save_custom_fields( int $post_id, WP_Post $post ): bool {
        // Verification of security token (nonce) presence
        if ( ! isset( $_POST['custom_meta_nonce'] ) || 
             ! wp_verify_nonce( $_POST['custom_meta_nonce'], 'save_custom_meta' ) ) {
            return false;
        }

        // Capabilities authorization check
        if ( ! current_user_can( 'edit_post', $post_id ) ) {
            return false;
        }

        // Sanitization and storage of user input parameters
        if ( isset( $_POST['custom_field_value'] ) ) {
            $sanitized_value = sanitize_text_field( wp_unslash( $_POST['custom_field_value'] ) );
            update_post_meta( $post_id, '_custom_field_key', $sanitized_value );
        }

        return true;
    }
}

6.3 JavaScript & TypeScript Style Guide (ES2024)

При написании скриптов MUST использоваться стандарт ES2024 (асинхронность через async/await, деструктуризация, optional chaining ?., nullish coalescing ??).

Кириллица полностью запрещена в исходном коде JS/TS файлов (включая шапки и комментарии) во избежание повреждения Юникода.

Шапка файла JS/TS

/**
 * =============================================================================
 * Process Name: Asynchronous API Provider Interaction
 * =============================================================================
 * Description:
 *   Abstract client implementation for executing HTTP requests to OpenAI-compatible APIs.
 *   Provides dynamic authorization headers configuration based on provider parameters.
 *
 * Examples:
 *   const client = new ApiClient(config.openai.baseUrl);
 *   await client.fetchData('/chat/completions', { model: config.openai.model });
 *
 * File: api-client.js
 * Project: Our Intelligent Assistant
 * Module: Network
 * Class: ApiClient
 * Author: hypo69
 * Copyright: © 2026 hypo69
 * =============================================================================
 */

Пример кода JS/TS

class ApiClient {
    /**
     * Initialization of the base API client.
     *
     * @param {string} baseUrl - Base endpoint URL path.
     */
    constructor(baseUrl) {
        this.baseUrl = baseUrl;
    }

    /**
     * Asynchronous HTTP POST execution to selected path.
     *
     * Args:
     *   endpoint (string) — API endpoint target path.
     *   payload (object) — Request body payload details.
     *
     * Returns:
     *   object — Resolved JSON data response object.
     *
     * Exceptions:
     *   Error — Thrown on network timeout or failed status codes.
     *
     * Examples:
     *   const client = new ApiClient(config.api.baseUrl);
     *   const response = await client.postData('/submit', { id: config.api.id });
     */
    async postData(endpoint, payload) {
        // Checking of endpoint parameter existence
        if (!endpoint) {
            throw new Error("Missing endpoint parameter");
        }

        const targetUrl = `${this.baseUrl}${endpoint}`;
        
        // Execution of fetch request
        const response = await fetch(targetUrl, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(payload ?? {})
        });

        if (!response.ok) {
            throw new Error(`HTTP Error Status: ${response.status}`);
        }

        return await response.json();
    }
}

6.4 HTML & CSS/SCSS Style Guide

Кириллица полностью запрещена в исходном коде HTML/CSS/SCSS файлов (включая шапки и комментарии) во избежание повреждения Юникода.

Шаблон шапки файлов HTML

<!--
===============================================================================
Process Name: Dashboard Settings Configuration Layout
===============================================================================
Description:
    Core template for managing system integrations, connection parameters, and API keys.
    Utilizes data-i18n attributes on label tags to ensure translation support.

File: dashboard-settings.html
Project: Our Intelligent Assistant
Module: AdminUI
Author: hypo69
Copyright: © 2026 hypo69
===============================================================================
-->

Шаблон шапки файлов CSS/SCSS

/*
===============================================================================
Process Name: Dashboard Settings Styling Interface
===============================================================================
Description:
    Layout and visual rules for inputs, action forms, and administration panels.
    Implements CSS Grid layouts and responsive variables for system themes.

File: admin-styles.css
Project: Our Intelligent Assistant
Module: AdminUI
Author: hypo69
Copyright: © 2026 hypo69
===============================================================================
*/

7. Работа с конфигурацией, файлами и логированием

7.1 Операции ввода-вывода (Файлы и JSON)

Все файловые операции в Python MUST выполняться только через специализированные функции-обертки из библиотеки утилит проекта:

Чтение данных: j_loads(), j_loads_ns(), read_text_file().
Запись данных: j_dumps(), save_text_file().

Особенности утилит:

Эти функции автоматически выполняют логирование ошибок ввода-вывода и создание недостающей структуры директорий (для записи).

Правило обработки результатов:

Поскольку эти вспомогательные утилиты внутри себя обрабатывают все исключения файловой системы, выполняют обязательное логирование и возвращают ложное значение (False) в случае сбоя, исключения не будут передаваться вызывающему коду.

Оборачивание вызовов этих утилит в блоки try/except является логически избыточным и НЕ ДОПУСКАЕТСЯ (MUST NOT). Кроме того, так как утилиты уже самостоятельно логируют факт сбоя, вызывающий код MUST NOT повторно вызывать логгер (во избежание дублирования логов). Вызывающий код должен исключительно обрабатывать логику управления кодом и выполнять ранний возврат.

# ✅ Правильно: Явная проверка возвращаемого значения без дублирования логирования
# Примечание: Самостоятельное логирование ошибки утилитой j_loads при сбое.
# Осуществление вызывающим кодом раннего возврата (Early Return) без повторного логирования.
config_data = j_loads(config_path)
if not config_data:
    return False

# ❌ Неправильно: Избыточное логирование (дублирование логов) и неверный try/except
# Примечание: Отсутствие генерации исключения; засорение логов повторным вызовом логгера.
try:
    config_data = j_loads(config_path)
    if not config_data:
        logger.error(f"Не удалось загрузить файл")  # Дублирование лога!
        return False
except Exception as e:
    logger.error("Ошибка файловой системы", e)  # Мертвый код, отсутствие выполнения блока.

7.2 Разделение конфигураций и секретов

Параметры работы приложения разделяются на два типа: публичные настройки и приватные (секреты).

Тип	Способ хранения	Механизм дистрибуции	Пример
Публичные	`config.json`	Хранится в Git репозитории	Порты, таймауты, пути к RAG-индексам
Секретные	`.env`	MUST NOT попадать в Git (добавляется в `.gitignore`)	API ключи, JWT секреты, пароли БД

Использование переменных окружения внутри JSON

В публичном файле config.json запрещается прямое указание секретных значений. Для ссылок на секреты MUST использоваться строго заданный формат плейсхолдера: "${ENVIRONMENT_VARIABLE_NAME}".

Системный обработчик переменных окружения при старте приложения автоматически подставляет значения из .env вместо плейсхолдеров.

{
  "huggingface": {
    "api_endpoint": "https://api-inference.huggingface.co",
    "token": "${HUGGING_FACE_TOKEN}"
  }
}

Обязательные переменные окружения (.env.example)

При добавлении в кодовую базу любого нового секрета, его плейсхолдер MUST одновременно добавляться в файл .env.example с описанием назначения:

# Токен HuggingFace для работы с закрытыми моделями
HUGGING_FACE_TOKEN=hf_your_token_here

# Сетевые параметры локального окружения Foundry
FOUNDRY_BASE_URL=http://localhost
FOUNDRY_DYNAMIC_PORT=3000

7.3 Логирование и вывод информации

Вывод логов во всех средах выполнения MUST осуществляться исключительно через стандартный объект логгера проекта src.logger.logger.
Использование системного вызова print() для вывода информации в консоль MUST NOT допускаться в продакшн-коде.
Для отладочной печати сложных структур в консоль (в среде разработки) MUST использоваться утилита красивого вывода pprint.

# ✅ Запись ошибки с исключением
logger.error("Сбой инициализации API коннектора", ex, exc_info=True)

# ✅ Вывод отладочной структуры
pprint(debug_data_structure)

8. Правила для искусственного интеллекта (AI Coding Rules)

ИИ-ассистенты, работающие с кодовой базой проекта, ОБЯЗАНЫ строго руководствоваться следующими протоколами анализа и модификации исходных кодов:

8.1 Протокол предварительного анализа

Перед внесением изменений в файл ИИ MUST прочитать файл полностью и проанализировать структуру его импортов, комментариев и архитектурных связей.
ИИ MUST сопоставить вносимые изменения с общими архитектурными принципами проекта (Early Return, DRY, Single Responsibility).

8.2 Протокол модификации и сохранения целостности

Запрет рефакторинга ради рефакторинга: ИИ MUST NOT переписывать корректно работающий код только ради изменения визуального стиля, если он не нарушает данный инженерный стандарт.
Сохранение существующего API: При внесении изменений ИИ MUST сохранять сигнатуры публичных методов, классов и интерфейсов обратной совместимости, если иное явно не указано в задаче.
Запрет на генерацию незавершенных блоков: Генерация комментариев-маркеров, такого плана как // TODO: реализовать позже, /* FIXME */ или добавление пустых заглушек-заполнителей вместо написания логики MUST NOT допускаться.
Сохранение служебных комментариев: Символы отладки (строки с троеточиями ...), а также автогенерируемые заголовки с метаданными файлов MUST бережно сохраняться в неизменном виде.

9. Приложения и шаблоны

9.1 Шаблон файла README.md для каталогов проекта

Внутри каждой директории проекта MUST находиться файл README.md, описывающий ее структуру и функциональное назначение. Файл составляется по следующему жесткому шаблону:

# Название директории (например: src/utils)

## Описание
Краткое описание назначения данной папки, ее роли в глобальной архитектуре проекта.

## Обзор файлов и модулей
* `printer.py` — Обеспечение красивого консольного вывода сложных структур данных.
* `json_processor.py` — Утилиты безопасного чтения, парсинга и записи JSON файлов.

## Связи и зависимости
* Модуль импортируется всеми уровнями приложения для ведения вспомогательных операций.
* Зависит от системных утилит сериализации данных.

9.2 Итоговый чек-лист контроля качества перед отправкой коммита (Commit Checklist)

Перед завершением работы над задачей и отправкой изменений в репозиторий, разработчик или ИИ-ассистент MUST выполнить проверку по следующему контрольному списку:

Name		Name	Last commit message	Last commit date
LICENSE		LICENSE
README.md		README.md
code-rules.md		code-rules.md
Стандарт кроссплатформенной разработки приложений.md		Стандарт кроссплатформенной разработки приложений.md
регламент туннлирования.md		регламент туннлирования.md

Latest commit

History

Folders and files

Repository files navigation