AgentSkillsCN

update-docs-on-code-change

在本仓库中，当 Python、MQL4 代码或 Notebook 发生变更时，使用此技能同步代码文档（包括头文件、文档字符串、Markdown 文档以及架构说明）。

SKILL.md
--- frontmatter
name: update-docs-on-code-change
description: >
  Use this skill to sync code documentation (headers, docstrings, Markdown docs, architecture)
  after code changes in Python, MQL4 and notebooks in this repository.
tags:
  - documentation
  - workflows
  - sync
triggers:
  - when user says "sync docs", "обнови документацию", "синхронизируй docs"
  - when user mentions that code has changed and asks to update docs
applies_to:
  - "*.py"
  - "*.mq4"
  - "*.mqh"
  - "*.ipynb"
always_apply: false

Skill: Синхронизация документации при изменении кода

Цель

Поддерживать документацию в актуальном состоянии при изменении кода: file headers, docstrings, Markdown‑документацию и архитектурные описания.

Когда использовать

  • •Пользователь говорит: sync docs, «обнови документацию», «синхронизируй docs».
  • •Пользователь сообщает, что изменил конкретный файл и просит обновить документацию.
  • •После серии изменений в коде перед подготовкой PR/merge.

Высокоуровневый алгоритм

  1. •Определить изменённые файлы.
  2. •Найти соответствующую им документацию.
  3. •Обновить элементы документации в коде и .md‑файлах.
  4. •Показать diff и запросить подтверждение перед внесением изменений.

Подробные шаги

Шаг 1. Найди изменённые файлы

  1. •

    Если пользователь явно указал файлы — используй их.

  2. •

    Иначе выполни в корне репозитория:

    bash
    git diff --cached --name-only | grep -E '\.(py|mq4|mqh|ipynb)$'
  3. •

    Игнорируй файлы вне указанных расширений.

Шаг 2. Определи соответствующую документацию

Для каждого изменённого файла определи связанный .md/архитектурный файл:

  • •processing/[script].py → docs/data_preprocessing/[script].md
  • •statistics/[script].py → docs/data_analysis/[script].md
  • •MT/MQL4/Include/[lib].mqh → docs/architecture.md (секция Pipeline)

Если соответствующий .md ещё не существует, предложи его создать.

Шаг 3. Обнови элементы документации

В коде:

  • •В file header обнови поле Обновлён: на текущую дату в формате YYYY-MM-DD.
  • •Обнови docstrings, если изменились сигнатуры функций, аргументы, возвращаемые значения или исключения.

В связанном .md‑файле (если существует):

  • •Назначение — обнови, если изменилась функциональность.
  • •Входные данные — обнови, если изменились форматы или источники.
  • •Выходные данные — обнови, если изменились форматы или потребители.
  • •Использование — обнови пример запуска и параметры, если они изменились.
  • •Примечания — добавь новые ограничения или важные особенности.

В docs/architecture.md (если нужно):

  • •Обнови секцию Pipeline, если изменились входы/выходы шагов конвейера или их связи.

Шаг 4. Покажи diff и запроси подтверждение

  1. •Сгенерируй сводку изменений в стиле:
bash
Файл: docs/data_preprocessing/normalize.py.md
+ ## Входные данные
+ - **Файл**: `Nero.csv` (было: `data.csv`)
  1. •

    Явно спроси пользователя: Применить изменения? (yes/no)

  2. •

    Только после явного подтверждения внеси изменения в файлы.

Примеры использования

Пример 1 Пользователь: «Я изменил normalize.py, обнови документацию».

  • •Действия:
  • •Обновить header и docstrings в processing/normalize.py, отражая новые аргументы/поведение.
  • •Обновить docs/data_preprocessing/normalize.py.md (назначение, входы/выходы, использование, примечания).
  • •Показать diff и запросить подтверждение.

Пример 2 Пользователь: sync docs

  • •Действия:
  • •Найти все staged файлы через git diff --cached --name-only | grep -E '.(py|mq4|mqh|ipynb)$'.
  • •Для каждого файла найти соответствующий .md/архитектурный документ.
  • •Обновить документацию по правилам выше.
  • •Показать сводный diff и запросить подтверждение перед применением.