https://github.com/mdemyanov/tsn-assistant
AI-ассистент правления товарищества (ТСЖ/СНТ/ЖСК) на базе Claude Code + Gramax
https://github.com/mdemyanov/tsn-assistant
ai-agents claude-code gramax homeowners-association housing property-management russian tsn
Last synced: 14 days ago
JSON representation
AI-ассистент правления товарищества (ТСЖ/СНТ/ЖСК) на базе Claude Code + Gramax
- Host: GitHub
- URL: https://github.com/mdemyanov/tsn-assistant
- Owner: mdemyanov
- License: mit
- Created: 2026-05-25T19:30:17.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-26T09:07:57.000Z (29 days ago)
- Last Synced: 2026-05-26T11:08:23.960Z (29 days ago)
- Topics: ai-agents, claude-code, gramax, homeowners-association, housing, property-management, russian, tsn
- Language: Shell
- Size: 1.49 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# 🏛️ TSN-Assistant — AI-ассистент правления товарищества
База знаний и команда AI-агентов для управления **ТСЖ, СНТ, ОНТ, ЖСК и другими ТСН**. Работает в [Claude Code](https://claude.com/claude-code), хранит все документы в открытом текстовом формате (Markdown + [Gramax](https://gram.ax)), не зависит от облачных платформ для жилищного управления.
**Зачем:**
- 📑 **Один источник правды.** Реестр собственников, договоры, протоколы, тарифы, переписка с УК — в одном репозитории, под версионным контролем, доступны с любого устройства.
- 🤖 **Сложная работа — за минуты, а не за дни.** Анализ договора с УК, расчёт повышения тарифа, подготовка претензии или протокола ОСС — Claude делает черновик, председатель проверяет и подписывает.
- 💰 **Юрист и финансист в подписке.** Вместо разовых консультаций по 5–15 тыс. руб — AI-помощник, который знает ЖК РФ и ФЗ-217, считает варианты «силами правления vs внешний подрядчик», находит судебную практику.
---
## Кому подходит
| Подходит | Не подходит |
|----------|-------------|
| ТСЖ / МКД (многоквартирный дом) | Профессиональные УК с десятками домов в управлении (нужно специализированное ПО) |
| СНТ / ОНТ (садоводческое/огородническое товарищество) | Если в правлении некому открыть терминал — нужен хотя бы один сочувствующий технике |
| ЖСК (жилищно-строительный кооператив) | Если нет готовности приватно платить за подписку Claude (~$20/мес и выше) |
| Другие формы ТСН с правлением | Если нужна автоматизация биллинга и приёма платежей онлайн (это отдельные продукты) |
| От 10 квартир / 20 участков до нескольких сотен помещений | |
Стартовый порог — один человек в правлении, готовый освоить терминал и базовые git-команды. Дальше им может пользоваться кто угодно — Claude разговаривает по-русски.
---
## Что внутри
**8 AI-агентов** работают как команда правления:
| Агент | Роль |
|-------|------|
| `chair` | Виртуальный председатель — оркестратор, главный собеседник |
| `legal` | Юрист (знает ЖК РФ для МКД, ФЗ-217 для СНТ, ГК РФ) |
| `finance` | Финансист (тарифы, бюджет, сметы, биллинг, сравнение КП) |
| `docs` | Документовед (решения, протоколы, претензии по шаблонам) |
| `comms` | Коммуникатор (тексты жителям/членам в инфостиле) |
| `research` | Исследователь (НПА, КП подрядчиков, судебная практика через web) |
| `archivist` | Архивариус (приём PDF/email/фото, раскладка по разделам) |
| `analyst` | Аналитик (сравнения, опции, SWOT, выбор подрядчика) |
**19 slash-команд** покрывают типовые задачи: `/status`, `/delegate`, `/weekly`, `/decision`, `/protocol`, `/claim`, `/contract`, `/message`, `/ingest`, `/insight`, `/review` и прямой вызов каждого агента.
**10 разделов содержимого** в `content/` — паспорт объекта, реестр собственников, правление, общее собрание, финансы, договоры, юридическое, проекты, контакты, архив.
Подробнее: [AGENTS.md](AGENTS.md) (контракт вызова агентов) и [CLAUDE.md](CLAUDE.md) (правила работы AI).
---
## Установка
### 1. Поставить Claude Code
Это CLI-агент от Anthropic, через который работают все AI-функции.
- Установка и подписка: [claude.com/claude-code](https://claude.com/claude-code)
- Без подписки не запустится (см. FAQ ниже про варианты планов).
### 2. Поставить `uv` (менеджер Python-окружений)
Нужен для запуска скрипта валидации содержимого.
**macOS (Homebrew):**
```bash
brew install uv
```
**macOS / Linux (curl):**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
**Windows (WinGet):**
```powershell
winget install --id=astral-sh.uv -e
```
### 3. Настроить git
Без этого `/init` не сможет сделать стартовый коммит.
```bash
git config --global user.email "you@example.com"
git config --global user.name "Имя Фамилия"
```
### 4. Клонировать репозиторий
```bash
git clone https://github.com//tsn-assistant.git mytsn
cd mytsn
```
Замените `` и `mytsn` на актуальные. Имя папки — на ваш вкус (например, `tsn-life2`, `snt-ozero`).
### 5. (Опционально) Поставить Gramax-клиент
Если хотите редактировать содержимое каталога в визуальном WYSIWYG-редакторе, а не в Markdown — поставьте [Gramax](https://gram.ax) (desktop-клиент бесплатный). Без Gramax всё работает — просто читаете/редактируете `.md`-файлы в любом редакторе.
---
## Первый запуск
В корне проекта откройте Claude Code:
```bash
claude
```
И выполните в нём:
```
/init
```
Команда спросит:
1. **Название товарищества** (например, `ТСН «Лайф-2»`)
2. **Код Gramax** (короткий UPPERCASE, например, `LIFE2`)
3. **Краткое описание** каталога (фраза для главной)
4. **Полный адрес**
5. **ФИО председателя/и.о.**
6. **Email редактора** для Gramax
7. **URL нового origin** (можно пропустить, добавите позже через `git remote add origin`)
После Phase 1 запустится Phase 2 — интервью по 8 темам (тип организации, состав правления, основные договоры, реестр и т.д.). Часть пунктов можно отложить — на месте появятся `TODO(/init)`-маркеры, и Claude в следующих сессиях будет напоминать заполнить.
На выходе — полностью персонализированный каталог: ваше название везде, контекст в `CLAUDE.md`, заполнен паспорт объекта, ветки `main` и `private` в git.
---
## Типовые сценарии
### Анализ нового договора с УК
```
/contract Проанализируй договор content/06-contracts/uk/proteya_2026.md
```
Параллельно отрабатывают `legal` (юр.риски, соответствие ЖК РФ) и `finance` (тарифная сетка, выгодность относительно среднерыночных). Получаете заключение с конкретными статьями ЖК РФ, списком рисков и рекомендациями к переговорам.
### Подготовка протокола ОСС
```
/protocol ОСС от 12.05.2026, очно-заочное, 8 вопросов повестки
```
`docs` создаёт черновик протокола по форме, утверждённой Минстроем, с правильной нумерацией решений, кворумом, итогами голосования. Дальше — `/insight` для сохранения ключевых решений и `/decision` для оформления каждого как отдельного решения правления.
### Расчёт повышения тарифа
```
/finance Посчитай, на сколько нужно поднять тариф на содержание,
если ФОТ дворника растёт с 35 → 45 тыс. в месяц, остальное без изменений
```
`finance` показывает: текущая структура тарифа, новая структура, рост в руб/м² и в % для типовой квартиры 60 м². Сравнивает с предельным индексом изменения платы граждан в вашем регионе.
### Претензия за невыполнение работ
```
/claim Подрядчик «Альянслифтсервис» не провёл ТО по графику в марте 2026,
есть акт скрытых дефектов
```
Параллельно: `legal` оформляет требование со ссылками на договор и ст. 723 ГК РФ; `docs` создаёт сам документ претензии с реквизитами и приложениями. Готовый PDF/Word — на печать и в отправку.
### Объявление об отключении воды
```
/message Холодная вода будет отключена 15.05 с 9:00 до 18:00,
причина — плановая замена задвижки на вводе
```
`comms` через скилл `infoinstyle` пишет короткий текст без штампов («доводим до вашего сведения», «приносим извинения за неудобства» — нет), пригодный для подъездов, чата и доски объявлений.
### Делегирование задачи
```
/delegate Проверить акт КС-2 от Альянслифтсервис, срок до пятницы,
ответственный — Иванов
```
Задача попадает в `content/03-board/tasks/`, появляется в `/status` и `/weekly`. Claude напомнит, если срок подходит, а статус не обновлён.
---
## Каталог `content/` — что где лежит
| Раздел | Назначение |
|--------|------------|
| `01-property/` | Паспорт объекта: общая площадь, реестр помещений/участков, оборудование (лифты, ИТП, котельная) |
| `02-owners/` | Реестр собственников/членов, входящие обращения, рассылки |
| `03-board/` | Правление: состав, решения, протоколы заседаний, задачи, журнал активности |
| `04-general-meeting/` | Общее собрание (ОСС для МКД / ОС для СНТ): материалы по годам, процедуры |
| `05-finance/` | Тарифы/взносы, бюджеты, отчёты, фин.анализы, биллинг |
| `06-contracts/` | Договоры с УК, РСО (вода/тепло/свет), обслуживающими организациями |
| `07-legal/` | Шаблоны, претензии, юр.анализы |
| `08-projects/` | Активные и завершённые проекты (капремонт, замена лифтов, благоустройство) |
| `09-contacts/` | Контакты органов власти, контрагентов |
| `10-archive/` | Архив завершённых документов прошлых лет |
Каждый файл — обычный Markdown с frontmatter. Можно открыть в любом редакторе. Можно редактировать через Gramax (см. установку). Можно публиковать в Gramax-каталоге как сайт (закрытый или открытый).
---
## Сколько это стоит
**Главный расход — подписка на Claude Code.** Варианты:
| План | Цена | Кому подходит |
|------|------|---------------|
| Claude Pro | ~$20/мес | Маленькое товарищество (10–30 помещений), 1–2 сессии в неделю |
| Claude Max 5x | ~$100/мес | Среднее (50–150 помещений), регулярная работа |
| Claude Max 20x | ~$200/мес | Большое (200+) либо если AI-ассистент используют несколько членов правления |
| API pay-as-you-go | по факту | Если хотите точный контроль расходов; цены: [anthropic.com/pricing](https://www.anthropic.com/pricing) |
Внутри подписки большинство задач (chair-оркестрация, docs, comms, finance, research) работает без доплат. `chair` использует более дорогую модель Opus для координации, остальные агенты — Sonnet (дешевле в ~5 раз).
**Главное — экономия за рамками LLM-bill.** Одна качественно подготовленная претензия экономит 50–200 тыс. руб. на спорной работе подрядчика. Один правильно посчитанный тариф окупает подписку на год вперёд. Один отказ от ненужной услуги УК (поднятой по принципу «всегда так делали») — на годы.
---
## Безопасность данных
**Что хранится в репозитории:**
- Документы, договоры, протоколы, тарифы, переписка с УК — в открытом виде.
- Контекст товарищества: адрес, ФИО председателя.
**Что НЕ должно попадать в репозиторий:**
- 🔒 Паспортные данные собственников/членов
- 🔒 СНИЛС, ИНН частных лиц без согласия
- 🔒 ФИО + контакты в одном файле без согласия (ПДн по 152-ФЗ)
- 🔒 Пароли, токены, API-ключи (для этого есть `.env`, который игнорируется git)
**Если репозиторий приватный (private на GitHub) —** видят только вы и приглашённые члены правления. Это рекомендация по умолчанию для рабочего каталога.
**Если репозиторий публичный —** видит весь интернет. Это годится для шаблона (как этот) или открытого Handbook товарищества, но не для оперативной работы с реестром и финансами.
Команда `/review` запускается перед merge `private → main` и проверяет каталог на ПДн, секреты и устаревшие данные.
---
## Документация
- **[CLAUDE.md](CLAUDE.md)** — инструкции для Claude: роль, правила, протокол работы, two-way sync, красные линии
- **[AGENTS.md](AGENTS.md)** — каталог ролей, контракт вызова субагентов, self-improvement
- **[.claude/docs/](.claude/docs/)** — внутренние гайды (frontmatter, шаблоны документов, конфиг vault)
- **[docs/lessons-learned.md](docs/lessons-learned.md)** — журнал уроков разработки (append-only)
- **[docs/superpowers/specs/](docs/superpowers/specs/)** — design-спецификации
- **[docs/superpowers/plans/](docs/superpowers/plans/)** — implementation-планы
---
## Контрибьюшен
Шаблон в активном развитии. Любая обратная связь полезна:
- 🐛 **Баг** — [Issues](../../issues) с тегом `bug`
- 💡 **Идея новой команды/агента/скилла** — `feature_request`
- ❓ **Вопрос по использованию** — `usage_question`
- 🔧 **PR** — приветствуются, особенно: новые типы документов, шаблоны для конкретных регионов (с учётом региональных НПА), готовые сценарии для специфики СНТ vs МКД.
Лицензия — **MIT**, см. [LICENSE](LICENSE). Можно использовать в коммерческих и частных проектах, форкать, адаптировать.
---
## FAQ
### А если я не программист?
Освойте 4 команды: `git clone`, `git pull`, `git commit -am "..."`, `git push`. Дальше Claude всё подскажет. На macOS поставится через `brew`, на Windows — через winget. Если терминал пугает в принципе — спросите у соседа-айтишника поставить вам один раз; дальше работа через диалог с Claude по-русски.
### Можно ли использовать без подписки Claude?
Нет. Все AI-функции (агенты, команды) идут через Claude Code, который требует подписку Anthropic. Можно ограниченно посмотреть/потрогать содержимое каталога без Claude — но это уже не «AI-ассистент», а просто папка с документами.
### Что с приватностью данных моих собственников?
См. [Безопасность данных](#безопасность-данных) выше. Коротко: репозиторий ДЕЛАЙТЕ ПРИВАТНЫМ. ПДн в .md-файлы НЕ кладите. Claude обрабатывает данные на серверах Anthropic — это значит, что отправленные в чат данные проходят через США. Не отправляйте в Claude паспорта и не клейте контакты собственников в промпт.
### Подходит ли для УК (управляющей компании)?
Под одно товарищество — да, под десятки домов в управлении — нет. Шаблон рассчитан на правление одного объекта с горизонтальной структурой принятия решений. УК с центральным офисом и стандартизированными процессами лучше подойдёт специализированный 1С/собственный софт.
### Можно ли использовать для маленького товарищества (10 квартир)?
Да, но проще: с большой вероятностью не понадобятся `/protocol` для ОСС каждые две недели и регулярный `/contract`. Используйте `chair` как «карманного юриста и помощника» по точечным вопросам — этого хватит. Подписка Claude Pro окупится с первого же вопроса по ЖК РФ.
### Чем это лучше, чем «спросить ChatGPT»?
ChatGPT не знает контекст вашего товарищества, ваши договоры, ваши тарифы, ваших собственников. Каждый раз начинаете с нуля и переклеиваете контекст. TSN-Assistant — это **постоянный контекст**: Claude видит ваш реестр, ваши решения правления, прошлые протоколы, и работает в них. Плюс — структурированные команды (`/contract`, `/protocol`, `/claim`) дают предсказуемый результат, а не «как карта ляжет».
### Что с обновлениями? Если шаблон обновится — как получить?
Шаблон используется как стартовая точка (Phase 1 init «отвязывает» от template-репо). После init ваш репозиторий живёт независимо. Если хотите подтянуть улучшения шаблона — merge вручную из upstream (`git remote add template ; git fetch template; git merge template/main` с разрешением конфликтов). Автоматического апдейта нет — это сознательное решение: ваш каталог = ваша ответственность за изменения.
---
## Тесты
```bash
bash scripts/test-template.sh # все тесты шаблона
bash scripts/test-init-tsn.sh # smoke-test init.sh
bash scripts/test-validate-content.sh # валидатор содержимого
```
Прогоняются автоматически через `.githooks/` после `bash scripts/install-hooks.sh`.
---
**Made with ❤️ для всех, кому надоело тратить вечера на бесконечную бумажную работу правления.**