split: cleanup migrated artifacts (step 13 — split done)
Removed (now lives in .workshop/, see commits 4608ba9..f8f6f1a there):
- .archive/* (8 archived buffers from 2026-05-05..2026-05-07)
- .brainstorm/* (6 untracked brainstorm buffers — never tracked here, just on disk)
- .wiki/concepts/modulair-rag-brainstorm-trace.md (workshop-meta methodology trace)
- .wiki/raw/naming/* (untracked, naming research clipping)
- .wiki/raw/research/* (modulair, code-review, tokens-economy/, hermes-agent-skills/)
- .claude/skills/meeting-room-promote-brainstorm/SKILL.md (renamed → workshop-promote-brainstorm in workshop repo)
Kept: scenarios/, config/, .wiki/raw/transcripts/, .wiki/entities/, .wiki/concepts/meeting-room-architecture.md (runtime-only rewrite),
.claude/skills/{meeting-room-start-meeting,meeting-room-register-persona}/.
Promoted history of the split decision: .workshop/.wiki/concepts/meeting-room-split.md.
This commit is contained in:
@@ -1,301 +0,0 @@
|
||||
---
|
||||
date: 2026-05-05
|
||||
topic: interns
|
||||
status: design-approved
|
||||
type: domain
|
||||
target_promote: claude-skills
|
||||
sources:
|
||||
- .wiki/raw/research/tokens-economy/2026-05-05-i-gave-claude-code-a-$0.02call-coworker-and-stopped-hitting-pro-limits---here's-the-full-setup.md
|
||||
- .wiki/raw/research/tokens-economy/i-was-burning-through-claude-codes-weekly-limit-in-3-days-here-s-how-i-fixed-it.html
|
||||
- .brainstorm/modulair-rag.md (selected line 134 — Marker/Repomix/Firecrawl specialization hint)
|
||||
- claude-skills/.wiki/concepts/project-discipline-design.md (Rule 4 — permission grant prototype)
|
||||
- claude-skills/.wiki/concepts/skill-vs-plugin.md (bare skill vs plugin decision)
|
||||
- claude-skills/.wiki/concepts/repo-layout.md (skill repo conventions)
|
||||
---
|
||||
|
||||
# Interns — Design Spec
|
||||
|
||||
Каталог специализированных «интернов» — дешёвых LLM/тулзов, которым Claude Code делегирует bulk I/O и предсказуемую генерацию, чтобы экономить твою Anthropic квоту. Доступ — через локальный MCP-сервер. Использование защищено per-session permission grant (зеркало `project-discipline` Rule 4). Каталог расширяется без переписывания скила.
|
||||
|
||||
## Context
|
||||
|
||||
Triggered by Reddit thread (May 2026) и Medium-статьёй того же автора, обе в `.wiki/raw/research/tokens-economy/`. Pattern: `expensive manager (Claude) + cheap intern (DeepSeek/Kimi/Ollama)`. ~23× cheaper end-to-end на summarization задачах, ~125× per-call на bulk read. Без этого OP упирался в weekly Pro limit к среде.
|
||||
|
||||
Локальный сигнал из selected line `.brainstorm/modulair-rag.md:134` — `Marker лучше PDF, Repomix лучше код, Firecrawl лучше JS-сайты` — определил выбор архитектуры (b) специализированных интернов вместо одного universal cheap-LLM.
|
||||
|
||||
## Architecture (three layers)
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ Layer 3 — Policy (skills) │
|
||||
│ using-interns — runtime policy + permission grant │
|
||||
│ setup-interns — one-time install/build/register │
|
||||
│ CLAUDE.md trigger: "delegate to interns when allowed" │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
↑ читает / соблюдает Claude
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ Layer 2 — Runtime (MCP server) │
|
||||
│ .common/lib/interns-mcp/ (Python + FastMCP, stdio) │
|
||||
│ ├── interns_mcp/server.py — MCP entry point │
|
||||
│ ├── interns_mcp/registry.py — load catalog from config │
|
||||
│ ├── interns_mcp/client.py — OpenAI-compatible HTTP │
|
||||
│ ├── interns_mcp/safety.py — always-ask path matcher │
|
||||
│ └── interns_mcp/interns/ — one file per intern impl │
|
||||
│ ├── base.py │
|
||||
│ ├── bulk_text_read.py │
|
||||
│ └── transcript_distill.py │
|
||||
│ Tools exposed: │
|
||||
│ mcp__interns__bulk_text_read │
|
||||
│ mcp__interns__transcript_distill │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
↑ читает on startup
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ Layer 1 — Config (data, no code) │
|
||||
│ .common/config/interns/config.yaml — endpoints + tools │
|
||||
│ .common/secrets/interns.env — API ключи (gitignored) │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
Слои ортогональны. Добавить интерна = одна запись в config + один файл в `interns/`. Skills и setup-flow не трогаются.
|
||||
|
||||
## MVP catalog
|
||||
|
||||
| ID | Описание | Endpoint | Модель | Когда вызывать |
|
||||
|---|---|---|---|---|
|
||||
| `bulk_text_read` | Прочитать N файлов и ответить на вопрос | `ollama_cloud` | `deepseek-v4-flash` | Когда Claude собирался прочесть 3+ файлов или один >400 строк ради контекста |
|
||||
| `transcript_distill` | Сжать session-transcript / лог в action-list | `ollama_cloud` | `deepseek-v4-flash` | Перед обновлением `.wiki/log.md` или summary документации по сессии |
|
||||
|
||||
Оба на одном endpoint и модели — демонстрируют разделение **по классу задачи**, не по провайдеру. Дальнейшие интерны (PDF/web/code) — следующий релиз.
|
||||
|
||||
## Layer 1 — Config
|
||||
|
||||
`.common/config/interns/config.yaml`:
|
||||
|
||||
```yaml
|
||||
endpoints:
|
||||
ollama_cloud:
|
||||
base_url: https://ollama.com/v1
|
||||
api_key_env: OLLAMA_CLOUD_API_KEY
|
||||
request_defaults:
|
||||
extra_body:
|
||||
reasoning: { enabled: false } # обязательно для DeepSeek V4 — иначе max_tokens уходит в silent thinking
|
||||
|
||||
interns:
|
||||
bulk_text_read:
|
||||
description: "Read N files and answer a focused question. Returns concise summary."
|
||||
endpoint: ollama_cloud
|
||||
model: deepseek-v4-flash
|
||||
max_tokens: 4096
|
||||
temperature: 0.2
|
||||
system_prompt: |
|
||||
You are a careful reader. Answer ONLY what the user asks, citing
|
||||
file:line refs. Do not hallucinate file contents. If unsure, say so.
|
||||
|
||||
transcript_distill:
|
||||
description: "Compress a session transcript/log into a structured action-list."
|
||||
endpoint: ollama_cloud
|
||||
model: deepseek-v4-flash
|
||||
max_tokens: 2048
|
||||
temperature: 0.1
|
||||
system_prompt: |
|
||||
Extract action items, decisions, and unresolved questions from the
|
||||
transcript. Output structured markdown sections. Be terse.
|
||||
```
|
||||
|
||||
`.common/secrets/interns.env` (gitignored):
|
||||
|
||||
```dotenv
|
||||
OLLAMA_CLOUD_API_KEY=...
|
||||
```
|
||||
|
||||
Сервер на startup: загружает `.env` через `python-dotenv` → читает `config.yaml` → берёт ключ из `os.environ[api_key_env]`. Если ключа нет — `setup-interns` интерактивно спрашивает и пишет в `.env` (с preview-confirmation gate перед записью).
|
||||
|
||||
## Layer 2 — MCP server
|
||||
|
||||
`.common/lib/interns-mcp/`:
|
||||
|
||||
```
|
||||
interns-mcp/
|
||||
├── pyproject.toml
|
||||
├── README.md
|
||||
├── interns_mcp/
|
||||
│ ├── __init__.py
|
||||
│ ├── server.py — FastMCP app, tool registration
|
||||
│ ├── registry.py — load config.yaml → list of Intern objects
|
||||
│ ├── client.py — OpenAI-compatible HTTP client (per-endpoint, persistent)
|
||||
│ ├── safety.py — always-ask path matcher
|
||||
│ └── interns/
|
||||
│ ├── __init__.py
|
||||
│ ├── base.py — Intern protocol/dataclass
|
||||
│ ├── bulk_text_read.py
|
||||
│ └── transcript_distill.py
|
||||
└── tests/
|
||||
├── test_safety.py — path matcher tests
|
||||
└── test_registry.py
|
||||
```
|
||||
|
||||
**Server contract:**
|
||||
- На startup `registry.load()` проходит config, для каждого интерна делает `@mcp.tool()` с typed signature.
|
||||
- Tool name = `<intern_id>` — Claude harness сформирует `mcp__interns__<id>` (где `interns` — имя сервера в `~/.claude.json`).
|
||||
- Каждый tool принимает `paths: list[str]`, `question: str`, опционально `max_tokens: int`.
|
||||
- **MCP-сервер сам читает файлы из переданных `paths`** — Claude передаёт пути, не содержимое. Это критично для safety: сервер видит пути и применяет always-ask matcher до того как файл уйдёт в endpoint. Если бы Claude слал content, политика могла бы быть обойдена случайно (Claude прочитал `.env`, переслал содержимое — поздно).
|
||||
- Persistent HTTP client per-endpoint — для prefix-cache discount если endpoint его поддерживает (OpenRouter да, Ollama Cloud TBD).
|
||||
|
||||
**Safety enforcement:** `safety.py` проверяет каждый input `path` против always-ask glob-списка. Match → возвращает `BlockedByPolicy` объект с указанием matched-pattern; Claude получает structured ответ и сам спрашивает пользователя. Безопасность на стороне сервера — Claude может «забыть» политику в длинной сессии, MCP не забудет.
|
||||
|
||||
**Cross-platform:** Python 3.11+. Установка `pip install -e .common/lib/interns-mcp/`. Запуск как stdio: `python -m interns_mcp.server`. Без bash/PowerShell зависимостей в hot path.
|
||||
|
||||
## Layer 3 — Skills
|
||||
|
||||
Два скила, по prior art (`setup-context7` + `using-context7`, `setup-projects-meta` + `using-projects-meta`).
|
||||
|
||||
### setup-interns (v0.1.0)
|
||||
|
||||
**When:** «set up interns», «настрой интернов», «install interns», или когда `mcp__interns__*` отсутствуют в сессии где они нужны.
|
||||
|
||||
**Steps:**
|
||||
1. Проверить `.common/lib/interns-mcp/` существует. Если нет — инициализировать pустой через template (TBD: см. open question про source repo).
|
||||
2. `pip install -e .common/lib/interns-mcp/` через активный Python interpreter.
|
||||
3. Прочитать `.common/config/interns/config.yaml`, для каждого `endpoint.<name>.api_key_env` проверить наличие в `.common/secrets/interns.env`. Отсутствующие — спросить интерактивно, preview перед записью, write.
|
||||
4. Зарегистрировать `mcpServers.interns` в `~/.claude.json`:
|
||||
```json
|
||||
"interns": {
|
||||
"command": "python",
|
||||
"args": ["-m", "interns_mcp.server"]
|
||||
}
|
||||
```
|
||||
Путь к Python — через `shutil.which("python")` или `where`/`which` в зависимости от платформы.
|
||||
5. Попросить пользователя перезапустить Claude Code.
|
||||
|
||||
**Migration mode:** detect устаревший layout (например, переезд с `~/.local/interns-mcp/` если когда-то такой был) и предложить миграцию.
|
||||
|
||||
### using-interns (v0.1.0)
|
||||
|
||||
**When:** активируется триггером `delegate to interns when allowed` в `CLAUDE.md`. Также явные команды: «use interns», «delegate this to an intern».
|
||||
|
||||
**Policy:**
|
||||
|
||||
1. **Старт сессии = ask-mode.** Перед первым вызовом `mcp__interns__*` Claude спрашивает:
|
||||
> «Я бы делегировал чтение `<files>` интерну `bulk_text_read` (DeepSeek Flash, ~$0.002 за вызов). Ок?»
|
||||
|
||||
2. **Conversational grant.**
|
||||
- «разреши интернов» / «allow interns» / «use interns» → grant до конца сессии.
|
||||
- «отзови интернов» / «revoke interns» / «делай сам» → возврат в ask-mode.
|
||||
|
||||
3. **Always-ask paths (даже с активным grant'ом).** Полный список:
|
||||
- `**/.env`, `**/.env.*` — environment files со секретами
|
||||
- `**/secrets/**` — каноническая папка секретов (включая `.common/secrets/`)
|
||||
- `**/credentials*` — credentials.json и подобные
|
||||
- `**/*.key` — private keys любого формата
|
||||
- `**/*.pem` — PEM-encoded keys/certs
|
||||
- `**/.ssh/**` — SSH ключи
|
||||
- `**/.aws/credentials`, `**/.aws/config` — AWS credentials
|
||||
- `**/.netrc`, `**/.npmrc`, `**/.pypirc` — registry credentials
|
||||
- **Любой путь, который Claude в текущей сессии прочитал из такого пути и теперь хочет передать интерну** (transitive — нельзя обойти, прочитав файл сам и переслав содержимое).
|
||||
- **Любой intern call с estimated cost >$0.10** (sanity-check, по-конфигу: `tokens × price`).
|
||||
|
||||
Поведение: matched call → MCP возвращает `BlockedByPolicy{path, pattern, reason}`. Claude формулирует пользователю явный вопрос: «Файл `<path>` matched always-ask pattern `<pattern>`. Передавать интерну на endpoint `<endpoint>`?»
|
||||
|
||||
4. **Что НЕ делегируется** (рекомендации в SKILL.md, не enforced):
|
||||
- Архитектурные / design-решения
|
||||
- Debugging — cheap model теряет тонкие баги
|
||||
- Auth / payments / PII / deletion / production data (даже если файлы не в always-ask списке)
|
||||
- Final commit messages, PR descriptions
|
||||
- Финальный текст ответа пользователю
|
||||
|
||||
5. **Конец сессии = reset на ask-mode.** Persistent grant отвергнут как менее безопасный (зеркало Rule 4 `project-discipline`).
|
||||
|
||||
6. **Routing-подсказки** (внутри SKILL.md, чтобы Claude знал когда уместно):
|
||||
- Файл >400 строк и не центральный для редактирования → `bulk_text_read`.
|
||||
- ≥3 файлов нужно прочитать ради контекста → `bulk_text_read`.
|
||||
- Перед обновлением `.wiki/log.md` или session-summary → `transcript_distill`.
|
||||
|
||||
## Bootstrap integration
|
||||
|
||||
`project-bootstrap` v1.5.0 → v1.6.0 (MINOR — capability added):
|
||||
|
||||
- `assets/CLAUDE.md.template` — добавить строку `delegate to interns when allowed` сразу после `follow project discipline`.
|
||||
- `bootstrap-manifest.md` — новые строки `using-interns` + `setup-interns` со своими version'ами.
|
||||
- Step 5 commentary — параграф с объяснением (по образцу commentary для `follow project discipline`).
|
||||
- Idempotent merge — существующие `CLAUDE.md` получат строку при следующем bootstrap (`bootstrap-claude-md-merge.md` уже умеет).
|
||||
|
||||
## Cross-platform
|
||||
|
||||
| Слой | Windows | Linux | macOS |
|
||||
|---|---|---|---|
|
||||
| `.common/lib/interns-mcp/` (Python 3.11+) | ✅ | ✅ | ✅ |
|
||||
| `.common/secrets/interns.env` (`python-dotenv`) | ✅ | ✅ | ✅ |
|
||||
| `setup-interns` install (`python -m pip`) | ✅ | ✅ | ✅ |
|
||||
| MCP registration — путь к Python | `where python` | `which python` | `which python` |
|
||||
| Always-ask matcher (`pathlib.PurePath.match`) | ✅ POSIX-style globs работают везде | ✅ | ✅ |
|
||||
|
||||
`active-platform` скил уже знает что показывать пользователю в каждой платформе для shell команд, никаких дублей.
|
||||
|
||||
## Как добавить нового интерна
|
||||
|
||||
1. **Создать файл** `.common/lib/interns-mcp/interns_mcp/interns/<intern_id>.py`. Шаблон:
|
||||
```python
|
||||
from .base import Intern, InternResponse
|
||||
|
||||
class PdfRead(Intern):
|
||||
id = "pdf_read"
|
||||
description = "Extract text from PDF, including tables."
|
||||
|
||||
def run(self, paths: list[str], question: str, **kwargs) -> InternResponse:
|
||||
# 1. Validate paths existence
|
||||
# 2. Optionally call safety.check(paths) — base.Intern может делать это в __call__
|
||||
# 3. Call external (LLM endpoint via self.client, or local subprocess like Marker)
|
||||
# 4. Return InternResponse(text=..., usage={tokens_in, tokens_out, cost_usd})
|
||||
...
|
||||
```
|
||||
|
||||
2. **Добавить запись** в `.common/config/interns/config.yaml` под `interns:`:
|
||||
```yaml
|
||||
pdf_read:
|
||||
description: "Extract text from PDF (tables, formulas)."
|
||||
endpoint: null # local subprocess, нет endpoint
|
||||
# OR:
|
||||
# endpoint: ollama_cloud
|
||||
# model: deepseek-v4-flash
|
||||
max_tokens: 8192
|
||||
```
|
||||
|
||||
3. **(Если новый endpoint)** — добавить в `endpoints:` секцию + ключ в `interns.env`.
|
||||
|
||||
4. **Зарегистрировать tool в `server.py`** (для MVP — explicit, см. open question про auto-discovery):
|
||||
```python
|
||||
from interns_mcp.interns.pdf_read import PdfRead
|
||||
register_tool(mcp, PdfRead())
|
||||
```
|
||||
|
||||
5. **Restart Claude Code** — новый MCP tool появится как `mcp__interns__pdf_read`.
|
||||
|
||||
6. **Routing-подсказки** в `using-interns/SKILL.md` — добавить строку «если задача XYZ → `pdf_read`».
|
||||
|
||||
7. **(Опц.) Test** в `tests/test_interns_pdf_read.py`. Минимум — проверка happy-path и safety-block для `**/.env*`.
|
||||
|
||||
Если интерн использует local CLI (Marker, Repomix, etc.) вместо LLM API — `endpoint: null` в config, и реализация в `interns/<id>.py` вызывает subprocess.
|
||||
|
||||
## Action items
|
||||
|
||||
- [ ] **`claude-skills`:** разработать и зашипить `setup-interns` (v0.1.0) + `using-interns` (v0.1.0). Bump `project-bootstrap` 1.5.0 → 1.6.0 с обновлением `assets/CLAUDE.md.template`, `bootstrap-manifest`, Step 5 commentary.
|
||||
- [ ] **`.common`:** реализовать `interns-mcp/` MVP с двумя интернами (`bulk_text_read`, `transcript_distill`); написать `README.md` с секцией «Как добавить» (см. выше); pyproject.toml + минимум tests.
|
||||
- [ ] **`projects-meta-mcp`:** мигрировать в `.common/lib/projects-meta-mcp/` для унификации (отложенный backlog item, отдельная задача).
|
||||
- [ ] **`.meeting-room`:** вынести `ollama_cloud.api_key` из `config/config.yaml` в `.common/secrets/interns.env` (или отдельный `.common/secrets/llm-providers.env` если хочется общую точку для всех потребителей этого endpoint — meeting-room runner + interns-mcp + future).
|
||||
|
||||
## Open questions
|
||||
|
||||
- **Source repo для `.common/lib/interns-mcp/`.** Inline в `.common` или отдельный repo на Gitea + git-subtree/submodule? Текущее склонение — inline (это часть `.common`, не самостоятельный продукт).
|
||||
- **Auto-discovery интернов** в `registry.py` (через `pkgutil.iter_modules`) vs explicit `register_tool` в `server.py`. Auto проще для расширения, explicit прозрачнее. Текущее склонение — explicit для MVP.
|
||||
- **Cost tracking.** В первом релизе — нет. Если оботрётся в реальной работе — добавим в `safety.py` per-call estimate из config (`tokens_used × price_per_M`) и блокировку >$X через always-ask механизм.
|
||||
- **Sharing endpoint между meeting-room runner и interns-mcp.** Сейчас `.meeting-room/config/config.yaml` имеет свой `providers.ollama_cloud` с собственным ключом; interns-mcp будет иметь свой в `.common/secrets/interns.env`. Дублирование. Унификация — отдельная задача (см. action item #4).
|
||||
- **Persistent prefix-cache benefit с Ollama Cloud.** Документация Ollama Cloud не подтверждает prefix-cache discount явно (как делает OpenRouter). Если измерения покажут что cache не работает — рассмотреть переключение на OpenRouter как primary endpoint.
|
||||
|
||||
## References
|
||||
|
||||
- [.wiki/raw/research/tokens-economy/2026-05-05-i-gave-claude-code-a-...md](../.wiki/raw/research/tokens-economy/2026-05-05-i-gave-claude-code-a-$0.02call-coworker-and-stopped-hitting-pro-limits---here's-the-full-setup.md) — оригинальный Reddit thread, паттерн + ~125× cost reduction цифры.
|
||||
- [.wiki/raw/research/tokens-economy/i-was-burning-through-...html](../.wiki/raw/research/tokens-economy/i-was-burning-through-claude-codes-weekly-limit-in-3-days-here-s-how-i-fixed-it.html) — Medium-статья от автора Reddit-поста.
|
||||
- `claude-skills/.wiki/concepts/project-discipline-design.md` — Rule 4 (commit-yes-push-no per-session) — прототип permission-grant механизма для `using-interns`.
|
||||
- `claude-skills/.wiki/concepts/skill-vs-plugin.md` — обоснование bare SKILL.md (skills here не нуждаются в plugin format).
|
||||
- `claude-skills/.wiki/concepts/repo-layout.md` — конвенции `claude-skills` repo для скилов.
|
||||
- `.brainstorm/modulair-rag.md:134` — selected line, повлияла на выбор архитектуры (b) специализированных интернов.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,230 +0,0 @@
|
||||
---
|
||||
date: 2026-05-05
|
||||
topic: meeting-room-redesign
|
||||
status: draft
|
||||
type: room-meta
|
||||
promotes_to: .wiki/concepts/meeting-room-architecture.md
|
||||
---
|
||||
|
||||
# Meeting-Room Redesign — design spec
|
||||
|
||||
## 1. Контекст
|
||||
|
||||
`.meeting-room/` сейчас объявлена транзитной зоной (`README.md`: «❌ NO `.tasks`/`.wiki` внутри»). На практике:
|
||||
|
||||
- В `.brainstorm/modulair-rag.md` уже копится содержательный артефакт прошедшей сессии — ему некуда уехать кроме `.archive/` или ручного копирования в глобал.
|
||||
- Реестр персон (`config/config.yaml`) — операционный конфиг без человекочитаемого вики-слоя.
|
||||
- Два типа сырья (pre-loaded research в `source/` и транскрипты в `sessions/`) разнесены по плоским папкам без общей семантики.
|
||||
- В памяти `MEMORY.md` есть открытый todo `project_extend_discipline_for_meeting_room.md` — `project-discipline` молчит про brainstorm-workspace.
|
||||
|
||||
Цель редизайна — достроить комнату как **«микро-проект про методологию совещаний»** без превращения её в полноценный проект с локальным backlog. Опереться на Karpathy LLM Wiki pattern для структуры знаний и на `projects-meta` для связи с глобальным скоупом.
|
||||
|
||||
## 2. Принятые решения
|
||||
|
||||
| # | Развилка | Решение |
|
||||
|---|---|---|
|
||||
| 1 | Wiki/Tasks семантика | **B**: локальный `.wiki/` есть, локальных `.tasks/` нет |
|
||||
| 2 | Folder-миграция | **1 (чистый Karpathy)**: всё «сырое» централизовано в `.wiki/raw/` |
|
||||
| 3 | Промоушен | **C**: локальный `.wiki/concepts/` зарезервирован под room-meta; доменное идёт сразу в глобал, без hop |
|
||||
| 4 | Судьба буфера после промоушена | **(ii)**: `.brainstorm/<topic>.md` → `.archive/<date>-<topic>.md` |
|
||||
| 5 | Skill v1 | `promote-brainstorm`, `start-meeting`, `register-persona` |
|
||||
| 6 | Persona sync | **α**: писать в обе стороны имеет право только `register-persona`; `config.yaml` — SoT |
|
||||
| 7 | Project-discipline | master-only ✅, push-by-permission ✅, semver — N/A, локальные tasks — N/A |
|
||||
| 8 | Spec этого редизайна | живёт здесь, после сборки промоутим своей же системой в `.wiki/concepts/meeting-room-architecture.md` |
|
||||
|
||||
## 3. Целевая структура
|
||||
|
||||
```
|
||||
.meeting-room/
|
||||
├── CLAUDE.md ← корневой контракт работы в комнате (см. §6)
|
||||
├── README.md ← обновлённый, ссылка на CLAUDE.md и .wiki/
|
||||
│
|
||||
├── .wiki/ ← Karpathy-canonical, room-meta only
|
||||
│ ├── CLAUDE.md ← вики-схема (см. §7)
|
||||
│ ├── index.md ← навигация
|
||||
│ ├── overview.md ← что такое meeting-room
|
||||
│ ├── log.md ← хронологический лог: meetings, promotions, persona changes
|
||||
│ ├── raw/
|
||||
│ │ ├── README.md
|
||||
│ │ ├── research/ ← бывший source/: pre-loaded clippings, транскрипты внешних чатов
|
||||
│ │ └── transcripts/ ← бывший sessions/: транскрипты прошедших совещаний
|
||||
│ ├── entities/
|
||||
│ │ ├── persons/ ← карточки persona (генерируются из config.yaml)
|
||||
│ │ └── projects/ ← pointer-карточки для целевых проектов (modulair-rag, books, …)
|
||||
│ ├── concepts/ ← room-meta: методология, ретроспективы, паттерны
|
||||
│ ├── packages/ ← инструменты комнаты (runner, framework, schema)
|
||||
│ └── sources/ ← внешняя литература (Karpathy gist, фасилитация, multi-agent)
|
||||
│
|
||||
├── scenarios/ ← runtime: frontmatter-сценарии для запуска multi-agent
|
||||
├── config/ ← runtime: config.yaml — single source of truth для persona
|
||||
├── .brainstorm/ ← рабочий буфер: черновики, single-agent capture
|
||||
├── .archive/ ← post-promotion: исходники из .brainstorm/, старые сценарии
|
||||
└── .claude/ ← локальные скилы и settings.local.json
|
||||
└── skills/
|
||||
├── meeting-room/
|
||||
│ ├── promote-brainstorm/SKILL.md
|
||||
│ ├── start-meeting/SKILL.md
|
||||
│ └── register-persona/SKILL.md
|
||||
```
|
||||
|
||||
**Различие `.wiki/raw/` ↔ `.brainstorm/`:** raw — immutable, append-only, сырое. `.brainstorm/` — рабочий, редактируемый, чистится промоушеном.
|
||||
|
||||
**Различие `.wiki/concepts/` ↔ `~/projects/.wiki/concepts/`:** локальный — только про **то, как комната работает**. Глобал — доменное содержимое, рождённое в комнате.
|
||||
|
||||
## 4. Lifecycle
|
||||
|
||||
```
|
||||
PRE-MEETING
|
||||
user clip → .wiki/raw/research/<date>-<topic>.md
|
||||
user writes → scenarios/<topic>.md (frontmatter: name, participants, problem)
|
||||
|
||||
MEETING
|
||||
start-meeting <s> → создаёт .wiki/raw/transcripts/<date>-<topic>.md (skeleton)
|
||||
создаёт .brainstorm/<topic>.md (shell)
|
||||
логирует в .wiki/log.md
|
||||
multi-agent run → дописывает транскрипт в .wiki/raw/transcripts/<date>-<topic>.md
|
||||
single-agent CSO → ведёт активный диалог в .brainstorm/<topic>.md
|
||||
|
||||
POST-MEETING
|
||||
promote-brainstorm → парсит .brainstorm/<topic>.md
|
||||
спрашивает: room-meta или domain?
|
||||
room-meta → .wiki/concepts/<topic>.md
|
||||
domain → ~/projects/<proj>/.wiki/concepts/<topic>.md
|
||||
via mcp__projects-meta__knowledge_ingest
|
||||
парсит action-items, создаёт в .tasks/ target-проекта
|
||||
via mcp__projects-meta__tasks_create
|
||||
git mv .brainstorm/<topic>.md → .archive/<date>-<topic>.md
|
||||
логирует в .wiki/log.md
|
||||
```
|
||||
|
||||
## 5. Skills v1
|
||||
|
||||
Каждый скил живёт в `.claude/skills/meeting-room/<name>/SKILL.md`. Триггер-фразы — в frontmatter `description`, чтобы автодиспетчер их подхватывал.
|
||||
|
||||
### 5.1 `meeting-room:promote-brainstorm`
|
||||
|
||||
**Триггеры:** «промоутни брейнсторм», «finalize `<topic>`», «выкати в вики», «promote `<topic>`».
|
||||
|
||||
**Аргумент:** путь к файлу `.brainstorm/<topic>.md` или topic-name.
|
||||
|
||||
**Интерактивные шаги:**
|
||||
1. Прочитать файл, показать summary (1–2 абзаца).
|
||||
2. Спросить: **room-meta** или **domain**?
|
||||
3. Если domain — спросить целевой проект; валидация `~/projects/<proj>/` существует и виден `projects-meta`.
|
||||
4. Распарсить action-items (checkbox `- [ ]`, секции «TODO», «следующие шаги», «next steps»). Показать список, дать отредактировать.
|
||||
|
||||
**Действия (в порядке, atomic-ish):**
|
||||
1. **Промоушен контента:**
|
||||
- room-meta: `Write` → `.wiki/concepts/<topic>.md` с frontmatter (`date`, `source: .brainstorm/<topic>.md`, `status: promoted`).
|
||||
- domain: `mcp__projects-meta__knowledge_ingest` с target-проектом и контентом.
|
||||
2. **Создание тасок:** для каждого action-item — `mcp__projects-meta__tasks_create` с target-проектом, title, description.
|
||||
3. **Архивация:** `git mv .brainstorm/<topic>.md .archive/<YYYY-MM-DD>-<topic>.md`.
|
||||
4. **Лог:** дописать строку в `.wiki/log.md`: `<date> promoted <topic> → <destination>; created N tasks in <proj>`.
|
||||
|
||||
**Failure modes:**
|
||||
- Целевой проект не найден / `projects-meta` недоступен → abort до любых записей.
|
||||
- Промоушен прошёл, `tasks_create` упал на N-м экшене → продолжить, в логе зафиксировать частичный успех; `.brainstorm/` **не** перемещать пока пользователь не подтвердит.
|
||||
- Файла `.brainstorm/<topic>.md` нет → abort, ничего не делать.
|
||||
|
||||
### 5.2 `meeting-room:start-meeting`
|
||||
|
||||
**Триггеры:** «запусти совещание `<topic>`», «start meeting `<scenario>`», «новое совещание `<topic>`».
|
||||
|
||||
**Аргумент:** путь `scenarios/<topic>.md` или topic-name.
|
||||
|
||||
**Шаги:**
|
||||
1. Прочитать `scenarios/<topic>.md`, распарсить YAML frontmatter.
|
||||
2. Валидация:
|
||||
- `name`, `problem` непустые;
|
||||
- все `participants` присутствуют как роли в `config/config.yaml`;
|
||||
- `max_rounds` — целое (если есть).
|
||||
3. Сегодняшняя дата → `<date> = YYYY-MM-DD`.
|
||||
4. Создать `.wiki/raw/transcripts/<date>-<topic>.md` со скелетом (frontmatter: `date`, `scenario: scenarios/<topic>.md`, `participants`, `problem`).
|
||||
5. Создать `.brainstorm/<topic>.md` со skeleton (заголовок, ссылки на сценарий и транскрипт).
|
||||
6. Дописать в `.wiki/log.md`: `<date> started <topic> ({participants})`.
|
||||
7. Вернуть пользователю созданные пути и подсказку, как запустить multi-agent runner.
|
||||
|
||||
**Failure modes:**
|
||||
- Frontmatter невалидный → перечислить ошибки, ничего не создавать.
|
||||
- `.brainstorm/<topic>.md` уже есть → спросить: продолжить (append-skip) или прервать.
|
||||
|
||||
### 5.3 `meeting-room:register-persona`
|
||||
|
||||
**Триггеры:** «добавь персону», «новый агент в комнату», «register persona `<role>`».
|
||||
|
||||
**Интерактивный сбор полей:**
|
||||
- `role-id` (snake_case, уникальный)
|
||||
- `name` (display)
|
||||
- `model`, `provider`, `temperature`, `tools`, `system_prompt`
|
||||
|
||||
**Шаги:**
|
||||
1. Прочитать `config/config.yaml`. Если `roles.<role-id>` существует — спросить: overwrite, abort, новый id.
|
||||
2. Обновить `config.yaml`, **сохраняя YAML-форматирование** (использовать YAML-парсер с round-trip — иначе комментарии и порядок ключей побьются).
|
||||
3. Сгенерировать `.wiki/entities/persons/<role-id>.md` с frontmatter (`role-id`, `model`, `provider`, `source: config/config.yaml`) и body — summary поведения роли, цитата `system_prompt`, ссылка на `config.yaml`.
|
||||
4. Дописать в `.wiki/log.md`: `<date> registered persona <role-id>`.
|
||||
|
||||
**Sync-правило (α):** все автоматические записи в `entities/persons/` идут только через этот скил. Ручные правки разрешены только в `config.yaml`; для пере-генерации карточки — снова `register-persona <role>` (он определит, что роль уже есть, и пере-сгенерирует).
|
||||
|
||||
## 6. Корневой `CLAUDE.md`
|
||||
|
||||
Содержание (outline):
|
||||
|
||||
1. **Идентичность:** «Это `.meeting-room` — workspace для кросс-проектных брейнштормов и круглых столов. Не код-проект.»
|
||||
2. **Семантика артефактов** (короткая шпаргалка из §3 + §4).
|
||||
3. **Жёсткие правила:**
|
||||
- Доменное содержимое **никогда** не оседает в локальном `.wiki/` — всегда в глобал через `projects-meta`.
|
||||
- Локальный `.wiki/` — только room-meta (методология, persona-карточки, лог встреч, ретро).
|
||||
- Локальные `.tasks/` **не создавать** — экшены идут в `.tasks/` целевого проекта через `projects-meta__tasks_create`.
|
||||
- Перед любым предложением tooling/архитектуры — прочитать `.wiki/raw/research/` для текущего топика (закрепляет `feedback_read_source_transcripts.md` из памяти).
|
||||
4. **Триггеры скилов v1:** перечень фраз → скил.
|
||||
5. **Override `project-discipline`:**
|
||||
- master-only ✅
|
||||
- commit freely / push by permission ✅
|
||||
- semver-bump — N/A (нет versioned-артефактов в комнате)
|
||||
- локальные `.tasks/` — N/A (запрещены §6.3)
|
||||
6. **Persona registry:** SoT — `config/config.yaml`. Карточки `.wiki/entities/persons/` — производное, пишется только скилом `register-persona`.
|
||||
|
||||
## 7. `.wiki/CLAUDE.md` (схема)
|
||||
|
||||
Karpathy-канон от `setup-wiki` + meeting-room-специфика:
|
||||
|
||||
- `entities/persons/<role-id>.md` — frontmatter обязателен (`role-id`, `model`, `provider`, `source`); body — summary и цитата system_prompt.
|
||||
- `entities/projects/<proj>.md` — pointer-карточка к глобальному проекту (минимум: путь, краткая роль в контексте комнаты, ссылки на встречи где он фигурировал).
|
||||
- `concepts/<topic>.md` — room-meta: методология, ретро. Frontmatter: `date`, `source: .brainstorm/<topic>.md` (или `.archive/...`).
|
||||
- `raw/research/<date>-<topic>.md` — внешний clipping. Frontmatter: `date`, `source` (URL), `topic`.
|
||||
- `raw/transcripts/<date>-<topic>.md` — транскрипт встречи. Frontmatter: `date`, `scenario`, `participants`.
|
||||
- `log.md` — append-only, формат: `<date> <event-type> <topic> [details]`.
|
||||
|
||||
## 8. Migration plan
|
||||
|
||||
### 8.1 Существующие папки
|
||||
|
||||
| Источник | Назначение | Способ |
|
||||
|---|---|---|
|
||||
| `source/2026-05-03-modulair.md` | `.wiki/raw/research/2026-05-03-modulair.md` | `git mv` |
|
||||
| `source/2026-05-03-code-review.md` | `.wiki/raw/research/2026-05-03-code-review.md` | `git mv` |
|
||||
| `sessions/` (пусто) | `.wiki/raw/transcripts/` (пусто) | создать новую |
|
||||
| `.archive/` (пусто) | остаётся `.archive/` | без изменений |
|
||||
| `scenarios/` | остаётся `scenarios/` | без изменений |
|
||||
| `config/` | остаётся `config/` | без изменений |
|
||||
| `.brainstorm/modulair-rag.md` | особый кейс — см. §8.2 | через `promote-brainstorm` (первый прогон) |
|
||||
| `README.md` | обновить: ссылки на `CLAUDE.md`, `.wiki/`, удалить устаревшее правило «❌ NO `.wiki` внутри» | edit |
|
||||
|
||||
### 8.2 `modulair-rag.md` — особый кейс
|
||||
|
||||
Содержимое — process trace прошедшей single-agent сессии. Финальный design уже лежит в `~/projects/.wiki/concepts/modulair-rag-design.md` (упомянут в шапке самого файла). То есть **доменный layer уже промочен**, что осталось в `.brainstorm/` — это методологический след: «как развивался брейнсторм, какие развилки выбрали, что отвергнуто и почему».
|
||||
|
||||
Это room-meta. Назначение при промоушене — `.wiki/concepts/modulair-rag-brainstorm-trace.md` (или похожее имя). Тасок не порождает (всё доменное уже зафиксировано). Исходник → `.archive/2026-05-05-modulair-rag.md`.
|
||||
|
||||
Использовать как первый end-to-end тест `promote-brainstorm`.
|
||||
|
||||
### 8.3 Spec этого редизайна
|
||||
|
||||
После сборки структуры и v1-скилов — прогнать `meeting-room:promote-brainstorm` на самом этом файле. Назначение: `.wiki/concepts/meeting-room-architecture.md`. Тасок не порождает (план реализации идёт через `writing-plans` отдельно). Исходник → `.archive/2026-05-05-meeting-room-redesign.md`.
|
||||
|
||||
## 9. Открытые вопросы (не блокируют реализацию)
|
||||
|
||||
- **Имя файла промо для `modulair-rag.md`** — `modulair-rag-brainstorm-trace.md` рабочая идея, финальное при первом прогоне.
|
||||
- **Парсер action-items в `promote-brainstorm`** — начнём с regex по `- [ ]` и явным секциям; LLM-парсер только если regex окажется недостаточным.
|
||||
- **Что писать в `entities/projects/<proj>.md`** — формат карточки утрясём после первой реальной встречи post-redesign (сейчас нет данных).
|
||||
- **Расширение `project-discipline` для brainstorm-workspaces** — после стабилизации этой комнаты подать как PR в сам `project-discipline` (закрытие memory-todo `project_extend_discipline_for_meeting_room.md`).
|
||||
@@ -1,178 +0,0 @@
|
||||
# ModulAIr RAG — brainstorm capture
|
||||
|
||||
> Captured 2026-05-05 in single-agent session inside `.meeting-room/`.
|
||||
> Source scenario: `scenarios/modulair.md` (4-agent meeting frontmatter, не запускалось — пользователь предпочёл одного собеседника).
|
||||
> Prior multi-agent transcript: `source/2026-05-03-modulair.md` — там пользователь с другим ассистентом прошёл первый круг и накопил пул tooling-кандидатов (Marker, Repomix, ArchiveBox, Memos, Hermes-agent, и др.).
|
||||
> Mature design: `~/projects/.wiki/concepts/modulair-rag-design.md` — этот файл фиксирует процесс, не финальное решение.
|
||||
|
||||
---
|
||||
|
||||
## Контекст ModulAIr
|
||||
|
||||
ModulAIr — AI-управляемый секвенсор/контроллер для еврорэка на Pico 2 W. Декомпозирован на 6 sub-projects:
|
||||
|
||||
- `modulair-hw` — KiCad PCB (Pico 2 W + DAC + Gate-drivers + ADC + MIDI TRS + audio preamp + eurorack-питание)
|
||||
- `modulair-fw` — прошивка Pico 2 W
|
||||
- `modulair-script` — Teletype-style DSL + интерпретатор
|
||||
- `modulair-mcp` — MCP-мост между LLM и Pico
|
||||
- **`modulair-rag`** — база знаний ◄ предмет этого брейнсторма
|
||||
- `modulair-agent` — Hermes-агент как top-level orchestrator
|
||||
|
||||
**Сквозная архитектурная развилка решена: Variant A — Pico-autonomous, LLM-conductor.** Pico исполняет скрипты sample-accurate, LLM через MCP мутирует паттерны/скрипты, но не сидит в горячем audio-пути. Wi-Fi latency перестаёт быть проблемой.
|
||||
|
||||
## RAG-решения и почему
|
||||
|
||||
### Стратегия — c-tiered (а не плоский vector RAG)
|
||||
|
||||
Чисто вектор-RAG плох на factual-лукапах в синт-домене:
|
||||
- Эмбеддинги "0–8V" / "±5V" / "0V to 10V" близки в семантическом пространстве, но это разные факты
|
||||
- Отрицание ("у X нет Reset-входа") не работает — ретривер тащит чанки где есть "Reset" и "X" рядом
|
||||
- Сравнения требуют JOIN, а не top-k retrieval
|
||||
- Чанкинг ломает таблицы datasheet'ов
|
||||
|
||||
→ **Tier 1** vector (manuals / theory / VCV source / forum threads) — recall-heavy, fuzzy.
|
||||
→ **Tier 2** structured Postgres (module specs из ModularGrid + vendor parsers) — precision-heavy, точные ответы.
|
||||
→ **Tier 3** ручные аннотации (~50 модулей личного рэка, calibration quirks, undocumented behavior).
|
||||
|
||||
### Storage
|
||||
|
||||
- **Postgres (cloud, существующий)** для Tier 2/3. **Не MariaDB:** JSONB для переменной формы jack-списков, pgvector как открытая дверь, recursive CTE + lateral joins зрелее, array-типы родные, MCP/ORM-экосистема Postgres-first.
|
||||
- **LightRAG #2 (новый instance с `working_dir=modulair-rag`)** для Tier 1. Текущий LightRAG-корпус не трогаем — он для других задач.
|
||||
- **Не pgvector unified** — это потребовало бы миграцию текущего LightRAG.
|
||||
- **Не Neo4j** — overkill для тысяч модулей; relations моделируются плоскими таблицами.
|
||||
|
||||
### Scope первой итерации — (II) MVP на full-scrape ModularGrid
|
||||
|
||||
~15k модулей, ~1 месяц. Альтернативы: (I) Top-50 за 2 недели — учиться на знакомом; (III) всё сразу за 1.5–2 мес. Выбрано (II) — компромисс между амбицией и сроками.
|
||||
|
||||
Что меняется при этом скоупе:
|
||||
- **Per-field provenance обязательна** — без неё не отличить достоверный ±5V от LLM-угадки
|
||||
- **LLM-extraction как этап pipeline** — jacks/polarity/range живут в свободном тексте описаний и manual PDF, нужен LLM-проход по 15k
|
||||
- **Validation gates first-class** — voltage standards становятся правилами (audio типично ±5V, anomaly → флаг)
|
||||
|
||||
### Pipeline — immutable layered (L1-L4)
|
||||
|
||||
```
|
||||
L1 raw HTML → MinIO bucket, content-addressed (sha256)
|
||||
L2 DOM extracts → JSONL/run, структурные поля (HP, manufacturer, current_ma)
|
||||
L3 LLM extracts → JSONL/run, jacks/polarity/range из свободного текста
|
||||
L4 Postgres → "current state", собран из L2+L3+Tier-3
|
||||
```
|
||||
|
||||
Зачем слоями: на MVP схема меняется ~5×, LLM-промпт ~10×. Без immutable слоёв каждое изменение = повторный scrape (медленно, rate-limit) + LLM-проход (дорого). С immutable — пере-extract из L2/L3 за минуты.
|
||||
|
||||
### Source стратегия — multi-source
|
||||
|
||||
```
|
||||
1. Vendor-side parsers (top-10):
|
||||
pichenettes/eurorack (canonical Mutable), Make Noise, Intellijel,
|
||||
Doepfer, ALM, Noise Engineering, Befaco, 4ms, Erica, Tiptop
|
||||
2. ModularGrid scrape (HTML, ≤1 RPS, weekly cron)
|
||||
robots.txt allow модули и .json; их официальный API паузнут из-за EU copyright reform
|
||||
3. Tier 3 — ручные аннотации (~50 модулей личного рэка)
|
||||
```
|
||||
|
||||
Не зависимы от ModularGrid одного — фрагильно (DOM может смениться, anti-scrape, юр. неопределённость).
|
||||
|
||||
### Extractor LLM — Ollama Cloud sample first, не Haiku
|
||||
|
||||
Решение: первый прогон через Ollama Cloud (GLM-5.1 / qwen) на golden set, валидация против Haiku 4.5 как benchmark. Если разница <5pp на ключевых метриках — Ollama, бесплатно. Если ≥10pp — Haiku-tiered с Sonnet 4.6 на flagged записях.
|
||||
|
||||
**Golden set protocol** (1–2 дня ручной работы):
|
||||
- ~40 модулей: 20 Mutable (pichenettes/eurorack), 10 Doepfer, 5 Make Noise/Intellijel, 5 edge-case
|
||||
- JSON-эталон per модуль: `{name, direction, signal_type, polarity, range_v_min, range_v_max}`
|
||||
- Метрики/пороги: F1 signal_type ≥0.85, Acc polarity ≥0.85, MAE range ≤0.5V, hallucination ≤5%, miss ≤15%
|
||||
- Артефакты в git: `golden/`, `runs/<model>/`, `metrics/`
|
||||
|
||||
### Provenance — module_facts + materialized consensus view
|
||||
|
||||
```sql
|
||||
module_facts (
|
||||
module_id, field, value JSONB, confidence REAL,
|
||||
source_layer -- 'L2-dom' | 'L3-llm-haiku' | 'L3-llm-sonnet' | 'tier3-manual'
|
||||
source_ref, -- 'scrape-2026-05-05/mutable-rings.json#desc-jacks'
|
||||
scraped_at
|
||||
)
|
||||
```
|
||||
|
||||
Плоские `modules` / `jacks` — materialized view "consensus" поверх highest-confidence values. MCP читает плоский view, валидатор/админка — `module_facts` напрямую. Альтернатива (`<col>_confidence`/`<col>_source` рядом) отвергнута — на 30+ полях шум.
|
||||
|
||||
### Tier 1 corpus — phased
|
||||
|
||||
**Phase 1 (MVP):** ModularGrid descriptions всех 15k (из L1) + top-100 vendor manuals + VCV Rack Fundamental/Library source + 30–50 hand-curated theory статей.
|
||||
**Phase 2 post-MVP:** vendor manuals top-500, YouTube whisper-транскрипты топ-creator'ов, selected forum threads.
|
||||
**Phase 3:** long-tail manuals, full forum scrape с quality filter.
|
||||
|
||||
### Deploy shape — Docker compose, своё железо
|
||||
|
||||
Existing: Postgres, Traefik, Portainer, kicad-mcp (для других sub-projects).
|
||||
|
||||
5 новых контейнеров для modulair-rag:
|
||||
1. `lightrag-modulair` — Tier 1 vector, working_dir отдельный
|
||||
2. `minio` — L1 raw HTML cache, content-addressed
|
||||
3. `modulair-pipeline` — scraper + extractor + loader, cron внутри
|
||||
4. `tier1-converter` — Marker + Repomix + Firecrawl batch jobs
|
||||
5. `modulair-mcp` — MCP-сервер для Hermes (`module_spec`, `concept_search`, `module_compare`, `module_pairs`, `module_text`, `rack_modules`, `provenance`)
|
||||
|
||||
### Orchestration — Hermes, не n8n
|
||||
|
||||
Hermes-agent живёт в отдельном sub-project и через MCP зовёт наш `modulair-mcp` + (будущий) `firmware-mcp` + собственные Python-skills для batch (`run_repomix`, `run_marker`). n8n из плана убран — дублирует Hermes.
|
||||
|
||||
Phases:
|
||||
- Phase 1 — cron внутри контейнеров
|
||||
- Phase 2 — Changedetection.io webhooks → Hermes scheduled-automations
|
||||
- Phase 3 — расширение Hermes skills (multi-source priorisation, feedback-loop из Memos/Obsidian, vendor-парсеры как skills)
|
||||
|
||||
## Что отвергнуто и почему
|
||||
|
||||
| Отвергнуто | Причина |
|
||||
|---|---|
|
||||
| Pure vector RAG (c-flat) | Factual-лукапы галлюцинируют; embeddings не различают voltage ranges |
|
||||
| Postgres + pgvector unified (α) | Заставит мигрировать существующий LightRAG-корпус |
|
||||
| MariaDB | JSONB и pgvector будущего — типпинг-пойнт за Postgres |
|
||||
| Neo4j | Overkill для тысяч модулей; relations плоско моделируются |
|
||||
| n8n | Дублирует Hermes-agent |
|
||||
| markitdown как primary | Marker лучше PDF, Repomix лучше код, Firecrawl лучше JS-сайты |
|
||||
| tree-sitter primary chunking | Repomix даёт structure-aware MD из коробки |
|
||||
| DVC | pg_dump + content-addressed MinIO покрывают provenance |
|
||||
| kicad-mcp в modulair-rag | Out of scope; живёт в modulair-agent / modulair-hw |
|
||||
| ArchiveBox в MVP | Heavy (Docker+Chrome+Node), своя scraper-реализация дешевле для targeted-scrape |
|
||||
|
||||
## Открытые вопросы (не блокируют MVP)
|
||||
|
||||
- Финальный размер golden-set (40 принято; ужесточение MAE до 0.2V для CV-модулей — после первого прогона)
|
||||
- Music theory sources — конкретный список 30–50 статей не зафиксирован (упомянуты Allen Strange, Whitwell, SoS Synth Secrets, Eno strategies)
|
||||
- Phasing для feedback-loop (Memos / Obsidian #feedback) — Phase 2, конкретная реализация позже
|
||||
- Где физически живёт kicad-mcp (host stdio vs Docker) — релевантно для modulair-agent / modulair-hw, не для modulair-rag
|
||||
|
||||
## Tooling из исходного транскрипта 2026-05-03
|
||||
|
||||
Я провалил первый проход — не прочитал транскрипт перед тем как предлагать стэк. Память записана: `feedback_read_source_transcripts.md`. Финальный мерж stack'ов:
|
||||
|
||||
| Категория | Что взято | Что отвергнуто |
|
||||
|---|---|---|
|
||||
| PDF→MD | **Marker** (primary), **LlamaParse** (fallback) | markitdown как primary, Docling (только если Marker не установится) |
|
||||
| Web→MD | **Firecrawl** (batch), **Jina Reader** (одноразовый) | Trafilatura |
|
||||
| Code→MD | **Repomix** | tree-sitter с нуля |
|
||||
| Web archive | **Wallabag** в Phase 2 | ArchiveBox в MVP, Linkwarden, Shiori |
|
||||
| Change detection | **Changedetection.io** в Phase 2 | (alone, без n8n) |
|
||||
| Orchestration | **Hermes-agent** | n8n, Huginn |
|
||||
| Data versioning | `pg_dump` + content-addressed MinIO | DVC |
|
||||
| Feedback loop | **Memos** или **Obsidian** в Phase 2 | (одно из двух) |
|
||||
| Container UI | **Portainer** (existing) | Dockge |
|
||||
| Vector store | **LightRAG** (existing для других, новый instance для modulair) | ChromaDB, Pinecone, GraphRAG |
|
||||
| Algo composition | **music21** — для modulair-agent, не RAG | — |
|
||||
| Embedded DSP | Pure Data + hvcc / Faust — для modulair-fw audio sub-project, не RAG | — |
|
||||
| EDA → MD | **kicad-mcp** существующий, для modulair-hw / modulair-agent | KiCad-CLI / KiBot — out of scope для modulair-rag |
|
||||
|
||||
## Меморики, появившиеся за сессию
|
||||
|
||||
- `feedback_meeting_room_workspace.md` — `.meeting-room` это brainstorm-зона, артефакты идут в `.brainstorm/` или global wiki, не через "transit-zone autopilot"
|
||||
- `project_extend_discipline_for_meeting_room.md` — открытый todo расширить project-discipline под brainstorm-workspaces
|
||||
- `feedback_read_source_transcripts.md` — `.meeting-room/source/<date>-<topic>.md` это pre-loaded user research, читать до предложения стэка
|
||||
|
||||
## Следующие шаги
|
||||
|
||||
1. Брейнсторм per остальным 5 sub-projects (`modulair-hw`, `modulair-fw`, `modulair-script`, `modulair-mcp`, `modulair-agent`)
|
||||
2. Когда RAG-implementation начнётся — поднять структуру репозитория `modulair-rag` где-то в `~/projects/`, скелет compose.yml, `.tasks/STATUS.md` под фактический проект
|
||||
3. Заведение golden-set (1–2 дня ручной работы — это первое что нужно сделать; в MVP это блокирующая зависимость для extractor-валидации)
|
||||
@@ -1,145 +0,0 @@
|
||||
---
|
||||
date: 2026-05-05
|
||||
topic: interns-repo-read
|
||||
status: design-approved
|
||||
type: domain
|
||||
target_promote: claude-skills
|
||||
parent: .archive/2026-05-05-interns.md
|
||||
sources:
|
||||
- .archive/2026-05-05-interns.md (parent — interns архитектура и "How to add" рецепт)
|
||||
- .brainstorm/modulair-rag.md:134 (selected line — Marker/Repomix/Firecrawl, мотивация специализации)
|
||||
---
|
||||
|
||||
# Interns — `repo_read` intern (v0.1.0)
|
||||
|
||||
Расширение каталога `interns-mcp` MVP: добавляет интерн `repo_read`, специализированный на «прочитай эту директорию/репо и ответь на вопрос». Реализуется поверх существующей трёхслойной архитектуры (config / MCP server / skills) без изменений в архитектуре, только новый tool + routing-добавка в `using-interns`.
|
||||
|
||||
## Context
|
||||
|
||||
Из исходного research line: «Repomix лучше код». Интерн оборачивает `repomix` CLI + cheap LLM (`deepseek-v4-flash`) в один MCP tool, чтобы Claude делегировал понимание целой кодовой базы дешёвой модели вместо того чтобы прочитать репо своим Read'ом и сжечь Anthropic-квоту.
|
||||
|
||||
Это первый **tool-wrapping** интерн (subprocess + LLM-call в одной операции) — паттерн под будущие PDF (Marker) и JS-web (Firecrawl) интерны.
|
||||
|
||||
## Decisions
|
||||
|
||||
| # | Решение | Аргумент |
|
||||
|---|---|---|
|
||||
| 1 | Шейп — композитный `repo_read(paths, question) → answer` | Симметрия с `bulk_text_read(paths, question) → answer`. Pure pack не экономит квоту — Claude всё равно читает результат. |
|
||||
| 2 | Tool name `repo_read` (не `repo_qa`, не `code_read`) | Симметрия с `bulk_text_read` (тоже семантически Q&A, но `_read`). Не `code_read` — repomix именно про **директорию целиком**, оставляем `code_read` под будущий grep+cheap-LLM интерн. |
|
||||
| 3 | Overflow при превышении контекста — hard fail с подсказкой | YAGNI. Без авто-compress / map-reduce / smart-selection. Параметр `compress: bool = False` явный, user-controlled. |
|
||||
| 4 | Runtime — `npx repomix@latest` | Zero-config: `setup-interns` только проверяет `node` в PATH. Всегда свежая версия. Первый запуск 5-10s (npm cache populate), потом instant. Pin'ить версию — позже, если будут регрессии. |
|
||||
| 5 | Safety — два слоя: input matcher + transitive `--ignore` | Always-ask matcher проверяет input `paths` (как у остальных interns). Дополнительно: `safety.always_ask_globs()` транслируется в флаги `--ignore` для repomix subprocess'а. Repomix walks recursively, нельзя надеяться что `.gitignore` юзера полный. Защита on-server. |
|
||||
| 6 | Без `include`/`ignore` параметров от Claude | YAGNI: исключение через узкие `paths` + `.gitignore` + always-ask. Если упрёмся — добавим в v0.2.0. |
|
||||
|
||||
## Сигнатура
|
||||
|
||||
```python
|
||||
repo_read(
|
||||
paths: list[str], # директории и/или файлы — targets для repomix
|
||||
question: str, # вопрос
|
||||
compress: bool = False, # repomix --compress (lossy: убирает комменты/whitespace)
|
||||
) -> InternResponse
|
||||
```
|
||||
|
||||
`InternResponse = {text: str, usage: {tokens_in, tokens_out, cost_usd, packed_files: int, packed_tokens: int}}`
|
||||
|
||||
При overflow: вместо `InternResponse` возвращается `BudgetExceededError{tokens, limit, top_files: [...], hint}` — Claude получает structured ответ и переформулирует (узкие paths или `compress=True`).
|
||||
|
||||
## Реализация (`interns_mcp/interns/repo_read.py`)
|
||||
|
||||
```python
|
||||
class RepoRead(Intern):
|
||||
id = "repo_read"
|
||||
|
||||
def run(self, paths, question, compress=False):
|
||||
safety.check_paths(paths) # raise if always-ask
|
||||
ignore_globs = safety.always_ask_globs() # transitive guard
|
||||
|
||||
with tempfile.NamedTemporaryFile(suffix=".xml", delete=False) as packed:
|
||||
args = ["npx", "repomix@latest", *paths,
|
||||
"--output", packed.name, "--style", "xml"]
|
||||
if compress:
|
||||
args.append("--compress")
|
||||
for glob in ignore_globs:
|
||||
args += ["--ignore", glob]
|
||||
subprocess.run(args, check=True, timeout=120)
|
||||
packed_text = Path(packed.name).read_text()
|
||||
|
||||
tokens = count_tokens(packed_text, model=self.config.model)
|
||||
if tokens > self.config.context_budget:
|
||||
return BudgetExceededError(
|
||||
tokens=tokens,
|
||||
limit=self.config.context_budget,
|
||||
top_files=top_files_by_size(packed_text, n=5),
|
||||
hint="use compress=True or narrow paths",
|
||||
)
|
||||
|
||||
return self.client.complete(
|
||||
system=self.config.system_prompt,
|
||||
user=f"# Packed repo\n\n{packed_text}\n\n# Question\n\n{question}",
|
||||
max_tokens=self.config.max_tokens,
|
||||
)
|
||||
```
|
||||
|
||||
## Layer 1 — config (`.common/config/interns/config.yaml`)
|
||||
|
||||
```yaml
|
||||
interns:
|
||||
repo_read:
|
||||
description: "Pack a repo/directory via repomix and answer a focused question via cheap LLM."
|
||||
endpoint: ollama_cloud
|
||||
model: deepseek-v4-flash
|
||||
max_tokens: 4096
|
||||
temperature: 0.2
|
||||
context_budget: 120000 # input-token cap before BudgetExceededError
|
||||
system_prompt: |
|
||||
You are reading a packed code repository. Answer ONLY what the user asks,
|
||||
citing file:line refs from the packed structure. Do not hallucinate file
|
||||
contents. If the answer requires files outside the pack, say so explicitly.
|
||||
```
|
||||
|
||||
## Layer 3 — skill update
|
||||
|
||||
`using-interns/SKILL.md`, секция Routing-подсказки — добавить:
|
||||
|
||||
> - Вопрос про целое репо/директорию (архитектура, «где используется X», «что делает модуль Y», обзор кодбазы) и нужно прочесть >5 файлов кода → `repo_read`.
|
||||
> - `bulk_text_read` vs `repo_read`: первый — пути известны и явные; второй — нужна целая директория без явного выбора файлов.
|
||||
> - Не делегировать `repo_read` для редактирования или отладки конкретного файла — читать файл сам.
|
||||
|
||||
## Setup-side change
|
||||
|
||||
`setup-interns/SKILL.md` — добавить runtime check:
|
||||
|
||||
1. `shutil.which("node")` — если нет, instruct: install Node.js 20+, retry.
|
||||
2. (Опц.) Pre-warm: `npx --yes repomix@latest --version` чтобы первый реальный вызов был быстрым.
|
||||
|
||||
Bump `setup-interns` 0.1.0 → 0.2.0 (MINOR — capability added).
|
||||
|
||||
## Cross-platform
|
||||
|
||||
| Слой | Windows | Linux | macOS |
|
||||
|---|---|---|---|
|
||||
| `npx repomix@latest` | ✅ через node from PATH | ✅ | ✅ |
|
||||
| `tempfile.NamedTemporaryFile` | ✅ | ✅ | ✅ |
|
||||
| Always-ask globs (`PurePath.match`) | ✅ POSIX-style работают везде | ✅ | ✅ |
|
||||
| `subprocess.run` timeout | ✅ | ✅ | ✅ |
|
||||
|
||||
## Action items
|
||||
|
||||
- [ ] **`.common/lib/interns-mcp`**: реализовать `interns_mcp/interns/repo_read.py`, зарегистрировать в `server.py`. Тесты: happy-path, safety-block (`paths=[".env"]`), budget-exceeded. Patch-bump `interns-mcp`.
|
||||
- [ ] **`.common/config/interns/config.yaml`**: добавить запись `repo_read`.
|
||||
- [ ] **`claude-skills/using-interns`**: добавить routing-подсказки в SKILL.md. Bump MINOR.
|
||||
- [ ] **`claude-skills/setup-interns`**: добавить Node-check + (опц.) pre-warm. Bump MINOR.
|
||||
|
||||
## Open questions
|
||||
|
||||
- Реальный context window `deepseek-v4-flash` на Ollama Cloud — проверить эмпирически после первого боевого вызова, скорректировать `context_budget`.
|
||||
- Когда появится 2-3-й tool-wrapping интерн (PDF/web) — выделить общий helper `interns_mcp/tool_wrapper.py` для пары (subprocess + safety-translation + budget-check). Сейчас inline в `repo_read.py`.
|
||||
- Cost-cap >$0.10 (упомянут в parent spec как always-ask trigger) — не реализован. Если появится несколько tool-wrapping interns с разной стоимостью — добавим `safety.check_cost(estimated)` рядом с `check_paths`.
|
||||
|
||||
## References
|
||||
|
||||
- [parent design — `.archive/2026-05-05-interns.md`](../.archive/2026-05-05-interns.md) — архитектура interns-mcp, "How to add an intern" recipe, Action items.
|
||||
- [Repomix](https://github.com/yamadashy/repomix) — JS CLI, упаковывает директорию в один LLM-friendly файл.
|
||||
- `using-interns/SKILL.md` — целевой файл для routing-добавки.
|
||||
- `setup-interns/SKILL.md` — целевой файл для Node-check.
|
||||
@@ -1,236 +0,0 @@
|
||||
---
|
||||
topic: factory-bootstrap
|
||||
started: 2026-05-06
|
||||
participants: [user, claude-cso]
|
||||
status: ready-to-promote
|
||||
problem: >
|
||||
Установка/обновление инфраструктуры software factory (точечные папки в ~/projects/,
|
||||
shared MCP-сервера, скилы) для нового сотрудника должна быть "одной кнопкой" —
|
||||
кросс-платформенной, идемпотентной, нечувствительной к расположению/имени projects-папки,
|
||||
поддерживающей несколько папок проектов на одной машине, частичные/устаревшие установки
|
||||
и разные AI-клиенты (Claude Code / Copilot CLI / Gemini CLI).
|
||||
---
|
||||
|
||||
# Software factory bootstrap — design buffer
|
||||
|
||||
## Контекст и диагноз (как это выглядит сейчас)
|
||||
|
||||
В `~/projects/` есть 6 точечных папок-модулей будущей "ERP":
|
||||
|
||||
| Модуль | Артефакт | Состояние |
|
||||
|---|---|---|
|
||||
| HR / org chart | `.organization/` (roster.md + personas) | частично (CSO/Dev/Analyst в roster, personas/permissions упомянуты но не наполнены) |
|
||||
| Inventory / templates | `.templates/` | `project/` — частично (`python-package`, `with-wiki-tasks`); `agent/`, `report/` — пустые |
|
||||
| Knowledge | `.wiki/` (local Karpathy) | живой |
|
||||
| Knowledge (shared) | `projects-wiki` через `mcp__projects-meta__*` | живой, 13 страниц |
|
||||
| Tasks / PMO | `.tasks/` (local) + `mcp__projects-meta__tasks_*` (shared) | живой, 13 проектов в кэше |
|
||||
| Shared services | `.common/` (lib/scripts/secrets/prompts/config) | живой |
|
||||
| Tooling registry | `claude-skills/` (~20 скилов: 5 setup-*, project-bootstrap, using-*, caveman-*) | живой |
|
||||
| Bus services | `.common/lib/projects-meta-mcp/`, `.common/lib/interns-mcp/` | живые |
|
||||
| Communications | `.meeting-room/` | живой (cwd) |
|
||||
|
||||
**Что не работает для онбординга нового сотрудника:**
|
||||
|
||||
1. Нет orchestrator'а — `setup-*` дёргаются по одному вручную из живого Claude.
|
||||
2. Нет L0 entry point — пока Claude не запущен, ни один setup-* не доступен (chicken-and-egg).
|
||||
3. Нет manifest'а компонентов — версий, зависимостей, health-check'ов нет нигде; `factory.yaml` отсутствует.
|
||||
4. Hardcoded `~/projects/` в путях (например `.common/lib/projects-meta-mcp/dist/sync.js`) — переезд / переименование = ручная починка.
|
||||
5. Multi-vendor (Cursor / Copilot CLI / Gemini CLI): `using-superpowers` уже это учитывает, но `setup-*` пишут только в `~/.claude.json`.
|
||||
6. `meeting-room` / `meeting-room2` — дубликаты, фабрика сама не убрана.
|
||||
7. В кросс-проектных задачах ничего нет про factory bootstrap (релевантные находки: только `web4-phase0-bootstrap` в stostayer.new и `active-platform-eval` в claude-skills). В shared wiki — пусто (`knowledge_search "factory bootstrap onboarding new machine"` → 0 hits).
|
||||
|
||||
## Рекомендация (decided)
|
||||
|
||||
**Создать новую дот-папку `~/projects/.factory/` — отдельный репо, сиблинг `.common/`. Manifest-driven cross-platform installer/updater всей мета-инфраструктуры.**
|
||||
|
||||
Размещение **(a)** выбрано потому, что factory должна работать **до того**, как `.common` склонирован. L0 кладёт `.factory/` первым, дальше уже он ставит всё остальное. Альтернативы (b) `.common/lib/factory/` и (c) `claude-skills/skills/factory/` отвергнуты: обе создают cycle dependency на свои родительские модули.
|
||||
|
||||
### Архитектура — три слоя
|
||||
|
||||
**L0 — Pre-Claude bootstrap** (нативный shell, без runtime-зависимостей). Разбит на два под-слоя:
|
||||
|
||||
**L0a — System bootstrap (toolchain).** Голая машина → готовая к работе.
|
||||
- Системный пакет-менеджер: `winget` (Win11, встроен), `brew` (Mac, `curl … | bash`), `apt`/`dnf`/`pacman` (Linux native).
|
||||
- `git` + `curl` через системный pkg-mgr.
|
||||
- `mise` (бывш. rtx) — single-binary unified runtime manager. Через него `node@lts`, `python@latest`, `go@latest`, `rust` по требованию. Кросс-платформенно, без root, один `mise.toml` на проект. Закрывает nvm/pyenv/goenv одной зависимостью.
|
||||
- Опционально, с интерактивным диалогом (yes/no/skip): Claude Code, Cursor, VS Code, Ollama, Docker Desktop.
|
||||
|
||||
**L0b — Factory bootstrap.** Запускается после L0a.
|
||||
- `bootstrap.ps1` + `bootstrap.sh` — запуск через `iwr … | iex` / `curl … | bash`
|
||||
- Делает только: detect platform → спросить `$PROJECTS_DIR` → clone `.factory/` (gitea) → передать управление в L1
|
||||
- Единое состояние машины: `~/.config/factory/home.toml` со схемой:
|
||||
```toml
|
||||
projects_dir = "C:/Users/vitya/projects"
|
||||
client = "claude-code" # | "copilot-cli" | "gemini-cli"
|
||||
installed_at = "2026-05-06T..."
|
||||
```
|
||||
- Если на машине несколько `projects_dir` — `home.toml` хранит активный, флаг `--projects-dir <path>` переключает.
|
||||
|
||||
**L1 — `factory.yaml` + `factory` CLI** (один скомпилированный бинарь — Go или deno-single-file)
|
||||
- Manifest-схема (черновик):
|
||||
```yaml
|
||||
components:
|
||||
- name: dot-common
|
||||
source: { type: git, url: "{gitea}/.common" }
|
||||
target: "{projects_dir}/.common"
|
||||
health_check: "test -f {target}/scripts/claude-switch.ps1"
|
||||
|
||||
- name: projects-meta-mcp
|
||||
source: { type: git, url: "{gitea}/projects-meta-mcp" }
|
||||
target: "{projects_dir}/.common/lib/projects-meta-mcp"
|
||||
deps: [dot-common]
|
||||
setup_skill: setup-projects-meta # делегируется в L2
|
||||
health_check: "mcp_tool_available mcp__projects-meta__meta_status"
|
||||
|
||||
- name: dot-wiki
|
||||
target: "{projects_dir}/.wiki"
|
||||
deps: [projects-meta-mcp]
|
||||
setup_skill: setup-wiki
|
||||
health_check: "test -f {target}/CLAUDE.md && test -f {target}/index.md"
|
||||
|
||||
- name: claude-skills
|
||||
source: { type: git, url: "{gitea}/claude-skills" }
|
||||
target: "{projects_dir}/claude-skills"
|
||||
post_install: "bash {target}/scripts/install.sh"
|
||||
health_check: "test -d ~/.claude/skills/project-bootstrap"
|
||||
|
||||
# ... .organization, .templates, .meeting-room, dot-tasks, interns-mcp
|
||||
```
|
||||
- Команды:
|
||||
- `factory install` — пройти DAG зависимостей, поставить всё что не прошло health-check
|
||||
- `factory update` — git pull + re-run health-checks
|
||||
- `factory status` — таблица: `name | version | health | deps`
|
||||
- `factory diagnose <name>` — verbose run health-check, печать stderr
|
||||
- Идемпотентность по health-check'у — re-run = no-op.
|
||||
|
||||
**L2 — `setup-*` skills остаются как есть.** `factory` их триггерит через печать инструкции пользователю ("запусти `/setup-projects-meta`") до тех пор, пока не появится программный slash-command-bridge. Когда появится — `setup_skill: <name>` будет вызываться напрямую.
|
||||
|
||||
### Что закрывает каждое требование
|
||||
|
||||
| Требование | Решение |
|
||||
|---|---|
|
||||
| Папка `~/projects` в произвольном месте | `{projects_dir}` substitution в manifest, источник — `~/.config/factory/home.toml` |
|
||||
| Произвольное имя папки | То же; manifest нигде не хардкодит "projects" |
|
||||
| Несколько папок на одной машине | Несколько профилей в `home.toml` (`[profiles.work]`, `[profiles.personal]`); флаг `--profile` |
|
||||
| Cross-platform | L0 — два нативных скрипта; L1 — single-file бинарь под Win/Mac/Linux; L2 — уже работает |
|
||||
| Частичные / устаревшие установки | health_check на каждый компонент; `factory status` показывает дельту; `factory update` чинит |
|
||||
| Multi-vendor (не только Anthropic) | `client` в `home.toml`; manifest-компоненты помечены `clients: [claude-code, copilot-cli]`; не-совместимые скипаются |
|
||||
|
||||
### Anti-recommendations (чего не делать)
|
||||
|
||||
- Один монолитный bash/ps скрипт без manifest'а — за год превратится в legacy.
|
||||
- Python-orchestrator с pip-зависимостями — сам требует bootstrap'а python (тот же chicken-and-egg).
|
||||
- Повторять логику установки в L0 и L2. health_check — single source of truth.
|
||||
- Складывать `factory` в `claude-skills/` — фабрика > tooling; claude-skills должен быть **компонентом** manifest'а, не корнем.
|
||||
|
||||
## Quick wins (параллельные, не блокируют дизайн)
|
||||
|
||||
- Заполнить пустые `.templates/agent/`, `.templates/report/`.
|
||||
- Разобрать duplicate `meeting-room` / `meeting-room2`.
|
||||
- После promotion — заингестить итог в shared wiki как `concepts/factory-bootstrap` (через `knowledge_ingest`).
|
||||
- Завести в `claude-skills/.tasks/` задачу `factory-bootstrap-design` со ссылкой на promoted concept.
|
||||
|
||||
## Открытые вопросы
|
||||
|
||||
### Решённые
|
||||
|
||||
- **Q1 — runtime для L1**: ✅ **Go**. Решено 2026-05-06.
|
||||
- Главные аргументы: размер бинаря (5–10 МБ vs 80–100 МБ Deno), старт ~5 мс, тривиальная кросс-компиляция (включая Win/macOS ARM), `go-git/go-git` снимает зависимость от системного git, cobra даёт shell-completion из коробки.
|
||||
- Стек: Go 1.23+, `go-git/go-git`, `goccy/go-yaml`, `spf13/cobra`, опционально `charmbracelet/lipgloss`. Поставка — pre-built бинари в `.factory/dist/`, скачиваются L0b.
|
||||
- Контраргументы (Deno/Rust/Bun) отброшены: Deno слишком жирный для curl-pipe, Rust learning curve не оправдывает экономию 5 МБ, Bun на Windows ARM ещё не дозрел.
|
||||
|
||||
- **Q6 — toolchain layer в L0**: ✅ **`mise` поверх системного pkg-mgr**. Решено 2026-05-06.
|
||||
- L0a: системный pkg-mgr (winget/brew/apt) → ставит git + curl + mise → mise ставит node/python/go/rust.
|
||||
- Опциональный интерактивный слой: Claude Code, Cursor, VS Code, Ollama, Docker Desktop.
|
||||
- Не отдельные nvm + pyenv + goenv — у каждого свой bootstrap, mise унифицирует.
|
||||
- Не свой пакет-менеджер — winget/brew/apt уже стоят на любой целевой ОС.
|
||||
|
||||
### Открытые
|
||||
|
||||
- **Q2 — где живёт каноничный manifest в production**: в `.factory/factory.yaml` (один на машину) или в shared Gitea с per-machine override? Склоняюсь к "default в `.factory/` репе, override через `~/.config/factory/home.toml#overrides`".
|
||||
- **Q3 — slash-command-bridge для L2**: ждать пока Anthropic / другие вендоры дадут программное API, или поднять свой через MCP-сервер `factory-mcp` (тулы: `factory_install`, `factory_status`)? Второе — независимее, но стоит ещё одного сервера.
|
||||
- **Q4 — версионирование manifest'а**: semver на `factory.yaml` сам? Или per-component версии в pinned-формате `name@v1.2.3`? Last вероятно правильнее, повторяет npm/cargo.
|
||||
- **Q5 — secrets**: где хранятся токены (gitea, ollama, anthropic) в multi-machine setup? Сейчас ad-hoc в `.common/secrets/` и `~/.config/projects-mcp/auth.toml`. factory должен это унифицировать.
|
||||
- **Q7 — access control / discoverability** (deferred to v2): иерархия видимости компонентов фабрики (`public` / `internal` / `secret`) с фильтром при `factory install`. В v0 — все компоненты `public`, secrets живут только в `.common/secrets/` с `.gitignore`. Не блокирует v0.
|
||||
|
||||
- **Q8 — fresh-enterprise bootstrap (greenfield-mode дистрибутива)**: должен ли `factory` уметь поднимать **пустое предприятие** — не клонировать существующие гитеа-репы (clone-mode), а **скаффолдить шесть мета-репо из встроенных templates**?
|
||||
- **Use case:** новый юзер хочет повторить эту ERP-архитектуру у себя — у него есть свой gitea/github namespace, но нет ни `.common/`, ни `.meeting-room/`, ни `.organization/`, ни `.templates/`, ни `claude-skills`-форка, ни `projects-meta-mcp` source-tree. Должен иметь возможность сделать `factory init my-enterprise --git-host https://my-gitea.example.com/myorg` — фабрика создаёт пустые репы, пушит скелеты, потом идёт обычный `factory install`.
|
||||
- **Status:** ✅ нужно поддерживать. Решение принято на field-test'е 2026-05-06; реализация отложена в production-фазу.
|
||||
- **Что уже покрыто greenfield'ом** (повторно использовать как есть): `setup-wiki` (пустая Karpathy-вики), `setup-tasks` (пустой STATUS.md с легендой), `project-bootstrap` (CLAUDE.md/.gitignore/README в любой папке).
|
||||
- **Что не покрыто** (нужны новые скаффолды):
|
||||
1. **Корневые мета-репо** — `.common/`, `.meeting-room/`, `.organization/`, `.templates/` сам, claude-skills-fork. У них нет templates ни в одном из существующих скилов. Сейчас они выросли органически, готовые лежат в `git.kzntsv.site/OpeItcLoc03/`. Для нового предприятия их надо родить.
|
||||
2. `setup-projects-meta` и `setup-interns` ждут готовый source-tree в gitea — нужен **`init`-mode** (форкать из template-репа `factory/templates/...` либо inline-scaffold).
|
||||
- **Архитектурное предложение** — добавить в `factory.yaml` per-component `clone-or-init`-источник:
|
||||
```yaml
|
||||
components:
|
||||
- name: dot-common
|
||||
source:
|
||||
type: clone-or-init
|
||||
url: "{gitea}/common" # сперва пробуем clone
|
||||
template: "{factory}/templates/enterprise/common" # fallback — scaffold + init+push
|
||||
```
|
||||
И команда `factory init <enterprise-name> --git-host <url>` — создаёт пустые репы в namespace юзера, пушит scaffolded skeletons, далее обычный `factory install`.
|
||||
- **Anti-recommendation:** **не** пытаться bootstrap'ить сам git-host (gitea/forgejo/github). Factory ожидает, что писательский git-сервер уже существует и юзер имеет туда write-access. Подъём гитеа — это L0a infra-задача (winget/docker-compose), не L1 (factory).
|
||||
- **Цена:** +1 папка `templates/enterprise/<repo>/` (6 скелетов: `common`, `meeting-room`, `organization`, `templates`, `projects-meta-mcp-skeleton`, `interns-mcp-skeleton`) + per-component поле `source.template:` в manifest. Оценка: ~неделя на скелеты + ~3 дня на `clone-or-init` логику в Go-биноре.
|
||||
- **Зависимости:** не блокирует v0 (clone-mode достаточно для текущего fleet'а из 1 юзера + новой машины). Реализуется параллельно после v0 production-deploy.
|
||||
|
||||
- **Q9 — переименование `claude-skills` → `.skills`** (deferred): репо `claude-skills` стилистически выпадает из dotfile-конвенции флота (`.common/`, `.organization/`, `.meeting-room/`, `.templates/`, `.wiki/`, `.tasks/`) и фиксирует в имени один движок, хотя `superpowers:using-superpowers` уже ссылается на Copilot CLI / Codex / Gemini tool mappings. Озвучено пользователем 2026-05-06 во время field-test'а, явно «но позже».
|
||||
- **Scope переименования:** только git-имя репо в gitea + cloned dir name. Local runtime path `~/.claude/skills/` остаётся (hardcoded в Claude Code). Frontmatter скилов с Claude-specific tool names не трогается — `references/copilot-tools.md` / `codex-tools.md` уже покрывают cross-platform.
|
||||
- **Когда поднимать:** (a) при дизайне `factory.yaml` v0.2 / `templates/enterprise/<repo>/` — естественный момент менять имена; (b) при общем рефакторинге фикстур-репо. Не блокирует v0.
|
||||
|
||||
## v0 plan — live bootstrap нового ноута как field-test
|
||||
|
||||
Stop-condition этого подхода: **не сидеть в чистом дизайне до победного — у пользователя есть свежая машина, на ней проверяем дизайн руками**.
|
||||
|
||||
Алгоритм:
|
||||
1. Узнать ОС нового ноута (Q6 ответ — определяет первую команду L0a).
|
||||
2. Бутстрапить машину пошагово, я директирую каждую команду.
|
||||
3. Каждая выполненная команда логгируется в `.factory/L0/install-log.md` — это сырьё для будущих `bootstrap.ps1` / `bootstrap.sh`.
|
||||
4. После того как factory поднимется на новом ноуте end-to-end (включая `setup-projects-meta`, `setup-interns`, claude-skills install, `.wiki`/`.tasks`/`.organization` clone), формализуем log в скрипты.
|
||||
5. Только после успешного field-test'а садимся за L1 (Go-бинарь и `factory.yaml`).
|
||||
|
||||
**Артефакты этого этапа:**
|
||||
- `.factory/L0/install-log.md` — пошаговый лог команд (на новом ноуте).
|
||||
- Diff между "что я сделал руками" и "что должен делать L0 скрипт" — readme-черновик `.factory/L0/README.md`.
|
||||
- Список найденных gaps (что не получилось / что было неочевидно) — кандидаты в Q-список.
|
||||
|
||||
## Field-test results — 2026-05-06
|
||||
|
||||
End-to-end на новом Win11 ноуте отработал. Полный лог — `.factory/L0/install-log.md` (`git.kzntsv.site/OpeItcLoc03/factory`).
|
||||
|
||||
| Шаг | Что | Статус |
|
||||
|---|---|---|
|
||||
| L0a | mise + системный pkg-mgr (winget) | ✅ first-pass |
|
||||
| L0b | clone `factory`, инициализация `~/.config/factory/home.toml` | ✅ |
|
||||
| 11a | clone `claude-skills`, 21 скил доступен через `Skill` тул | ✅ |
|
||||
| 11b | `claude login` + плагины `superpowers@claude-plugins-official` + `context7@claude-plugins-official` | ✅ (manual, browser-redirect) |
|
||||
| 11c.1 | `setup-interns` — MCP-сервер, секреты в `.common/secrets/interns.env` | ✅ |
|
||||
| 11c.2 | `setup-projects-meta` — repo + wiki clone + MCP entry + initial sync | ✅ idempotent re-run (всё уже было — скил детектил наличие и пошёл по path «update + verify») |
|
||||
| 11c.3 | context7 sanity (`resolve-library-id "react"` → 5 matches) | ✅ |
|
||||
| Фикстуры | `.organization/`, `.templates/`, `.meeting-room/` склонированы | ✅ |
|
||||
|
||||
**Что подтвердилось:**
|
||||
|
||||
1. **Q1 решение (Go для L1) валидно** — текущий L0 на mise+winget хорошо ложится в манифест, runtime-зависимостей сверху не нужно.
|
||||
2. **Q6 решение (mise поверх системного pkg-mgr)** — отработало без сюрпризов. Mise успешно поставил node/python.
|
||||
3. **`setup-projects-meta` idempotency-логика** — корректно различил «fresh install» vs «update+verify». В bootstrap.ps1 повторить эту же pre-check логику.
|
||||
4. **Plugin-route для context7** — правильное решение (legacy `setup-context7` скил не запускался, конфликта нет).
|
||||
|
||||
**Gap'ы / кандидаты для bootstrap-скрипта** (полный список — в `install-log.md` секция «Gaps / questions surfaced during field-test»):
|
||||
|
||||
- 11b принципиально не автоматизируется (требует браузер-redirect / device-code) — bootstrap.ps1 должен **парковаться** здесь и ждать пользователя.
|
||||
- Порядок 11c-скилов критичен: `interns` → `projects-meta` → плагины (или их sanity) → фикстуры. Это контракт скрипта, не выбор пользователя.
|
||||
- Каждый setup-* скил уже идемпотентен — bootstrap может звать их без проверки «надо ли». Но pre-check блок самого скрипта (есть ли git, mise, claude, плагины) обязан быть.
|
||||
|
||||
## Действия после промоушена (план)
|
||||
|
||||
1. `meeting-room-promote-brainstorm factory-bootstrap` →
|
||||
- shared wiki в проекте `factory`: `concepts/factory-bootstrap` (полный дизайн + Q1/Q6/Q8 решения + Q9 deferred + field-test results).
|
||||
- tasks в `factory/.tasks/`:
|
||||
- `factory-bootstrap-script` — status=ready, next_action: «извлечь шаги из install-log.md в `bootstrap.ps1` + `bootstrap.sh`, переиспользовать idempotency-pattern из setup-projects-meta».
|
||||
- `factory-l1-design` — status=blocked-by `factory-bootstrap-script`, next_action: «после успешного скрипта — Go-бинарь + factory.yaml schema (см. Q2/Q4)».
|
||||
- архив: `.archive/2026-05-06-factory-bootstrap.md`.
|
||||
|
||||
## Stop-condition этого буфера
|
||||
|
||||
✅ **Достигнут 2026-05-06.** Q1, Q6, Q8 закрыты; Q2–Q5 явно отложены за v0 (живут в shared wiki после промоушена); Q7, Q9 deferred. Field-test end-to-end успешен. Готов к промоушену.
|
||||
@@ -1,210 +0,0 @@
|
||||
---
|
||||
date: 2026-05-06
|
||||
topic: hermes-skills-rollout
|
||||
status: in-progress
|
||||
type: domain
|
||||
target_promote: claude-skills
|
||||
sources:
|
||||
- .wiki/raw/research/hermes-agent-skills/how-to-create.md
|
||||
- https://hermes-agent.nousresearch.com/docs/user-guide/features/skills
|
||||
- https://hermes-agent.nousresearch.com/docs/guides/work-with-skills
|
||||
- https://www.glukhov.org/ai-systems/hermes/authoring-hermes-skill/
|
||||
- https://github.com/mudrii/hermes-agent-docs/blob/main/skills.md
|
||||
- https://deepwiki.com/NousResearch/hermes-agent/8-skills-system
|
||||
---
|
||||
|
||||
# Hermes Skills Rollout — design buffer
|
||||
|
||||
Раскатить наш `claude-skills` репозиторий на Hermes Agent (Nous Research). Hermes и Claude формально совместимы по `agentskills.io`, но различия по фронтматтеру, раскладке (категории) и body-секциям требуют конвертации, не просто копирования.
|
||||
|
||||
## Context
|
||||
|
||||
Hermes — агент от Nous Research, поддерживает SKILL-формат. Юзер уже клонировал hermes-репу (упоминается в research-файле). У нас 21 скил в `~/projects/claude-skills/skills/`. Нужно понять: формат, что портируется, как поддерживать.
|
||||
|
||||
## Hermes skill format (verified by web)
|
||||
|
||||
**Frontmatter:**
|
||||
|
||||
| Field | Required | Notes |
|
||||
|---|---|---|
|
||||
| `name` | ✅ | lowercase-hyphen |
|
||||
| `description` | ✅ | search-result style; считается по токенам (level-0) |
|
||||
| `version` | ✅ | semver, должен матчить git-tag релиза |
|
||||
| `author`, `license` | ⬜ | typical: MIT |
|
||||
| `platforms` | ⬜ | `[macos, linux, windows]` — silently hides на не-целевой OS |
|
||||
| `metadata.hermes.tags` | ⬜ | indexed labels (e.g. `[devops, backups, shell]`) |
|
||||
| `metadata.hermes.category` | ⬜ | grouping (определяет папку) |
|
||||
| `metadata.hermes.related_skills` | ⬜ | cross-refs |
|
||||
| `metadata.hermes.requires_toolsets` / `requires_tools` | ⬜ | visibility gate |
|
||||
| `metadata.hermes.fallback_for_toolsets` / `fallback_for_tools` | ⬜ | "show only if premium tool absent" |
|
||||
| `metadata.hermes.config` | ⬜ | non-secret prefs (`key,description,default,prompt`) |
|
||||
| `metadata.hermes.required_environment_variables` | ⬜ | `.env` injection в `execute_code`/`terminal` |
|
||||
| `metadata.hermes.required_credential_files` | ⬜ | OAuth/SA mounting |
|
||||
|
||||
**Body sections (recommended outline):**
|
||||
|
||||
1. `## When to Use`
|
||||
2. `## Quick reference`
|
||||
3. `## Procedure`
|
||||
4. `## Pitfalls`
|
||||
5. `## Verification`
|
||||
|
||||
**Layout:**
|
||||
|
||||
```
|
||||
~/.hermes/skills/<category>/<skill-name>/
|
||||
├── SKILL.md (required)
|
||||
├── references/ (long tables, vendor docs — pulled by skill_view(name, file))
|
||||
├── templates/
|
||||
├── scripts/
|
||||
└── assets/
|
||||
```
|
||||
|
||||
Категории — Hermes-стандартный набор: `autonomous-ai-agents, creative, data-science, devops, email, gaming, github, mcp, media, mlops, note-taking, productivity, red-teaming, research, smart-home, social-media, software-development`.
|
||||
|
||||
**Distribution:** публичный git-tap. Юзер делает `hermes skills tap add owner/repo`. Релизы — git-теги, `version` фронтматтера = тег. Hub-публикация — security scan.
|
||||
|
||||
## Design tenet: independence
|
||||
|
||||
**Мы не зависим от Hermes built-in скилов.** Где у нас и у Hermes есть аналог по функции (например llm-wiki), ставим наш. Hermes built-in тоже остаётся, но **наша schema** и наш темп развития — суверенны. Override через `skill_manage` precedence (locally modified bundled skills are preserved).
|
||||
|
||||
Исключение — Hermes-нативные **тулы** (не скилы): `skills_list()`, `cronjob`, `execute_code` и т.п. Это инфраструктура, не «их скил». Используем напрямую.
|
||||
|
||||
## Hermes' inventory (key findings)
|
||||
|
||||
- **`research/llm-wiki`** — встроен (Karpathy). Покрывает init+operate+lint. Использует `SCHEMA.md` (не `.wiki/CLAUDE.md`). Секции `entities/concepts/comparisons/queries` (у нас `entities/concepts/packages/sources`). **`.tasks/` НЕ трогает.** Не drop-in замена нашему — другая schema.
|
||||
- **`mcp/native-mcp`** — встроен MCP-клиент. Внешние сервера через `~/.hermes/config.yaml > mcp_servers.<name>` (stdio/HTTP, env-vars, auto-discovery, `/reload-mcp` команда).
|
||||
- **`skills_list()`** — встроенный progressive disclosure (Level 0). Делает `find-skills` лишним.
|
||||
- Hermes на Linux (`/opt/data/projects` в твоём скриншоте), модель `glm-5.1` (Nous, дешёвая) → caveman экономия токенов не нужна.
|
||||
- **Cron** встроен tool-сом → `using-projects-meta` + cron = автосинк фабричных проектов.
|
||||
|
||||
## Audit (post-discoveries, factory-relevance × Hermes-side fit)
|
||||
|
||||
| Skill | Решение | Reasoning |
|
||||
|---|---|---|
|
||||
| `pulling-before-work` | ✅ **MVP** | универсально, нет аналога |
|
||||
| `using-markitdown` | ✅ **MVP** | через `execute_code` |
|
||||
| `active-platform` | ✅ **MVP** | shell-идиома (Hermes на Linux) |
|
||||
| `project-discipline` | ✅ **MVP** | workflow-правила |
|
||||
| `setup-tasks` / `using-tasks` | ✅ **adapt** | Hermes' llm-wiki `.tasks/` не покрывает |
|
||||
| `setup-wiki` / `using-wiki` | ✅ **adapt** | наша schema, наш контроль (override Hermes built-in llm-wiki через `skill_manage` precedence) |
|
||||
| `setup-projects-meta` (Hermes-flavour) | ✅ **adapt-mandatory** | thin wrapper: бинарь уже в `~/projects/.common/lib/projects-meta-mcp/` (общефабричная инфра), `auth.toml` тоже общий → только yaml-edit `~/.hermes/config.yaml` + `/reload-mcp`. Никаких клонов/билдов на Hermes-стороне |
|
||||
| `using-projects-meta` | ✅ **adapt-mandatory** | тулы auto-injected; политика та же |
|
||||
| `project-bootstrap` | ⚠️ **adapt** | зависит от wiki-fork |
|
||||
| `setup-context7` (Hermes-flavour) | ✅ **adapt-mandatory** | yaml-edit `~/.hermes/config.yaml > mcp_servers.context7`, env API-key, `/reload-mcp`. Тот же паттерн что projects-meta. |
|
||||
| `using-context7` | ✅ **adapt-mandatory** | политика та же, тулы auto-injected |
|
||||
| `caveman`×5 | ❌ skip | Hermes-модель дешёвая, мотив пропадает |
|
||||
| `setup-interns` / `using-interns` | ❌ skip | Hermes сам — «cheap intern» |
|
||||
| `find-skills` | ❌ skip | Hermes имеет `skills_list()` |
|
||||
|
||||
**MVP locked (post-decisions):**
|
||||
- 4 универсальных: `pulling-before-work`, `active-platform`, `project-discipline`, `using-markitdown`
|
||||
- 2 tasks: `setup-tasks`, `using-tasks`
|
||||
- 2 projects-meta: `setup-projects-meta` (Hermes-flavour, thin), `using-projects-meta`
|
||||
- 2 wiki: `setup-wiki`, `using-wiki` (наша schema, override Hermes built-in)
|
||||
- 2 context7: `setup-context7` (Hermes-flavour, thin), `using-context7`
|
||||
- 1 bootstrap: `project-bootstrap` (orchestrator над всем выше; адаптируется последним)
|
||||
|
||||
= **13 скилов**. (Skip: caveman×5, interns×2, find-skills.)
|
||||
|
||||
## In-flight в claude-skills (учитываем)
|
||||
|
||||
- `[setup-projects-meta-token-leak]` ready (security fix — extraheader вместо URL-creds). **Hermes-версия пишется сразу с правильным паттерном.**
|
||||
- `[install-ps1]` ready (PowerShell parity). Для Hermes-installer'а понадобится cross-platform логика.
|
||||
- `[skills-grouping-revisit]` triggers на >30 скилов. С Hermes-добавкой подходим к порогу.
|
||||
|
||||
## Категория-маппинг (черновик)
|
||||
|
||||
- `pulling-before-work`, `project-discipline`, `project-bootstrap`, `active-platform` → `software-development`
|
||||
- `setup-tasks`, `using-tasks` → `productivity`
|
||||
- `using-markitdown` → `productivity` или `research`
|
||||
- `setup-projects-meta`, `using-projects-meta` → `mcp`
|
||||
- `setup-wiki`, `using-wiki` (если порти́руем) → `research`
|
||||
|
||||
## Recommendation: pre-converted `dist-hermes/` + Hermes-side installer
|
||||
|
||||
Это **частные скилы фабрики**. Отметаем tap/Hub/публикацию. Установка — через `skill_manage(action='create')` на стороне Hermes.
|
||||
|
||||
**User-flow:** на фабричной машине `git clone claude-skills` → команда Hermes «установи скилы» → он итерирует, вызывает `skill_manage` per файл → скилы в `~/.hermes/skills/<category>/<name>/`.
|
||||
|
||||
**Архитектура:**
|
||||
|
||||
```
|
||||
claude-skills/
|
||||
├── skills/ ← source-of-truth (Claude-формат)
|
||||
├── dist/ ← .skill архивы для Claude (есть)
|
||||
├── dist-hermes/ ← pre-converted Hermes-tree (committed, NEW)
|
||||
│ ├── productivity/caveman/SKILL.md
|
||||
│ ├── productivity/caveman-commit/SKILL.md
|
||||
│ ├── software-development/pulling-before-work/SKILL.md
|
||||
│ └── meta/claude-skills-installer/SKILL.md ← bootstrap
|
||||
├── scripts/
|
||||
│ ├── build.sh / build.ps1 (есть)
|
||||
│ ├── install.sh (есть)
|
||||
│ └── build-hermes.{sh,py} (NEW — конвертер skills/* → dist-hermes/*)
|
||||
└── hermes-mapping.yaml (NEW — skill → category, replace-rules, skip-list)
|
||||
```
|
||||
|
||||
**Разделение труда:**
|
||||
- **На стороне claude-skills (у нас):** `build-hermes.{sh,py}` читает `skills/*`, применяет `hermes-mapping.yaml` (category, фронтматтер, секции, replace-rules для тулов), пишет в `dist-hermes/`. Запускается локально или в CI на push to master. `dist-hermes/` коммитится в репу.
|
||||
- **На стороне Hermes (на фабрике):** простая итерация по `dist-hermes/<cat>/<name>/` с вызовом `skill_manage(action='create', ...)` per файл. Никакой conversion-логики там нет.
|
||||
|
||||
**Почему dist-hermes коммитится, а не генерится при install:**
|
||||
- Аналог уже committed `dist/.skill` — установившаяся практика в репе.
|
||||
- Hermes не нуждается в Python-окружении / нашем `hermes-mapping.yaml` парсере.
|
||||
- Diff в `dist-hermes/` виден в PR-ах — review-able, не магия.
|
||||
- Bootstrap проще: clone + один Hermes-trigger.
|
||||
|
||||
**Почему не ручной перенос в `~/.hermes/skills/`:**
|
||||
- Анти-дрейф: claude-skills растёт. Через месяц рассинх.
|
||||
- Видимость Claude-измов: конвертер падает / помечает на каждом `mcp__*`/`Read`-рефе — авто-lint совместимости.
|
||||
- Reuse: `agentskills.io` открытый. Тот же скрипт с другим маппингом → Codex / Gemini target позже.
|
||||
|
||||
**Trade-off:** конвертер растёт нелинейно с количеством Claude-измов. Запасной план — `mode: manual` пер-скил в маппинге (готовый Hermes-вариант лежит в `skills/<name>/SKILL.hermes.md`, конвертер копирует as-is, без преобразований).
|
||||
|
||||
## Open questions (live)
|
||||
|
||||
- [x] **Q1.** Maintenance model → **ongoing dual-target** (конвертер + маппинг, регенерим при каждом релизе claude-skills). Anti-drift, видимость Claude-измов, reuse под другие агенты.
|
||||
- [x] **Q2.** ~~Hermes-tap репо / install-script~~ → **`dist-hermes/` (pre-converted, committed) + Hermes-side installer**. Конвертация у нас в claude-skills, установка через `skill_manage(action='create')` на стороне Hermes.
|
||||
- [x] **Q3.** ~~Hub-публикация~~ → **out of scope** (частные скилы).
|
||||
- [x] **Q4.** Форма Hermes-installer'а → **installer-как-Hermes-скил** (`dist-hermes/meta/claude-skills-installer/SKILL.md`). Bootstrap: одна ручная `skill_manage` вызов для самого installer'а, дальше триггер «обнови claude-skills» — он сам итерирует по `dist-hermes/<category>/<name>/` и вызывает `skill_manage(action='create', ...)` per скил. Recursive: installer обновляется вместе со всем остальным через `git pull && trigger update`.
|
||||
- [x] **Q5a.** caveman family → **skip** (Hermes на дешёвой модели, мотив пропадает).
|
||||
- [x] **Q5b.** wiki-fork → **порти́руем наши** (independence tenet — наша schema, не зависим от Hermes built-in).
|
||||
- [x] **Q5c.** context7 → **mandatory adapt** (yaml-edit паттерн).
|
||||
- [x] **Q5d.** projects-meta → **mandatory adapt thin** (бинарь + auth уже общие из `.common`, только yaml-edit).
|
||||
- [x] **Q6.** `🔴 не портируется` → **`mode: skip` в `mapping.yaml` + коммитимый `dist-hermes/SKIPPED.md`** с причиной per skill. Stub-скилы НЕ пишем. Silent отвергнут.
|
||||
- [x] **Q7.** Версионирование → **per-skill semver mirror из claude-skills фронтматтера** (`1.0.0` default если нет). Lock-step с upstream. Bump по `project-discipline` Rule 3.
|
||||
- [x] **Q8.** Layout → **внутри `claude-skills/hermes/`**:
|
||||
- `hermes/mapping.yaml` (skill→category, replace-rules, skip-list, mode)
|
||||
- `hermes/skills/<name>/SKILL.md` (`mode: manual` overrides)
|
||||
- `scripts/build-hermes.{sh,py}` (генератор)
|
||||
- `dist-hermes/<category>/<name>/` (autogenerated, committed)
|
||||
- `dist-hermes/meta/claude-skills-installer/SKILL.md` (recursive bootstrap)
|
||||
- `dist-hermes/SKIPPED.md` (skip-log)
|
||||
|
||||
## Action items
|
||||
|
||||
Все таски в `claude-skills` (это его доменный roadmap).
|
||||
|
||||
- [ ] **`hermes-converter-mvp`** — построить infra и пропустить через неё 4 универсальных скила.
|
||||
- Создать `hermes/mapping.yaml` (схема: per-skill `mode`, `category`, `replace-rules`, `skip-list` + `reason`).
|
||||
- Написать `scripts/build-hermes.{sh,py}` (читает `skills/<name>/SKILL.md` или `hermes/skills/<name>/` для manual, применяет mapping, пишет `dist-hermes/<category>/<name>/`, генерит `dist-hermes/SKIPPED.md`).
|
||||
- Прогнать через 4 universal: `pulling-before-work`, `active-platform`, `project-discipline`, `using-markitdown`.
|
||||
- Закоммитить `dist-hermes/` для этих 4 в репу.
|
||||
- Pre-encode security lessons: extraheader-pattern (от `[setup-projects-meta-token-leak]`) и POSIX-absolute paths (от `[setup-interns-fix-paths]`/`[using-projects-meta-fix-paths]`) — учесть при адаптации.
|
||||
|
||||
- [ ] **`hermes-flavour-mcp-setups`** — переписать `setup-projects-meta` и `setup-context7` в Hermes-flavour (yaml-edit `~/.hermes/config.yaml > mcp_servers`, `/reload-mcp`). Лежат как `mode: manual` в `hermes/skills/setup-projects-meta-hermes/` и `hermes/skills/setup-context7-hermes/`. Pre-check на existing бинарь в `~/projects/.common/lib/projects-meta-mcp/` и `~/.config/projects-mcp/auth.toml`. Применить extraheader-pattern сразу.
|
||||
|
||||
- [ ] **`hermes-installer-skill`** — написать `dist-hermes/meta/claude-skills-installer/SKILL.md` (Hermes loops по `dist-hermes/<category>/<name>/`, вызывает `skill_manage(action='create', ...)` per файл, рекурсивно копирует `references/`/`scripts/`/`templates/`/`assets/`). Документировать bootstrap-процедуру в `claude-skills/README.md` (Linux/Hermes раздел).
|
||||
|
||||
- [ ] **`hermes-mvp-coverage`** — расширить mapping и пропустить через converter оставшиеся 9 MVP-скилов: `setup-tasks`, `using-tasks`, `setup-wiki`, `using-wiki`, `using-projects-meta`, `using-context7`, `project-bootstrap` (адаптируется последним — orchestrator). Smoke-test на фабричной Linux-машине: clone → trigger installer → `hermes skills list` показывает все 13.
|
||||
|
||||
- [ ] (deferred) **`hermes-converter-ci`** — GitHub-Action / Gitea-pipeline на push to master: `build-hermes.{sh,py}` → diff `dist-hermes/` → auto-commit (или PR). Не блокирующее MVP, делается после первой ручной валидации.
|
||||
|
||||
### Discipline pre-requisites (не блокирующие, но желательны до старта hermes-tasks)
|
||||
|
||||
Из код-ревью factory-bootstrap fallout 2026-05-06 — две process-гнили, чинить чтобы новые hermes-таски попали в нормальный flow:
|
||||
|
||||
- [ ] **`tasks-close-normalize-body`** (target: **common**) — `tasks_close` MCP-инструмент сейчас меняет только эмодзи в H2 + врезает HTML-комент, body остаётся stale (`**Status:** ready` + `**Where I stopped:** (not started)` + `**Next action:** <unfulfilled plan>`). Должен normalize: `**Status:** done`, replace `**Where I stopped:**` с close-note narrative, reset `**Next action:**` → `(none — kept until merged)`. Видно во всех 4 closed-tasks в `common/.tasks/STATUS.md` (knowledge-getfrom-meta-alias, knowledge-search-reindex, tasks-aggregate-ready-filter-ux, skip-archived-repos-in-listuserrepos). Требует фикса в `src/tools/tasks.ts` close-handler + tests.
|
||||
|
||||
- [ ] **`using-tasks-close-coverage-gate`** (target: **claude-skills**) — `using-tasks` SKILL должен требовать coverage-проверку acceptance-criteria тестами **перед** вызовом `tasks_close`. Сейчас implementer закрывает по «150/150 tests pass» (existing suite), не покрывая новую логику. Ярко видно на 3 из 4 common-фиксов — acceptance criteria требовали regression-тестов, не написаны (no test for `cached = null` invalidation, no test for `AggregateStatusEnum` validation error, partial test for `archived` filter). Также: после `feat:`/`fix:` коммита skill должен подсказывать «эта работа закрывает таску `<slug>`?» — закрыть `extend-project-discipline-brainstorm-workspaces` и `project-creation-lifecycle-skill` тогда не пропустят (они сейчас оба ⚪ ready несмотря на `215afdd` и `23431c5` shipped).
|
||||
@@ -1,197 +0,0 @@
|
||||
# TDD-критерии: когда можно без
|
||||
|
||||
**Открыто:** 2026-05-07
|
||||
**Status:** brainstorm in progress
|
||||
|
||||
---
|
||||
|
||||
## Постановка (от user)
|
||||
|
||||
Разработка через тесты показывает свою эффективность. Готов внедрить её **почти во все задачи**. Но нужно определить критерии, **когда всё-таки можно без неё** — иначе TDD превращается из инструмента в догму, и каждая задача начинает оплачивать налог TDD даже там, где он не окупается.
|
||||
|
||||
## Ключевая опасность
|
||||
|
||||
«Carve-out для категории» легко превращается в «удобную лазейку». Если правило формулировать как «без TDD можно для exploratory» — каждая задача задним числом оказывается «exploratory». Критерий должен:
|
||||
|
||||
1. Быть **bright-line** (а не «по ощущениям»)
|
||||
2. **Принуждать к моменту осознанного выбора** (не «по умолчанию проскочило»)
|
||||
3. Делать пропуск **видимым** (commit, код-ревью могут это проверить)
|
||||
|
||||
## Открытые вопросы
|
||||
|
||||
- Какой реальный опыт стоит за «TDD показывает эффективность»? — нужен якорь, чтобы критерии калибровались на фактах, а не на мнениях
|
||||
- Где живёт правило: global `~/.claude/CLAUDE.md` (override `superpowers:test-driven-development`) или проектные CLAUDE.md?
|
||||
- Как обеспечить аудит: явная маркировка в commit (`[skip-tdd: <reason>]`), или достаточно ревью diff?
|
||||
|
||||
## Рабочая гипотеза (моя стартовая позиция, до обсуждения)
|
||||
|
||||
**TDD = default.** Carve-outs допустимы **по типу артефакта**, не «по ощущению задачи».
|
||||
|
||||
**Permissive (можно без TDD):**
|
||||
- Untestable surface: CSS/visual polish, layout, config-файлы, документация, prompt-инжиниринг
|
||||
- Throwaway: явный spike/POC с обещанием выкинуть (или переписать с TDD при принятии)
|
||||
- One-shot: миграции данных, ETL backfill, ad-hoc скрипты-однодневки
|
||||
|
||||
**Ironclad (TDD обязателен):**
|
||||
- Bug fixes — всегда начинать с red-теста, воспроизводящего баг (никаких исключений: иначе не убедимся, что починили именно его)
|
||||
- Pure logic, бизнес-правила, branching
|
||||
- Публичные API / контракты
|
||||
- Security, auth/authz, money/dates/identifiers
|
||||
|
||||
**Anti-loophole:**
|
||||
- При пропуске TDD — явная маркировка в commit (`[skip-tdd: visual]`, `[skip-tdd: spike]`)
|
||||
- Spike → если код пошёл в продакшен, заводится тех-долг «backfill tests»
|
||||
|
||||
## Trade-off
|
||||
|
||||
Маркировка `[skip-tdd: ...]` создаёт friction в каждом commit. **Это и есть смысл** — friction блокирует превращение carve-out в норму.
|
||||
|
||||
---
|
||||
|
||||
## Обсуждение
|
||||
|
||||
### Раунд 1 (2026-05-07 утро) — якорный вопрос обратно к user
|
||||
|
||||
Agent не пошёл сразу в формальное multi-persona meeting (нет `scenarios/tdd-criteria.md`, буфер ещё незрел) и не стал перечислять carve-outs в вакууме. Recommend-don't-menu: **остаёмся в single-thread брейнсторме**, потому что буфер сам залочен на якорном вопросе. Personas без factual anchor сгенерят гипотетику, потратят раунды.
|
||||
|
||||
Запрошено у user: какой проект / тип артефакта; что было до TDD vs после; контр-кейс, где TDD замедлил.
|
||||
|
||||
### Раунд 2 (2026-05-07) — user указал на наблюдаемые симптомы + контекст «не все используют Claude»
|
||||
|
||||
User: «modules-db и pilonuxt буксуют, полны багов, не могут уйти в прод. Посмотри, в каких проектах TDD использовали в общих тасках» + «у нас есть claude-skills. Не все используют Клода».
|
||||
|
||||
Из второго: **правило не должно быть Claude-specific.** Локация в `~/.claude/CLAUDE.md` (как было предложено в раунде 4) — ошибка. Правило — методология, не агент-инструкция.
|
||||
|
||||
### Раунд 3 (2026-05-07) — cross-project research через projects-meta
|
||||
|
||||
Agent выполнил Step 0 freshness gate (`meta_status` → 5.4h cache → `node sync.js` → 13 проектов, 0 errors, freshly synced 2026-05-07T03:27Z), затем `tasks_search "tdd"` / `"test"` + `tasks_get` по `modules-db`, `pilonuxt`, `books`.
|
||||
|
||||
**Поиск «tdd»**: 0 хитов в активных задачах ни одного проекта. **Поиск «test»**: 1 хит (`claude-skills/hermes-mvp-coverage` — про smoke-test, не TDD).
|
||||
|
||||
**books** (контрастный кейс — фичи систематически закрываются, активные двигаются):
|
||||
- `books-ops-mcp` Phase 2 (CLOSED, прод): «**3 unit-tested helpers (TDD)** + integration tests via docker-compose + smoke 7/7». Helpers — `enforceLimit`, `checkSql`, `capPayload` (defence-in-depth для read-only SQL).
|
||||
- `books-analyst-mcp` Phase 1.1: после real-API smoke вылез баг handler-обёртки → **сначала написан `handler-body.test.js` 10 кейсов через `Configuration.fetchApi`-перехват, потом fix** (`de3360c`). Классический red-test для bug-fix.
|
||||
- `analyst-report-formats` (CLOSED): `_test/` 11 unit-тестов для 5 pluggable formatters.
|
||||
- Закрытые крупные фичи: `pluggable-scheduler` Phase 1-9, `agenda-admin-ui`, `registry-gc`, `books-analyst-mcp`. Активный затык — `ozon-knowledge-base-ingest` (anti-bot, не баги кода).
|
||||
|
||||
**modules-db** (буксует):
|
||||
- `ai-fill`: «❌ Phase 7 (Testing) — unit tests, smoke test» — тесты отложены ПОСЛЕ Phases 1-6. Test-after.
|
||||
- `fill-fields-ai-sdk-migration`: SDK v5→v6 signature change, **endpoint висит несколько дней без contract-теста**.
|
||||
- `entity-drawer-refactor`: vitest упомянут в shell-setup, но в Progress нет тестовых артефактов; Playwright smoke в Phase 5 (после refactor).
|
||||
- `hydration-mismatch` шумит на всех страницах после миграции.
|
||||
|
||||
**pilonuxt** (буксует):
|
||||
- 2 задачи в кэше. `design-system-cleanup`: битые hex'ы, font preload — нет тестов и нечем их писать. `snolla-contract-refresh` (CLOSED): пересборка клиента к внешнему контракту, без тестов; открытый item — «`pnpm build` зависает».
|
||||
|
||||
### Раунд 4 (2026-05-07) — user сообщил n=1 + увольнение автора + «реши сам»
|
||||
|
||||
User: «Это программист выбирал, я не настаивал. Теперь уже не узнаем, он уволился. Давай ты сам порешаешь».
|
||||
|
||||
Что это меняет:
|
||||
- Нельзя говорить «коллективный опыт books validates TDD» — n=1, автор недоступен, мотивация неизвестна.
|
||||
- Опираться на: (а) **observable evidence** — где TDD применялся, фичи закрылись; где не применялся (modules-db/pilonuxt), фичи буксуют. (б) **First principles** — где TDD физически дешевле/дороже исходя из природы артефакта.
|
||||
- Урок «программист уволился — его конвенции исчезли»: **правило должно быть кодифицировано вне головы конкретного человека**. Поэтому промоушен в общий artefakt — не опционально.
|
||||
|
||||
Agent в этом раунде предложил `~/.claude/CLAUDE.md` как location → корректно отвергнуто на следующем раунде user-ом (Claude-only, не для всех агентов). Промежуточная попытка fallback'а на «shared agent-agnostic wiki via `projects-meta knowledge_ingest`» тоже устарела — финальная локация в раунде 5.
|
||||
|
||||
### Раунд 5 (2026-05-07) — user поправил локацию: claude-skills, не правила
|
||||
|
||||
User: «У нас есть проект `claude-skills`. Изучи принципы. Туда его, а не в правила».
|
||||
|
||||
Agent изучил `~/projects/claude-skills/`: `README.md`, `.wiki/concepts/repo-layout.md`, `skills/project-discipline/SKILL.md`, `skills/recommend-dont-menu/SKILL.md`, `hermes/mapping.yaml`. Принципы:
|
||||
|
||||
- `skills/<name>/` — source of truth. `SKILL.md` с frontmatter (`name`, `version`, `description`).
|
||||
- `dist/<name>.skill` — committed архивы (для Claude). `dist-hermes/<category>/<name>/` — committed pre-converted Hermes-flavour tree.
|
||||
- `hermes/mapping.yaml` — required entry per skill. Modes: `auto` (apply replace-rules), `manual` (Hermes-flavour rewrite), `skip`, `pending`.
|
||||
- Конкретный прецедент `recommend-dont-menu`: rule переехал из `~/.claude/CLAUDE.md` в skill ровно по причине «Moving to a skill makes it portable: cross-agent compatibility is explicit».
|
||||
|
||||
→ TDD-criteria — это **policy skill**, его место в `claude-skills`. Локация раунда 4 (`~/.claude/CLAUDE.md`) была повторением старой ошибки; правка применена в секции «Локация правила» ниже.
|
||||
|
||||
### Раунд 6 (2026-05-07) — user сформулировал самый сильный аргумент: TDD как защита от vandalism
|
||||
|
||||
User: «возмущает, что несколько раз наблюдал, как эти уроды стирали целые простыни чужого кода и рапортовали "смотри, как я пиздато сделал, тут не получалось, но я почистил и стало пиздато". А потом по гиту собирали назад. Был бы код покрыт тестами — хуй бы они так сделали».
|
||||
|
||||
**Это аргумент про существование поведения, не про корректность.** Все мои четыре Ironclad-аргумента (bug fix, pure logic, third-party, security/money) — про защиту от *неправильного* поведения. Этот — про защиту от *удалённого* поведения.
|
||||
|
||||
Механизм: без теста контракт кода = «лежит в repo» (артефакт, не инвариант). Агент видит «грязно» → удаляет → коммитит «стало чище» → success-отчёт. Что код реализовывал реальное поведение — **нигде не записано кроме самого кода**, которого теперь нет. С тестом контракт = «X(Y)=Z» (инвариант). Удалить X = test fails = success невозможен. **Тест — адвокат поведения, когда поведения уже нет.**
|
||||
|
||||
Для контекста разработки с участием агентов (Claude, ChatGPT, будущих незнакомых) это означает: TDD-default — не «good practice», это **единственная защита от well-intentioned destruction**.
|
||||
|
||||
**Что меняется в Final decision:**
|
||||
|
||||
- Структура 4 Ironclad + 4 Permissive **сохраняется** (bright-line требует binary properties; этот аргумент — rationale, не критерий).
|
||||
- Permissive переформулируется **честнее**: не «зоны где TDD не нужен», а **«зоны принятого риска агентской дезорганизации»**. Ты явно соглашаешься: здесь агент может прибрать-удалить без signal-а, и ты accept-ишь recovery cost (eyeball-проверка для visual, throwaway по контракту для spike, one-shot после run-а уже неактуален, wrapper легко реконструировать).
|
||||
- В Ironclad: recovery cost > defending cost, поэтому signal обязателен.
|
||||
- В Final decision добавляется секция «Почему TDD-default — контракт, а не качество» как ведущий rationale.
|
||||
- В будущем `claude-skills/skills/tdd-criteria/SKILL.md` это становится ключевым «Why this exists».
|
||||
|
||||
---
|
||||
|
||||
## Final decision (2026-05-07)
|
||||
|
||||
**TDD = default. Bright-line carve-outs — четыре, по природе артефакта.**
|
||||
|
||||
### Почему TDD-default — это контракт, а не качество (ведущий rationale)
|
||||
|
||||
В контексте разработки с участием агентов (Claude, ChatGPT, нанятые программисты приходящие и уходящие) тест выполняет **функцию, которой нет ни у документации, ни у код-ревью**: он делает поведение **инвариантом**, а не артефактом.
|
||||
|
||||
- Без теста контракт = «код лежит в repo». Агент видит «грязно» → удаляет → коммитит «стало чище» → success-отчёт. Поведение **существовало только в самом коде**, который теперь удалён. Восстановление — `git revert` после того как заметили; до тех пор silent regression.
|
||||
- С тестом контракт = «X(Y)=Z». Удалить X → test fails → pipeline red → success невозможен. **Тест — адвокат поведения в момент, когда поведения уже нет.**
|
||||
|
||||
Этот аргумент сильнее остальных четырёх (bug fix / pure logic / contract / security) потому что они про *корректность* поведения, а этот — про *существование*. Без него классические аргументы решают локальную задачу, но оставляют уязвимость к well-intentioned destruction. Он — основа TDD-default; всё остальное — частные случаи.
|
||||
|
||||
### Permissive (зоны принятого риска агентской дезорганизации, skip + маркер)
|
||||
|
||||
Не «зоны где TDD не нужен», а **зоны где принимаешь риск silent deletion и accept-ишь recovery cost**. Вход в зону — явный, маркируется в commit subject.
|
||||
|
||||
| Категория | Триггер | Маркер | Recovery cost |
|
||||
|---|---|---|---|
|
||||
| Visual / config | CSS, layout, design tokens, `.env.example`, prompt-тексты, wiki, README | `[skip-tdd: visual]` | Eyeball на следующем render-е |
|
||||
| Spike | Explicit POC с обещанием выкинуть | `[skip-tdd: spike]` | Throwaway по контракту, deletion = no problem |
|
||||
| One-shot | Миграции данных, ETL backfill, скрипты-однодневки | `[skip-tdd: oneshot]` | После run-а уже неактуален |
|
||||
| Wrapper | Транзитный код без логики (re-export, glue ≤10 строк) | `[skip-tdd: wrapper]` | Reconstruct cost ≈ delete cost |
|
||||
|
||||
### Ironclad (без исключений, без маркера — TDD обязателен)
|
||||
|
||||
1. **Bug fixes** — red-test, воспроизводящий баг, **до** fix-а. Подтверждено `books-analyst-mcp` `handler-body.test.js` 10 кейсов через `Configuration.fetchApi`-перехват **до** `de3360c`.
|
||||
2. **Pure logic с bounded inputs** — helpers, parsers, validators, formatters, любая `(known input) → (known output)` без I/O. Подтверждено `books-ops-mcp` Phase 2: `enforceLimit/checkSql/capPayload`.
|
||||
3. **Third-party contract consumption** — SDK clients, API-обёртки. **Контр-кейс прямо сейчас**: `modules-db/fill-fields-ai-sdk-migration` висит после AI SDK v5→v6 без contract-теста.
|
||||
4. **Security / auth / money / identifiers** — без изменений vs стартовой гипотезы.
|
||||
|
||||
### Anti-loophole
|
||||
|
||||
- **Skip без категории не существует.** Категория — одна из четырёх явных, не «других причин». Без маркера — нарушение.
|
||||
- **Spike survivor**: если spike-код пережил merge в master → тем же merge-commit создаётся `[backfill-tests-<slug>]` task в `.tasks/STATUS.md`. Иначе категория «spike» становится loophole.
|
||||
- Friction чисто социальная (видна в `git log --oneline`); pre-commit hook опционален и обсуждается отдельно.
|
||||
|
||||
### Локация правила
|
||||
|
||||
**Корректировка после раунда 5 (user поправил).**
|
||||
|
||||
Правило живёт **как skill** в `~/projects/claude-skills/skills/tdd-criteria/SKILL.md`, не в `~/.claude/CLAUDE.md` (Claude-only) и не в `projects-wiki/concepts/` (пассивный artefact).
|
||||
|
||||
Обоснование:
|
||||
- `claude-skills` — единственный механизм с встроенным cross-agent rollout: `install.sh` → `~/.claude/skills/`, `build-hermes.py` + `mapping.yaml` → `dist-hermes/<category>/<name>/`. Любой будущий агент получает свой target.
|
||||
- Прямой прецедент — `recommend-dont-menu`. Цитата из его SKILL.md: «Original rule lived in `~/.claude/CLAUDE.md` as a per-machine instruction. Moving to a skill makes it portable: cross-agent compatibility is explicit.» Ровно тот же refactoring, который user уже один раз делал.
|
||||
- Skill — активный trigger-driven artefact: description-frontmatter + триггер-фразы → pull-механизм. Concept-страница в wiki — push-механизм («помни читать»), который не работает для cross-cutting policy.
|
||||
|
||||
Структура skill:
|
||||
- `name: tdd-criteria`, `version: 0.1.0`, multi-line `description:` с явными триггер-фразами
|
||||
- секции: «When this runs» (trigger phrases) → «Default mode (TDD-by-default)» → «Permissive carve-outs (4 категории + маркеры)» → «Ironclad (4 правила)» → «Anti-loophole» → «Out of scope» → «Why this exists»
|
||||
- mapping.yaml entry: вероятно `mode: auto` без replace-rules (правило агент-агностично — pure policy, не упоминает Claude-tool-refs); category `software-development`. Пометить `pending` если хочется отдельный Hermes-аудит.
|
||||
|
||||
Проектные CLAUDE.md могут **расширять** Permissive (например `karu` — проект чистого CSS) или **расширять** Ironclad через локальный override. **Не могут сужать Ironclad.** Триггер-line в шаблоне `project-bootstrap` **не добавляем автоматически** — skill активируется по description при релевантных запросах, форсированный pull в каждый проект — отдельное решение.
|
||||
|
||||
### Trade-off (зафиксирован честно)
|
||||
|
||||
- **Supportive evidence — n=1**. books мог быть продуктивнее по причинам не связанным с TDD. Но направление эффекта (где помогало vs где не применялось) согласуется с first principles, инверсия маловероятна.
|
||||
- **Friction в UI-итерациях**. `[skip-tdd: visual]` 50 раз подряд при `web-design-system` — раздражает. Это и есть замысел: friction — fence, не bug. Снимать не раньше 2 недель usage.
|
||||
- **Альтернатива** «не кодифицировать вовсе» отвергнута: именно «не кодифицировано» привело к ситуации, что после ухода автора в books невозможно реконструировать его критерий. Уволенный человек — argument *за* кодификацию, не *против*.
|
||||
|
||||
---
|
||||
|
||||
## Где остановились (2026-05-07)
|
||||
|
||||
- Final decision выше — готово к промоушену.
|
||||
- Status: ready-for-promotion.
|
||||
- **Resume:** запустить `meeting-room-promote-brainstorm` → routing: `domain` → target project: **`claude-skills`** (не `projects-wiki` через knowledge_ingest, не `~/.claude/CLAUDE.md`). Действие промоушена: (а) написать `~/projects/claude-skills/skills/tdd-criteria/SKILL.md` напрямую файлом + (б) добавить entry в `hermes/mapping.yaml` + (в) `bash scripts/install.sh tdd-criteria` + `bash scripts/build.sh tdd-criteria` + `python scripts/build-hermes.py` + (г) commit (push по grant-у). Импл-таски в `claude-skills/.tasks/`: (1) написать `SKILL.md` с разделами When/Default/Permissive/Ironclad/Anti-loophole/Why; (2) `mapping.yaml` entry (`mode: auto`, `category: software-development`, без replace-rules — правило агент-агностично); (3) install + build + build-hermes; (4) опционально pre-commit hook на `[skip-tdd: <one-of-four>]` (отдельная таска, не блокер). Review-таска `tdd-criteria-review` создаётся автоматически скилом промоушена.
|
||||
@@ -1,164 +0,0 @@
|
||||
---
|
||||
name: meeting-room-promote-brainstorm
|
||||
description: Use when user says "промоутни брейнсторм", "finalize <topic>", "выкати в вики", "promote <topic>", or wants to finalize a .brainstorm/<topic>.md buffer. Asks routing (room-meta vs domain), writes to local .wiki/concepts/ OR ingests into target project's wiki via mcp__projects-meta__knowledge_ingest, extracts action-items into target project's .tasks via mcp__projects-meta__tasks_create, creates a [<topic>-review] umbrella task in the target project blocked by impl-tasks for cross-project review handoff, archives buffer to .archive/<date>-<topic>.md.
|
||||
---
|
||||
|
||||
# meeting-room-promote-brainstorm
|
||||
|
||||
Финализирует созревший брейнсторм-буфер. По правилу C+ii из spec'а: room-meta → локальный `.wiki/concepts/`, domain → глобал через `projects-meta`; буфер уезжает в `.archive/`.
|
||||
|
||||
## When to use
|
||||
|
||||
- «промоутни брейнсторм», «finalize <topic>», «выкати в вики», «promote <topic>».
|
||||
- Пользователь явно ссылается на `.brainstorm/<topic>.md` как на готовый к промоушену.
|
||||
|
||||
## Inputs
|
||||
|
||||
- Путь `.brainstorm/<topic>.md` или просто `<topic>`.
|
||||
|
||||
## Decision flow
|
||||
|
||||
```
|
||||
.brainstorm/<topic>.md
|
||||
│
|
||||
▼
|
||||
read + summarize (1–2 paragraphs)
|
||||
│
|
||||
▼
|
||||
ask: room-meta or domain?
|
||||
│ │
|
||||
│ ▼
|
||||
│ ask: target project (validate ~/projects/<proj>/ exists)
|
||||
│ │
|
||||
▼ ▼
|
||||
write to ingest via
|
||||
.wiki/concepts mcp__projects-meta__knowledge_ingest
|
||||
│ │
|
||||
└──────┬───────┘
|
||||
▼
|
||||
parse action-items, show, allow edit
|
||||
│
|
||||
▼
|
||||
for each: mcp__projects-meta__tasks_create
|
||||
│
|
||||
▼
|
||||
if domain && N≥1: tasks_create [<topic>-review] (blocked-by impl)
|
||||
│
|
||||
▼
|
||||
git mv .brainstorm/<topic>.md .archive/<date>-<topic>.md
|
||||
│
|
||||
▼
|
||||
append to .wiki/log.md
|
||||
```
|
||||
|
||||
## Steps
|
||||
|
||||
1. **Прочитать `.brainstorm/<topic>.md`.** Показать summary (≤2 абзаца).
|
||||
2. **Спросить тип:** room-meta (методология самой комнаты) или domain (доменное содержимое для какого-то целевого проекта)?
|
||||
3. **Если domain:**
|
||||
- Спросить целевой проект (имя папки в `~/projects/`).
|
||||
- Валидация: вызвать `mcp__projects-meta__meta_status`, убедиться что проект известен; иначе — abort с сообщением «зарегистрируй проект через setup-projects-meta».
|
||||
4. **Парсинг action-items:**
|
||||
- regex по строкам вида `- [ ] ...`, `- [ ]`, секции после `## Следующие шаги`/`## TODO`/`## Next steps`/`## Action items`.
|
||||
- Показать список, дать редактировать/удалять/добавлять.
|
||||
- Если 0 action-items — продолжить, не блокировать.
|
||||
5. **Промоушен контента:**
|
||||
- **room-meta:** `Write` → `.wiki/concepts/<topic>.md` с frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
date: <YYYY-MM-DD>
|
||||
source: .brainstorm/<topic>.md
|
||||
status: promoted
|
||||
type: room-meta
|
||||
---
|
||||
```
|
||||
|
||||
Тело — содержимое буфера (можно слегка причесать заголовки, секции типа TODO убрать — они уже сепарированы в action-items).
|
||||
|
||||
- **domain:** `mcp__projects-meta__knowledge_ingest` с параметрами:
|
||||
- `project: <target>`
|
||||
- `path: concepts/<topic>.md` (внутри target wiki)
|
||||
- `content: <тело буфера с frontmatter>`
|
||||
|
||||
Если `knowledge_ingest` падает → abort до tasks_create и до `git mv`. Сообщить пользователю.
|
||||
|
||||
6. **Создание тасок:** для каждого action-item:
|
||||
- `mcp__projects-meta__tasks_create` с `project: <target>` (для domain) или с `project: <inferred-from-buffer>` (для room-meta это может быть `meeting-room` или конкретный проект упомянутый в action-item — спросить пользователя если неоднозначно).
|
||||
- Title — первая строка action-item; description — остальное.
|
||||
- Если N-я таска упала — продолжить остальные, в конце сообщить какие созданы / какие нет.
|
||||
- Запомнить slug'и созданных импл-тасок для шага 6.5.
|
||||
|
||||
6.5. **Review-чекпоинт** (только для domain-промоушена с N≥1 импл-тасок; для room-meta или N=0 — skip с пометкой в логе):
|
||||
- `mcp__projects-meta__tasks_create`:
|
||||
- `target_project: <target>`
|
||||
- `slug: <topic>-review`
|
||||
- `status: blocked`
|
||||
- `blocker:` `«impl-tasks: <comma-separated slugs из шага 6>»`
|
||||
- `description:` шаблон ниже.
|
||||
- `next_action:` «Дождаться 🟢 у всех blocker-тасок. Прочитать спецификацию (см. путь в description). Для каждой импл-таски: `git show <commit>`, прогнать тесты в её scope'е, сверить с acceptance criteria. Findings → новые follow-up tasks через `mcp__projects-meta__tasks_create`.»
|
||||
- Description шаблон:
|
||||
|
||||
```
|
||||
Code-review checkpoint для брейнсторма <topic> (промоушен <YYYY-MM-DD>).
|
||||
|
||||
**Спецификация:** <путь к промоушенному design-документу — concepts/<topic>.md в target-wiki или claude-skills/.wiki/concepts/<topic>-design.md, в зависимости от того куда ушёл ingest>.
|
||||
**Импл-таски (review против их acceptance criteria):** <list slug'ов из шага 6>.
|
||||
|
||||
**Кто делает:** **не имплементер.** Следующая сессия в этом проекте (другая модель / другой день / другой агент) поднимает таску с чистым контекстом. «Я только что это написал» bias = главный риск.
|
||||
|
||||
**Чек-лист ревью:**
|
||||
- Прочитать спецификацию (acceptance criteria каждой импл-таски).
|
||||
- `git log --oneline` shipped-коммитов (по slug или scope в commit-message).
|
||||
- Для каждой импл-таски: прогнать соответствующие тесты, реально проверить что они доходят до своих веток (не coverage-illusion).
|
||||
- Сверить дизайн-decisions со shipped-кодом (signature, params, error-paths, безопасность).
|
||||
- Findings — отдельные follow-up tasks (`<topic>-<gap>-fix` или подобное) через `tasks_create`.
|
||||
|
||||
**Закрытие:** только когда все findings зафайлены ИЛИ ревьюер подтвердил «нет findings» в close-note.
|
||||
```
|
||||
|
||||
- Если `tasks_create` review-таски упала — сообщить пользователю, **продолжить** к шагу 7 (архивация буфера). Review-таску можно создать вручную позже из `.archive/<date>-<topic>.md`.
|
||||
|
||||
7. **Архивация:**
|
||||
|
||||
```bash
|
||||
git mv .brainstorm/<topic>.md .archive/<YYYY-MM-DD>-<topic>.md
|
||||
```
|
||||
|
||||
**Только** если шаги 5 и 6 прошли (или прошли с допустимым partial — пользователь подтвердил). Иначе — оставить буфер на месте, чтобы можно было ретраиить.
|
||||
|
||||
8. **Лог:** дописать в `.wiki/log.md`:
|
||||
|
||||
```
|
||||
<date> promoted <topic> → <destination> [created N tasks in <proj>]
|
||||
```
|
||||
|
||||
9. **Финальный отчёт пользователю:**
|
||||
- Куда промочено (полный путь).
|
||||
- Какие таски созданы (id, title, проект).
|
||||
- Куда уехал исходник.
|
||||
|
||||
## Failure modes
|
||||
|
||||
- `.brainstorm/<topic>.md` отсутствует → abort.
|
||||
- `mcp__projects-meta` недоступен → abort до записей.
|
||||
- Целевой проект (для domain) не найден в `meta_status` → abort.
|
||||
- `knowledge_ingest` упал → abort до `tasks_create` и `git mv`. Буфер остаётся.
|
||||
- `tasks_create` упал на N-й таске → продолжить остальные. Сообщить partial. **Не делать** `git mv` без подтверждения пользователя.
|
||||
- `tasks_create` упал на review-таске (шаг 6.5) → не блокировать; перейти к архивации, сообщить пользователю чтобы создал вручную из `.archive/`.
|
||||
|
||||
## Side effects
|
||||
|
||||
- room-meta: создаёт `.wiki/concepts/<topic>.md`.
|
||||
- domain: создаёт запись в target wiki через MCP.
|
||||
- Создаёт N тасок в target `.tasks/` через MCP.
|
||||
- Для domain с N≥1: создаёт зонтичную `<topic>-review` таску (status=blocked, blocker=impl-slugs) в том же target.
|
||||
- Перемещает `.brainstorm/<topic>.md` → `.archive/<date>-<topic>.md`.
|
||||
- Аппендит строку в `.wiki/log.md`.
|
||||
|
||||
## What NOT to do
|
||||
|
||||
- Не писать доменное содержимое в локальный `.wiki/concepts/` (правило #1 из root `CLAUDE.md`).
|
||||
- Не создавать локальный `.tasks/` (правило #3).
|
||||
- Не делать `git mv` буфера до успеха ingest+tasks.
|
||||
- Не удалять буфер вместо `git mv` — теряется история.
|
||||
@@ -1,185 +0,0 @@
|
||||
---
|
||||
date: 2026-05-05
|
||||
source: .brainstorm/modulair-rag.md
|
||||
status: promoted
|
||||
type: room-meta
|
||||
---
|
||||
|
||||
# ModulAIr RAG — brainstorm trace
|
||||
|
||||
> Promoted 2026-05-05 from `.brainstorm/modulair-rag.md` (single-agent session inside `.meeting-room/`). Process trace — фиксирует **как развивался брейнсторм**, какие развилки выбрали, что отвергнуто и почему. Доменный design финализирован отдельно в `~/projects/.wiki/concepts/modulair-rag-design.md`.
|
||||
|
||||
> Source scenario: `scenarios/modulair.md` (4-agent meeting frontmatter, не запускалось — пользователь предпочёл одного собеседника).
|
||||
> Prior multi-agent transcript: `.wiki/raw/research/2026-05-03-modulair.md` — там пользователь с другим ассистентом прошёл первый круг и накопил пул tooling-кандидатов (Marker, Repomix, ArchiveBox, Memos, Hermes-agent, и др.).
|
||||
|
||||
---
|
||||
|
||||
## Контекст ModulAIr
|
||||
|
||||
ModulAIr — AI-управляемый секвенсор/контроллер для еврорэка на Pico 2 W. Декомпозирован на 6 sub-projects:
|
||||
|
||||
- `modulair-hw` — KiCad PCB (Pico 2 W + DAC + Gate-drivers + ADC + MIDI TRS + audio preamp + eurorack-питание)
|
||||
- `modulair-fw` — прошивка Pico 2 W
|
||||
- `modulair-script` — Teletype-style DSL + интерпретатор
|
||||
- `modulair-mcp` — MCP-мост между LLM и Pico
|
||||
- **`modulair-rag`** — база знаний ◄ предмет этого брейнсторма
|
||||
- `modulair-agent` — Hermes-агент как top-level orchestrator
|
||||
|
||||
**Сквозная архитектурная развилка решена: Variant A — Pico-autonomous, LLM-conductor.** Pico исполняет скрипты sample-accurate, LLM через MCP мутирует паттерны/скрипты, но не сидит в горячем audio-пути. Wi-Fi latency перестаёт быть проблемой.
|
||||
|
||||
## RAG-решения и почему
|
||||
|
||||
### Стратегия — c-tiered (а не плоский vector RAG)
|
||||
|
||||
Чисто вектор-RAG плох на factual-лукапах в синт-домене:
|
||||
- Эмбеддинги "0–8V" / "±5V" / "0V to 10V" близки в семантическом пространстве, но это разные факты
|
||||
- Отрицание ("у X нет Reset-входа") не работает — ретривер тащит чанки где есть "Reset" и "X" рядом
|
||||
- Сравнения требуют JOIN, а не top-k retrieval
|
||||
- Чанкинг ломает таблицы datasheet'ов
|
||||
|
||||
→ **Tier 1** vector (manuals / theory / VCV source / forum threads) — recall-heavy, fuzzy.
|
||||
→ **Tier 2** structured Postgres (module specs из ModularGrid + vendor parsers) — precision-heavy, точные ответы.
|
||||
→ **Tier 3** ручные аннотации (~50 модулей личного рэка, calibration quirks, undocumented behavior).
|
||||
|
||||
### Storage
|
||||
|
||||
- **Postgres (cloud, существующий)** для Tier 2/3. **Не MariaDB:** JSONB для переменной формы jack-списков, pgvector как открытая дверь, recursive CTE + lateral joins зрелее, array-типы родные, MCP/ORM-экосистема Postgres-first.
|
||||
- **LightRAG #2 (новый instance с `working_dir=modulair-rag`)** для Tier 1. Текущий LightRAG-корпус не трогаем — он для других задач.
|
||||
- **Не pgvector unified** — это потребовало бы миграцию текущего LightRAG.
|
||||
- **Не Neo4j** — overkill для тысяч модулей; relations моделируются плоскими таблицами.
|
||||
|
||||
### Scope первой итерации — (II) MVP на full-scrape ModularGrid
|
||||
|
||||
~15k модулей, ~1 месяц. Альтернативы: (I) Top-50 за 2 недели — учиться на знакомом; (III) всё сразу за 1.5–2 мес. Выбрано (II) — компромисс между амбицией и сроками.
|
||||
|
||||
Что меняется при этом скоупе:
|
||||
- **Per-field provenance обязательна** — без неё не отличить достоверный ±5V от LLM-угадки
|
||||
- **LLM-extraction как этап pipeline** — jacks/polarity/range живут в свободном тексте описаний и manual PDF, нужен LLM-проход по 15k
|
||||
- **Validation gates first-class** — voltage standards становятся правилами (audio типично ±5V, anomaly → флаг)
|
||||
|
||||
### Pipeline — immutable layered (L1-L4)
|
||||
|
||||
```
|
||||
L1 raw HTML → MinIO bucket, content-addressed (sha256)
|
||||
L2 DOM extracts → JSONL/run, структурные поля (HP, manufacturer, current_ma)
|
||||
L3 LLM extracts → JSONL/run, jacks/polarity/range из свободного текста
|
||||
L4 Postgres → "current state", собран из L2+L3+Tier-3
|
||||
```
|
||||
|
||||
Зачем слоями: на MVP схема меняется ~5×, LLM-промпт ~10×. Без immutable слоёв каждое изменение = повторный scrape (медленно, rate-limit) + LLM-проход (дорого). С immutable — пере-extract из L2/L3 за минуты.
|
||||
|
||||
### Source стратегия — multi-source
|
||||
|
||||
```
|
||||
1. Vendor-side parsers (top-10):
|
||||
pichenettes/eurorack (canonical Mutable), Make Noise, Intellijel,
|
||||
Doepfer, ALM, Noise Engineering, Befaco, 4ms, Erica, Tiptop
|
||||
2. ModularGrid scrape (HTML, ≤1 RPS, weekly cron)
|
||||
robots.txt allow модули и .json; их официальный API паузнут из-за EU copyright reform
|
||||
3. Tier 3 — ручные аннотации (~50 модулей личного рэка)
|
||||
```
|
||||
|
||||
Не зависимы от ModularGrid одного — фрагильно (DOM может смениться, anti-scrape, юр. неопределённость).
|
||||
|
||||
### Extractor LLM — Ollama Cloud sample first, не Haiku
|
||||
|
||||
Решение: первый прогон через Ollama Cloud (GLM-5.1 / qwen) на golden set, валидация против Haiku 4.5 как benchmark. Если разница <5pp на ключевых метриках — Ollama, бесплатно. Если ≥10pp — Haiku-tiered с Sonnet 4.6 на flagged записях.
|
||||
|
||||
**Golden set protocol** (1–2 дня ручной работы):
|
||||
- ~40 модулей: 20 Mutable (pichenettes/eurorack), 10 Doepfer, 5 Make Noise/Intellijel, 5 edge-case
|
||||
- JSON-эталон per модуль: `{name, direction, signal_type, polarity, range_v_min, range_v_max}`
|
||||
- Метрики/пороги: F1 signal_type ≥0.85, Acc polarity ≥0.85, MAE range ≤0.5V, hallucination ≤5%, miss ≤15%
|
||||
- Артефакты в git: `golden/`, `runs/<model>/`, `metrics/`
|
||||
|
||||
### Provenance — module_facts + materialized consensus view
|
||||
|
||||
```sql
|
||||
module_facts (
|
||||
module_id, field, value JSONB, confidence REAL,
|
||||
source_layer -- 'L2-dom' | 'L3-llm-haiku' | 'L3-llm-sonnet' | 'tier3-manual'
|
||||
source_ref, -- 'scrape-2026-05-05/mutable-rings.json#desc-jacks'
|
||||
scraped_at
|
||||
)
|
||||
```
|
||||
|
||||
Плоские `modules` / `jacks` — materialized view "consensus" поверх highest-confidence values. MCP читает плоский view, валидатор/админка — `module_facts` напрямую. Альтернатива (`<col>_confidence`/`<col>_source` рядом) отвергнута — на 30+ полях шум.
|
||||
|
||||
### Tier 1 corpus — phased
|
||||
|
||||
**Phase 1 (MVP):** ModularGrid descriptions всех 15k (из L1) + top-100 vendor manuals + VCV Rack Fundamental/Library source + 30–50 hand-curated theory статей.
|
||||
**Phase 2 post-MVP:** vendor manuals top-500, YouTube whisper-транскрипты топ-creator'ов, selected forum threads.
|
||||
**Phase 3:** long-tail manuals, full forum scrape с quality filter.
|
||||
|
||||
### Deploy shape — Docker compose, своё железо
|
||||
|
||||
Existing: Postgres, Traefik, Portainer, kicad-mcp (для других sub-projects).
|
||||
|
||||
5 новых контейнеров для modulair-rag:
|
||||
1. `lightrag-modulair` — Tier 1 vector, working_dir отдельный
|
||||
2. `minio` — L1 raw HTML cache, content-addressed
|
||||
3. `modulair-pipeline` — scraper + extractor + loader, cron внутри
|
||||
4. `tier1-converter` — Marker + Repomix + Firecrawl batch jobs
|
||||
5. `modulair-mcp` — MCP-сервер для Hermes (`module_spec`, `concept_search`, `module_compare`, `module_pairs`, `module_text`, `rack_modules`, `provenance`)
|
||||
|
||||
### Orchestration — Hermes, не n8n
|
||||
|
||||
Hermes-agent живёт в отдельном sub-project и через MCP зовёт наш `modulair-mcp` + (будущий) `firmware-mcp` + собственные Python-skills для batch (`run_repomix`, `run_marker`). n8n из плана убран — дублирует Hermes.
|
||||
|
||||
Phases:
|
||||
- Phase 1 — cron внутри контейнеров
|
||||
- Phase 2 — Changedetection.io webhooks → Hermes scheduled-automations
|
||||
- Phase 3 — расширение Hermes skills (multi-source priorisation, feedback-loop из Memos/Obsidian, vendor-парсеры как skills)
|
||||
|
||||
## Что отвергнуто и почему
|
||||
|
||||
| Отвергнуто | Причина |
|
||||
|---|---|
|
||||
| Pure vector RAG (c-flat) | Factual-лукапы галлюцинируют; embeddings не различают voltage ranges |
|
||||
| Postgres + pgvector unified (α) | Заставит мигрировать существующий LightRAG-корпус |
|
||||
| MariaDB | JSONB и pgvector будущего — типпинг-пойнт за Postgres |
|
||||
| Neo4j | Overkill для тысяч модулей; relations плоско моделируются |
|
||||
| n8n | Дублирует Hermes-agent |
|
||||
| markitdown как primary | Marker лучше PDF, Repomix лучше код, Firecrawl лучше JS-сайты |
|
||||
| tree-sitter primary chunking | Repomix даёт structure-aware MD из коробки |
|
||||
| DVC | pg_dump + content-addressed MinIO покрывают provenance |
|
||||
| kicad-mcp в modulair-rag | Out of scope; живёт в modulair-agent / modulair-hw |
|
||||
| ArchiveBox в MVP | Heavy (Docker+Chrome+Node), своя scraper-реализация дешевле для targeted-scrape |
|
||||
|
||||
## Открытые вопросы (не блокируют MVP)
|
||||
|
||||
- Финальный размер golden-set (40 принято; ужесточение MAE до 0.2V для CV-модулей — после первого прогона)
|
||||
- Music theory sources — конкретный список 30–50 статей не зафиксирован (упомянуты Allen Strange, Whitwell, SoS Synth Secrets, Eno strategies)
|
||||
- Phasing для feedback-loop (Memos / Obsidian #feedback) — Phase 2, конкретная реализация позже
|
||||
- Где физически живёт kicad-mcp (host stdio vs Docker) — релевантно для modulair-agent / modulair-hw, не для modulair-rag
|
||||
|
||||
## Tooling из исходного транскрипта 2026-05-03
|
||||
|
||||
| Категория | Что взято | Что отвергнуто |
|
||||
|---|---|---|
|
||||
| PDF→MD | **Marker** (primary), **LlamaParse** (fallback) | markitdown как primary, Docling (только если Marker не установится) |
|
||||
| Web→MD | **Firecrawl** (batch), **Jina Reader** (одноразовый) | Trafilatura |
|
||||
| Code→MD | **Repomix** | tree-sitter с нуля |
|
||||
| Web archive | **Wallabag** в Phase 2 | ArchiveBox в MVP, Linkwarden, Shiori |
|
||||
| Change detection | **Changedetection.io** в Phase 2 | (alone, без n8n) |
|
||||
| Orchestration | **Hermes-agent** | n8n, Huginn |
|
||||
| Data versioning | `pg_dump` + content-addressed MinIO | DVC |
|
||||
| Feedback loop | **Memos** или **Obsidian** в Phase 2 | (одно из двух) |
|
||||
| Container UI | **Portainer** (existing) | Dockge |
|
||||
| Vector store | **LightRAG** (existing для других, новый instance для modulair) | ChromaDB, Pinecone, GraphRAG |
|
||||
| Algo composition | **music21** — для modulair-agent, не RAG | — |
|
||||
| Embedded DSP | Pure Data + hvcc / Faust — для modulair-fw audio sub-project, не RAG | — |
|
||||
| EDA → MD | **kicad-mcp** существующий, для modulair-hw / modulair-agent | KiCad-CLI / KiBot — out of scope для modulair-rag |
|
||||
|
||||
## Меморики, появившиеся за сессию
|
||||
|
||||
- `feedback_meeting_room_workspace.md` — `.meeting-room` это brainstorm-зона, артефакты идут в `.brainstorm/` или global wiki, не через "transit-zone autopilot"
|
||||
- `project_extend_discipline_for_meeting_room.md` — открытый todo расширить project-discipline под brainstorm-workspaces
|
||||
- `feedback_read_source_transcripts.md` — `.meeting-room/source/<date>-<topic>.md` это pre-loaded user research, читать до предложения стэка
|
||||
|
||||
## Deferred actions (не созданы как таски)
|
||||
|
||||
Целевые проекты `modulair-rag`/`meeting-room` пока не зарегистрированы в `projects-meta` (на 2026-05-05 в `meta_status` — 12 проектов, ни один из них). `tasks_create` в скиле `meeting-room-promote-brainstorm` пропущен. Перевести в backlog при появлении проектов:
|
||||
|
||||
1. Брейнсторм per остальным 5 sub-projects (`modulair-hw`, `modulair-fw`, `modulair-script`, `modulair-mcp`, `modulair-agent`) — owner: meeting-room.
|
||||
2. Когда RAG-implementation начнётся — поднять структуру репозитория `modulair-rag` где-то в `~/projects/`, скелет compose.yml, `.tasks/STATUS.md` под фактический проект — owner: modulair-rag.
|
||||
3. Заведение golden-set (1–2 дня ручной работы — это первое что нужно сделать; в MVP это блокирующая зависимость для extractor-валидации) — owner: modulair-rag.
|
||||
@@ -34,3 +34,4 @@ Events: `started`, `promoted`, `registered`, `archived`.
|
||||
2026-05-07 amended tdd-criteria post-promotion: anti-loophole rule 4 (test-immutability + [test-modify: was X; is Y] marker + separate-commit-from-impl) added; user surfaced symmetric vandalism risk on tests after initial promotion. Patches landed: claude-skills#tdd-criteria-skill-write description updated (commit b7819b17), claude-skills#tdd-criteria-precommit-hook task created (commit d440bb52). Design-doc amendment NOT applied directly (knowledge_ingest is create-only — overwrite blocked); amendment text embedded in skill-write task description for impl session to apply via direct git edit.
|
||||
2026-05-08 split meeting-room into multi-agent runtime (this zone) + .workshop/ boss-zone; remote workshop repo created at git.kzntsv.site/OpeItcLoc03/workshop.git
|
||||
2026-05-08 amended meeting-room-architecture.md: split-rewrite (runtime-only); boss sections moved to .workshop/.wiki/concepts/workshop-architecture.md
|
||||
2026-05-08 split-done cleanup: removed .archive/, .brainstorm/, .wiki/concepts/modulair-rag-brainstorm-trace.md, .wiki/raw/{naming,research}/, .claude/skills/meeting-room-promote-brainstorm/. All artifacts migrated to .workshop/ (commits 4608ba9..f8f6f1a in workshop repo). Promoted concept: .workshop/.wiki/concepts/meeting-room-split.md.
|
||||
|
||||
@@ -1,186 +0,0 @@
|
||||
---
|
||||
title: "Хочу обсудить, как подключить другую LLM к ревью кода, написанного КЛодом. Как это организовать? Наверняка ты знаешь, как другие это делают?"
|
||||
source: "https://www.google.com/search?sourceid=chrome&aep=42&source=chrome.crn.rb&q=%D0%A5%D0%BE%D1%87%D1%83+%D0%BE%D0%B1%D1%81%D1%83%D0%B4%D0%B8%D1%82%D1%8C%2C+%D0%BA%D0%B0%D0%BA+%D0%BF%D0%BE%D0%B4%D0%BA%D0%BB%D1%8E%D1%87%D0%B8%D1%82%D1%8C+%D0%B4%D1%80%D1%83%D0%B3%D1%83%D1%8E++LLM++%D0%BA+%D1%80%D0%B5%D0%B2%D1%8C%D1%8E+%D0%BA%D0%BE%D0%B4%D0%B0%2C+%D0%BD%D0%B0%D0%BF%D0%B8%D1%81%D0%B0%D0%BD%D0%BD%D0%BE%D0%B3%D0%BE+%D0%9A%D0%9B%D0%BE%D0%B4%D0%BE%D0%BC.+%D0%9A%D0%B0%D0%BA+%D1%8D%D1%82%D0%BE+%D0%BE%D1%80%D0%B3%D0%B0%D0%BD%D0%B8%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D1%8C%3F+%D0%9D%D0%B0%D0%B2%D0%B5%D1%80%D0%BD%D1%8F%D0%BA%D0%B0+%D1%82%D1%8B+%D0%B7%D0%BD%D0%B0%D0%B5%D1%88%D1%8C%2C+%D0%BA%D0%B0%D0%BA+%D0%B4%D1%80%D1%83%D0%B3%D0%B8%D0%B5+%D1%8D%D1%82%D0%BE+%D0%B4%D0%B5%D0%BB%D0%B0%D1%8E%D1%82%3F&mstk=AUtExfD5EFxgCPzN9i00Xb6Sng7oox3R0MLA9REWp9DPMJQl5bRyt_-vjx-aF_OLAdQQteu-vj8I7bVGjoD-a114g5-BOzZtyq0bSXcimbBbeakgHNjFiWOnFqNZ3MfdmwJwTKjGzkXXMCEsfvlWcg2J_AmBHzsuH60i3HjfHo2qSI148skiOz50PggUYfyARIMggD2xAPIent3dfljllT5pubb9vjJJXyKarGgn_uz-iiExDVpuL0wstNe7d1uUxyRS3-af17X_So2j8KnM83XZJxHLZcwUqz_l-pk&csuir=1&mtid=aof3aaPIFv_97_UPusiA6Qo&udm=50"
|
||||
fetched: "2026-05-03"
|
||||
published:
|
||||
fetched_via: "obsidian-web-clipper"
|
||||
tags:
|
||||
- "wiki-raw"
|
||||
- "clipping"
|
||||
---
|
||||
|
||||
## Результаты поиска
|
||||
|
||||
Здравствуйте, Victor! Что вас интересует?
|
||||
|
||||
Хочу обсудить, как подключить другую LLM к ревью кода, написанного КЛодом. Как это организовать? Наверняка ты знаешь, как другие это делают?
|
||||
|
||||
Подключение сторонней LLM для ревью кода, написанного Claude (или любой другой моделью), — это отличная практика «перекрестной проверки» (cross-review), которая помогает отловить галлюцинации и специфические баги.
|
||||
|
||||
Вот как это обычно организуют на практике:
|
||||
|
||||
1\. Автоматизация через CI/CD (Самый популярный путь)
|
||||
|
||||
Большинство команд не копипастят код вручную, а встраивают проверку прямо в GitHub/GitLab.
|
||||
|
||||
- **Инструменты:** Используются готовые экшены или скрипты (например, `coderabbit.ai`, `pr-agent` от Codium или опенсорсные аналоги).
|
||||
- **Процесс:** Claude пишет код и создает Pull Request. Скрипт в CI ловит это событие, отправляет диф (diff) в API другой модели (например, **GPT-4o** или **Llama 3**) с системным промптом: «Ты — эксперт по безопасности, проверь этот код на уязвимости».
|
||||
- **Результат:** Вторая LLM оставляет комментарии прямо в PR.
|
||||
|
||||
2\. Подход «Разделение ролей»
|
||||
|
||||
Чтобы проверка была качественной, другой модели дают узкую специализацию. Не просите её просто «проверить». Дайте конкретный фокус:
|
||||
|
||||
- **Модель A (Claude):** Пишет функционал и логику.
|
||||
- **Модель B (например, GPT-4o):** Ищет только ошибки в типах, потенциальные утечки памяти или несоответствие стилю (Style Guide).
|
||||
- **Модель C (например, DeepSeek Coder):** Пишет модульные тесты на этот код. Если тесты не проходят — значит, в коде Claude была ошибка.
|
||||
|
||||
3\. Использование локальных моделей (для приватности)
|
||||
|
||||
Если код чувствительный, многие разворачивают локальную LLM через **Ollama** или **vLLM**.
|
||||
|
||||
- Вы можете настроить локальную **Llama 3 (70B)** или **Phind-CodeLlama**, которая будет «подглядывать» за тем, что генерирует Claude, и сигнализировать, если код выглядит подозрительно.
|
||||
|
||||
4\. Промпт-инжиниринг для ревьюера
|
||||
|
||||
Важно, чтобы «ревьюер» не знал, что код написала другая нейронка (это убирает предвзятость). Типовой промпт для второй модели:
|
||||
|
||||
> "Перед тобой PR от разработчика. Проанализируй изменения. Найди логические ошибки, проблемы с производительностью и предложи 3 улучшения. Будь строг, но конструктивен."
|
||||
|
||||
С какими моделями лучше «спаривать» Claude?
|
||||
|
||||
- **Claude + GPT-4o:** Классика. У них разный «стиль мышления», и они часто находят ошибки друг за другом.
|
||||
- **Claude + DeepSeek V3:** Отличное сочетание для Python/C++, так как DeepSeek очень силен именно в кодинге и часто дешевле.
|
||||
- **Claude + Sonar (Perplexity):** Если код завязан на свежих библиотеках, которые вышли месяц назад (Sonar умеет ходить в интернет и проверять актуальность API).
|
||||
|
||||
**С какого стека технологий (язык программирования, гит-хостинг) ты хочешь начать настройку такой связки?**
|
||||
|
||||
В ответах искусственного интеллекта могут быть ошибки. [Learn more](https://support.google.com/websearch?p=aimode)
|
||||
|
||||
Создание общедоступной ссылки…
|
||||
|
||||
Показать все
|
||||
|
||||
Автоматизация через CI/CD (Самый популярный путь) - а еще пути есть? ЧТобы без пулл-реквестов?
|
||||
|
||||
Если мы убираем этап Pull Request и CI/CD, значит, мы переносим взаимодействие на уровень **IDE** (среды разработки) или **локальных скриптов**. Это делает цикл обратной связи мгновенным: вы еще не отправили код в репозиторий, а «второе мнение» уже получено.
|
||||
|
||||
Вот основные способы организовать это «на лету»:
|
||||
|
||||
1\. Расширения для IDE с поддержкой разных моделей (Continue.dev / Void)
|
||||
|
||||
Это самый удобный «ручной» способ.
|
||||
|
||||
- **Как это работает:** Вы устанавливаете плагин (например, **Continue** для VS Code или JetBrains). В нем можно настроить сразу несколько API-ключей.
|
||||
- **Процесс:** Вы просите Claude (через встроенный чат или автодополнение) написать функцию. Затем выделяете этот код, нажимаете горячую клавишу, переключаете модель на **GPT-4o** или **DeepSeek** прямо в выпадающем списке и выбираете команду `/verify` или `/review`.
|
||||
- **Плюс:** Не нужно переключаться между вкладками браузера, код проверяется мгновенно.
|
||||
|
||||
2\. Локальные CLI-утилиты (скрипты «надсмотрщики»)
|
||||
|
||||
Вы можете написать простой Python-скрипт или использовать готовые CLI-инструменты (например, **Aider**), которые работают в терминале.
|
||||
|
||||
- **Процесс:** Вы сохраняете код, написанный Клодом, в файл. В терминале запускаете команду: `check-code --file logic.py --model gpt4`.
|
||||
- **Автоматизация:** Можно настроить **Git Hooks** (pre-commit hook). Когда вы пытаетесь сделать `git commit`, скрипт автоматически отправляет изменения во вторую LLM. Если она находит критические баги, коммит блокируется до тех пор, пока вы не подтвердите, что всё ок.
|
||||
|
||||
3\. "Multi-Agent" системы (CrewAI / AutoGen)
|
||||
|
||||
Это более продвинутый уровень, где вы создаете «чат» между двумя нейронками прямо у себя на компьютере.
|
||||
|
||||
- **Организация:** Вы запускаете локальный оркестратор.
|
||||
- **Роли:** Одной модели (Claude) дается задача «Напиши код», а второй (например, Llama 3 локально) — задача «Ты суровый техлид, критикуй каждый символ».
|
||||
- **Результат:** В консоли вы видите диалог двух моделей. Они спорят, пока код не станет идеальным, и только финальный вариант сохраняется в файл.
|
||||
|
||||
4\. Использование платформ-агрегаторов (Poe / TypingMind)
|
||||
|
||||
Если не хочется возиться с плагинами, используются веб-интерфейсы, где несколько моделей доступны в одном окне.
|
||||
|
||||
- **Процесс:** В **TypingMind** можно создать чат, где подключены обе модели. Вы отправляете промпт, Claude генерирует ответ, а вы одной кнопкой пересылаете этот ответ в соседнюю ветку чата для GPT-4 с просьбой провести аудит.
|
||||
|
||||
Резюме по инструментам:
|
||||
|
||||
- **Continue.dev** — если хотите проверять код прямо в процессе написания в VS Code.
|
||||
- **Aider** — если любите работать через терминал и хотите, чтобы LLM сама правила файлы.
|
||||
- **Git Hooks** — если хотите «мини-CI» прямо на своей машине, чтобы не пропускать плохой код в историю правок.
|
||||
|
||||
Какой из этих вариантов ближе к твоему привычному рабочему процессу — **редактор кода** или **терминал**?
|
||||
|
||||
В ответах искусственного интеллекта могут быть ошибки. [Learn more](https://support.google.com/websearch?p=aimode)
|
||||
|
||||
Создание общедоступной ссылки…
|
||||
|
||||
Показать все
|
||||
|
||||
Git Hooks интересно
|
||||
|
||||
Git Hooks — это скрипты, которые Git запускает автоматически при определенных действиях (например, перед каждым коммитом). Это идеальная «точка контроля», чтобы плохой код даже не попадал в вашу локальную историю.
|
||||
|
||||
Для ревью кода лучше всего подходит хук **`pre-commit`**. Вот как это организовать по шагам:
|
||||
|
||||
1\. Как это работает технически
|
||||
|
||||
Когда вы пишете `git commit -m "feat: add logic"`, Git запускает скрипт. Скрипт берет ваш измененный код, отправляет его по API во вторую LLM (например, GPT-4o или DeepSeek) и ждет ответа. Если LLM находит ошибки — коммит прерывается.
|
||||
|
||||
2\. Реализация (простой пример на Python)
|
||||
|
||||
Вам понадобится скрипт-прослойка. Можно использовать библиотеку `pre-commit` (наиболее стандартный путь в индустрии).
|
||||
|
||||
**Файл `.pre-commit-config.yaml` в корне проекта:**
|
||||
|
||||
```
|
||||
repos:
|
||||
- repo: local
|
||||
hooks:
|
||||
- id: llm-code-review
|
||||
name: LLM Code Review
|
||||
entry: python scripts/llm_check.py
|
||||
language: python
|
||||
stages: [commit]
|
||||
types: [python] # или другие языки
|
||||
```
|
||||
|
||||
**Скрипт `scripts/llm_check.py` (логика):**
|
||||
Скрипт должен:
|
||||
|
||||
1. Получить список измененных строк (`git diff --cached`).
|
||||
2. Отправить их в API (через `openai` или `anthropic` SDK).
|
||||
3. Если в ответе от LLM есть ключевое слово (например, "FAIL" или "CRITICAL"), скрипт делает `sys.exit(1)`, и коммит не проходит.
|
||||
|
||||
3\. Готовые инструменты
|
||||
|
||||
Чтобы не писать всё с нуля, можно использовать существующие обертки:
|
||||
|
||||
- **Llint:** Специальная утилита, которая работает как линтер, но на базе LLM. Её легко добавить в хуки.
|
||||
- **[Aider](https://aider.chat/):** Хотя это полноценный AI-программист, его можно вызвать из скрипта для проверки текущих изменений перед фиксацией.
|
||||
|
||||
4\. Плюсы и минусы такого подхода
|
||||
|
||||
**Плюсы:**
|
||||
|
||||
- **Гарантия чистоты:** В репозиторий не попадет код, который не прошел «вторую пару глаз».
|
||||
- **Локальность:** Вы узнаете об ошибке через 5 секунд, а не через 5 минут после прогона CI на сервере.
|
||||
|
||||
**Нюансы:**
|
||||
|
||||
- **Задержка:** Коммит будет занимать чуть больше времени (пока ждем ответ от API).
|
||||
- **Стоимость:** Каждый `git commit` будет тратить несколько центов (токенов).
|
||||
- **Ложные срабатывания:** Если LLM ошиблась и заблокировала коммит, вам придется использовать флаг `git commit --no-verify`, чтобы обойти проверку.
|
||||
|
||||
С чего лучше начать?
|
||||
|
||||
Если хочешь попробовать «на коленке», я могу набросать **готовый Python-скрипт**, который будет брать твои изменения и отправлять их на проверку в OpenAI или любую другую модель через LiteLLM.
|
||||
|
||||
**Нужен пример такого скрипта или помочь настроить сам механизм Git Hooks?**
|
||||
|
||||
В ответах искусственного интеллекта могут быть ошибки. [Learn more](https://support.google.com/websearch?p=aimode)
|
||||
|
||||
Создание общедоступной ссылки…
|
||||
|
||||
Показать все
|
||||
|
||||
Приложения Google
|
||||
|
||||
Аккаунт Google
|
||||
|
||||
Victor Kuznetsov
|
||||
|
||||
vitya.kuznetsov@gmail.com
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,45 +0,0 @@
|
||||
|
||||
А как тебе новые скилы добавить?
|
||||
────────────────────────────────────────
|
||||
|
||||
┊ 📚 skill hermes-agent-skill-authoring 0.0s
|
||||
─ ⚕ Hermes ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
|
||||
|
||||
Есть два способа добавить скиллы в Hermes:
|
||||
|
||||
1. Локальные (только для тебя) — через skill_manage(action='create'):
|
||||
Пишутся в ~/.hermes/skills/<категория>/<имя>/SKILL.md. Работают только на твоей машине, не переносятся на другие.
|
||||
|
||||
2. В репозитории (как раз то, что ты склонировал) — через write_file:
|
||||
Пишутся в дерево репозитория skills/<категория>/<имя>/SKILL.md, коммитятся, пушатся — и становятся доступны всем, кто клонирует репу.
|
||||
|
||||
Структура SKILL.md:
|
||||
|
||||
yaml
|
||||
|
||||
name: my-cool-skill
|
||||
description: Use когда <триггер>. <что делает>.
|
||||
version: 1.0.0
|
||||
author: Hermes Agent
|
||||
license: MIT
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [tag1, tag2]
|
||||
related_skills: [other-skill]
|
||||
My Cool Skill
|
||||
Overview
|
||||
Краткое описание: что и зачем.
|
||||
When to Use
|
||||
- Когда триггер X
|
||||
- Не использовать для: Y
|
||||
<Разделы с инструкциями>
|
||||
...
|
||||
Common Pitfalls
|
||||
1. Типичная ошибка → как исправить
|
||||
Verification Checklist
|
||||
- [ ] Проверка 1
|
||||
|
||||
Категории уже есть в репе: autonomous-ai-agents, creative, data-science, devops, email, gaming, github, mcp, media, mlops, note-taking,
|
||||
productivity, red-teaming, research, smart-home, social-media, software-development и др.
|
||||
|
||||
Хочешь создать новый скилл? Скажи какой — я подготовлю SKILL.md, запишу в репозиторий и закоммичу.
|
||||
@@ -1,768 +0,0 @@
|
||||
---
|
||||
title: "I gave Claude Code a $0.02/call coworker and stopped hitting Pro limits — here's the full setup"
|
||||
source: "https://www.reddit.com/r/ClaudeAI/comments/1t1o43w/i_gave_claude_code_a_002call_coworker_and_stopped/"
|
||||
fetched: "2026-05-05"
|
||||
published: 2026-05-02
|
||||
fetched_via: "obsidian-web-clipper"
|
||||
tags:
|
||||
- "wiki-raw"
|
||||
- "clipping"
|
||||
---
|
||||
Was hitting my weekly Pro limit by Wednesday every single week. Tried compact, Sonnet for simple tasks, tighter prompts — nothing worked.
|
||||
|
||||
Built a simple pattern: CLI scripts that delegate bulk file reading and boilerplate generation to Kimi K2.5 (any cheap model works). Claude calls them via Bash tool. [CLAUDE.md](http://claude.md/) has routing rules for when to delegate vs when to use Claude's own intelligence.
|
||||
|
||||
Results after 3 weeks:
|
||||
|
||||
1. Haven't hit limits once
|
||||
2. Kimi total spend: $0.38
|
||||
3. Documentation updates went from ~5000 tokens to ~200 tokens
|
||||
|
||||
Wrote up the full implementation with code: [https://medium.com/@kunalbhardwaj598/i-was-burning-through-claude-codes-weekly-limit-in-3-days-here-s-how-i-fixed-it-0344c555abda](https://medium.com/@kunalbhardwaj598/i-was-burning-through-claude-codes-weekly-limit-in-3-days-here-s-how-i-fixed-it-0344c555abda)
|
||||
|
||||
Happy to answer questions about the setup.
|
||||
|
||||
Github Link: [https://github.com/imkunal007219/claude-coworker-model.git](https://github.com/imkunal007219/claude-coworker-model.git)
|
||||
|
||||
---
|
||||
|
||||
## Comments
|
||||
|
||||
> **ClaudeAI-mod-bot** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojjiv58/) · 1 points
|
||||
>
|
||||
> **TL;DR of the discussion generated automatically after 160 comments.**
|
||||
>
|
||||
> The consensus is in: **the community overwhelmingly agrees with OP's strategy.** This is a smart and widely-practiced method for avoiding Claude's Pro usage limits.
|
||||
>
|
||||
> Let's break down the hive mind's thoughts on this. The core idea is to treat Claude like an expensive manager and give it a cheap intern for the grunt work. You use a low-cost model (like Kimi, DeepSeek, or a local Ollama model) for high-volume, low-intelligence tasks like reading large files or generating boilerplate code. This saves Claude's precious token limit for the actual thinking, debugging, and architectural work.
|
||||
>
|
||||
> Here are the key takeaways from the thread:
|
||||
>
|
||||
> - **Why not just use Haiku?** This was the top question. **Answer: Haiku still burns your Anthropic Pro usage limit.** The whole point of using an external model like Kimi or DeepSeek is that it's on a completely separate budget, effectively bypassing the weekly cap.
|
||||
> - **Which cheap model is best?** While OP used Kimi, the crowd favorite seems to be **DeepSeek V4 Flash**. Commenters found it more reliable and less prone to "overthinking" than Kimi. One user did a detailed cost-benefit analysis and found DeepSeek was **~23x cheaper** than using Opus for a summarization task, with "good enough" quality.
|
||||
> - **How do you set it up?** The simple way is OP's method: CLI scripts and routing rules in your `CLAUDE.md` file. For power users, a more robust method using MCP (Model Context Protocol) with a Docker container was suggested to get better performance and safety. Several users confirmed they do the same thing with a local model via Ollama, which requires zero external API calls.
|
||||
> - **Why doesn't Claude do this automatically?** It sort of does by using Haiku for some tasks, but as mentioned, that still hits your limit. The consensus is that only *you* can define the rules for what's worth spending tokens on. Claude doesn't know or care about your budget; it just wants to give the best answer, even if that means reading five files. The `CLAUDE.md` file is where you teach it to be frugal.
|
||||
> - **Is it worth it?** Absolutely, if you're hitting your limits. The goal isn't to save pennies on a $20 subscription; it's to make that subscription last the whole week. OP's $0.38 spend on Kimi effectively bought them several extra days of Claude access.
|
||||
>
|
||||
> For the newbies feeling lost: think of it as having two employees. Claude is your brilliant but expensive expert who you only bring in for the hard problems. Kimi/DeepSeek is your cheap intern who you make read all the boring documents and give you the notes. This post is about how to build the office system that tells them who does what.
|
||||
|
||||
> **RTG\_ZODIAC** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojhw3wa/) · 89 points
|
||||
>
|
||||
> This is a great idea but from my experience I found that Kimi tends to overthink a lot .
|
||||
> I think using deepseek v4 flash works best for this case
|
||||
>
|
||||
> > **spinthebottl** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojie1lp/) · 23 points
|
||||
> >
|
||||
> > Went through this exact same pipeline. Though I use v4 pro. It's so cheap it doesn't matter.
|
||||
> >
|
||||
> > **haltingpoint** · [2026-05-03](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojlw4ax/) · 4 points
|
||||
> >
|
||||
> > What is a good secure and private way to access and use Chinese models? If I'm using it with sensitive data (personal stuff, credentials) are there any providers for these that are safe and trusted? Can the models themselves be trusted to not contain backdoors?
|
||||
> >
|
||||
> > > **bosse** · [2026-05-03](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojm6fno/) · 10 points
|
||||
> > >
|
||||
> > > The Chinese models on OpenRouter aren't necessarily operated from China, so the inference can happen at providers located elsewhere. DeepSeek v4 Pro is currently hosted by several providers in Singapore and USA. So at least the providers are (hopefully) not monitored by the CCP, and OpenRouter has a statement that they have data protection agreements in place for their paid models, which at least provides some relief that your data is private.
|
||||
> > >
|
||||
> > > **More-Hunter-3457** · [2026-05-04](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojtasai/) · 1 points
|
||||
> > >
|
||||
> > > Fair concern. Two things: (1) the code Kimi sees is already on my local machine - I'm not sending production secrets, just source files that I wrote. If someone already has access to my dev machine, I have bigger problems. (2) If that's a dealbreaker, use Ollama with a local model - same pattern, zero network calls.
|
||||
>
|
||||
> > **nemzylannister** · [2026-05-03](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojnt9pv/) · 2 points
|
||||
> >
|
||||
> > do you mean the api? cause even flash requires a ton of vram, no?
|
||||
> >
|
||||
> > **More-Hunter-3457** · [2026-05-04](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojt8h60/) · 1 points
|
||||
> >
|
||||
> > Yeah Kimi's thinking tokens can be annoying - my first version came back empty because all the tokens went to internal reasoning. That's why I set max\_tokens to 8192+ for reading tasks.But honestly, the specific model barely matters. The pattern is what matters. If DeepSeek V4 Flash works better for you, swap the base\_url and model name - it's literally 2 lines. The whole point is the architecture, not the model choice.
|
||||
|
||||
> **thedeftone2** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/oji7g3f/) · 81 points
|
||||
>
|
||||
> Why doesn't the AI model do this to save tokens. What use case scenario calls for bulk, inefficient squandering of tokens?
|
||||
>
|
||||
> > **HighDefinist** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojiplvf/) · 22 points
|
||||
> >
|
||||
> > Actually, Claude does sometimes use agents for research large code bases. But, at least if you have enough tokens available, I think it's actually better to disable it... because sometimes the research agent is simply wrong, and Claude doesn't notice it for a while, leading to worse results than when the search is still in context... Then again, this might simply be a case of bad tooling on the side of Claude Code, as in, a well written "ask-kimi" prompt might plausibly outperform whatever Claude Code is doing internally with its research agents...
|
||||
> >
|
||||
> > **Am094** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojk0ta2/) · 9 points
|
||||
> >
|
||||
> > They do actually do this under the hood to some degree, say you use Opus 4.6 and type /costs after some work. You might see Opus 4.6 and a smaller model like Heiku used as a cost saving method. It uses the smaller model to say do more trivial things, and then the more capable one for more demanding stuff. That's the intention anyway. Ofc not without other trade offs.
|
||||
> >
|
||||
> > `claude-sonnet-4-6: 3.0k input, 43.8k output, 3.4m cache read, 170.1k cache write ($2.33)`
|
||||
> > `claude-haiku-4-5: 500 input, 14 output, 0 cache read, 0 cache write ($0.0006)`
|
||||
> >
|
||||
> > **Sufficient-Rough-647** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojidcc3/) · 17 points
|
||||
> >
|
||||
> > AI right now for all its nice bells and whistles is one crude blob that has single stream processing and roughy edges all over it like the jagged reasoning patterns, so frontier AI makers are optimising for the mean, to reach maximum generalised use cases, which means LLMs aren’t tweaked for token savings natively, they still rely on tool calling and other patterns for it. It will come, but not in the next 2-3 years until the LLM architectures mature.
|
||||
> >
|
||||
> > > **unexpectedkas** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojkgnxa/) · 7 points
|
||||
> > >
|
||||
> > > But this routing is done at the harness level no? Nothing stops Anthropic from updating the harness so that it uses the cheap model to do the basic tasks.
|
||||
> > >
|
||||
> > > > **Sufficient-Rough-647** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojkyudp/) · 2 points
|
||||
> > > >
|
||||
> > > > Yes, the harness is what I’m saying not the highest focus of LLM makers yet. Which is why you will see so many folks in the sub building their own solutions to minimize token usage. It’s not they can’t but they won’t be able to optimize the quality of output if they did for all.
|
||||
>
|
||||
> > **workware** · [2026-05-03](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojo6deb/) · 3 points
|
||||
> >
|
||||
> > It absolutely does this, Opus calls use Haiku to read-in files for example.
|
||||
> >
|
||||
> > But
|
||||
> >
|
||||
> > 1. this is enforced. I know what file I am reading-in, sometimes it's a long spec which i'm fine with Haiku on, but sometimes it's a prompt saved in a file that I want accurately read in by Opus. Having control over this would be great.
|
||||
> > 2. If the limit pool is the same, you're still going to affect your limit. I ask Claude to offload things to codex, which uses my $20 Codex limit and saves my $100 Claude limit.
|
||||
> >
|
||||
> > **t\_zk** · [2026-05-03](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojod5k9/) · 2 points
|
||||
> >
|
||||
> > Subagents (Task)
|
||||
> >
|
||||
> > **Impossible\_Hour5036** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojkejf8/) · 2 points
|
||||
> >
|
||||
> > Whether a token is "squandered" or not surely depends on how many tokens you've got available to you.
|
||||
> >
|
||||
> > **Inner-Lawfulness9437** · [2026-05-03](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojqwf7o/) · 1 points
|
||||
> >
|
||||
> > Copilot regularly does this with an explore subagent as well.
|
||||
> >
|
||||
> > **More-Hunter-3457** · [2026-05-04](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojt8apg/) · 1 points
|
||||
> >
|
||||
> > It has no incentive to. Claude doesn't know or care about your token budget - it's trying to give you the best answer. Reading 5 files to answer your question is the best answer from its perspective. The routing logic has to come from you (via CLAUDE.md) because only you know what's worth spending tokens on vs. what can be offloaded. Once you set the rules though,Claude follows them perfectly - it's been self-routing to Kimi for weeks without me needing to intervene.
|
||||
|
||||
> **tribat** · [2026-05-03](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojmrgnv/) · 20 points
|
||||
>
|
||||
> Fantastic idea, OP! I gave claude code the Medium URL and told it I wanted the same thing, but also with deepseek and ollama options. It took about 20 minutes total to write a few python files, including one to extract human-readable test.
|
||||
>
|
||||
> I gave it 2 API tokens and asked it to run before-and-after tests. TLDR: Claude tested itself against Deepseek and said "conservatively, 23x cheaper".
|
||||
>
|
||||
> ## Side-by-side judgment
|
||||
>
|
||||
> The two answers cover the same milestone list and agree on every concrete detail. Differences:
|
||||
>
|
||||
> | | Delegated (DeepSeek Flash) | Direct (Claude Opus 4.7) |
|
||||
> | --- | --- | --- |
|
||||
> | |
|
||||
> | Tags (`v0.0-bootstrap`, etc.) | omitted | included |
|
||||
> | M3 specificity | "spot-checked client emails matching correctly" | "5 random client emails" — |
|
||||
> | closer to source | | |
|
||||
> | M4 framing | "concrete accuracy numbers" | also captures "95% precision Phase-2 bar" |
|
||||
> | M6 acceptance | invented one | correctly noted "no explicit acceptance criteria" |
|
||||
> | Tone | a bit more verbose | tighter, closer to source phrasing |
|
||||
>
|
||||
> Both are usable. Claude's version is slightly more faithful to the source on edge details (M6 has no acceptance criteria; the doc *says* `v0.0-bootstrap` is the M0 tag even though the body says M0 is "½ day"). Flash invented an acceptance criterion for M6 that wasn't in the source — minor
|
||||
> hallucination.
|
||||
>
|
||||
> ## Cost comparison
|
||||
>
|
||||
> | | Path A (delegated) | Path B (Claude Opus 4.7) |
|
||||
> | --- | --- | --- |
|
||||
> | |
|
||||
> | Input tokens | 12,873 | ~12,873 (same file) |
|
||||
> | Output tokens | 565 | ~700 (slightly longer) |
|
||||
> | Pricing input | $0.14/M (DeepSeek miss) | $15/M (Opus 4.7 standard) |
|
||||
> | Pricing output | $0.28/M | $75/M |
|
||||
> | **Total** | **$0.001960** | **~$0.246** |
|
||||
> | Multiple | 1× | **~125×** |
|
||||
>
|
||||
> Plus, in Path A, the worker's 565-token answer goes into Claude's context for ~$0.0085 of
|
||||
> marginal Opus cost on whatever Claude does next. Total round-trip with delegation: **~$0.0105 vs ~$0.246 → ~23× cheaper end-to-end**, even being conservative about Opus cache.
|
||||
>
|
||||
> ## Quality verdict
|
||||
>
|
||||
> For "summarize a long doc" / "find facts in a corpus" tasks, **Flash's answer is good enough that Claude should accept it without re-reading the file**. The single hallucinated M6 acceptance
|
||||
> criterion is the kind of thing a careful reviewer catches in 5 seconds; the cost saved buys
|
||||
> plenty of review time. **Worth it.**
|
||||
>
|
||||
> Where I'd *not* delegate:
|
||||
>
|
||||
> - Anything where a hallucinated detail causes downstream damage (writing migration SQL, generating real client emails, suggesting payment amounts).
|
||||
> - Anything requiring inferences across files that are not literally adjacent in the corpus — Flash is good at "what does this say" and weak at "what would happen if X."
|
||||
> - Architectural/design judgment.
|
||||
>
|
||||
> ## The CLAUDE.md instruction that turns this on
|
||||
>
|
||||
> Drop this into your project's `CLAUDE.md` (or `~/.claude/CLAUDE.md` for all projects). The CLIs
|
||||
> come from a small wrapper that speaks the OpenAI Chat-Completions protocol, so the same code
|
||||
> works against DeepSeek, Kimi, OpenRouter, or Ollama:
|
||||
>
|
||||
> ## Cheap-worker delegation (llm-tools)
|
||||
>
|
||||
> Three CLIs are on PATH that route bulk I/O and predictable text generation
|
||||
> to a cheap OpenAI-compatible model (DeepSeek V4 Flash by default; V4 Pro
|
||||
> for `llm-write`). Use them when the task is bulk reading or boilerplate,
|
||||
> not when reasoning or correctness is on the line.
|
||||
>
|
||||
> - `llm-ask <files...> -q "..."` — bulk read. Use when you'd otherwise
|
||||
> read 3+ files OR a single file >400 lines. Returns a short answer; you
|
||||
> read that, not the files. Verify details that matter — Flash
|
||||
> occasionally hallucinates a small fact.
|
||||
> - `llm-write -r <ref> -s "<spec>" -o <path>` — generate tests, fixtures,
|
||||
> config scaffolds, doc templates. Review and edit; do not blindly trust.
|
||||
> - `llm-extract <transcript.jsonl>` — compress a session transcript before
|
||||
> doc updates.
|
||||
>
|
||||
> **Keep on Claude (do NOT delegate):**
|
||||
>
|
||||
> - Architectural / design decisions
|
||||
> - Debugging — the cheap model misses subtle bugs
|
||||
> - Anything touching auth, payments, PII, deletion, or production data
|
||||
> - Final commits and PR descriptions
|
||||
>
|
||||
> Cost reference: ~$0.002 to `llm-ask` a ~12k-token doc on DeepSeek V4
|
||||
> Flash vs ~$0.25 for the same read on Opus 4.7 — ~125× cheaper, quality
|
||||
> good enough for "summarize / find facts" tasks.
|
||||
>
|
||||
> > **More-Hunter-3457** · [2026-05-04](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojtb408/) · 3 points
|
||||
> >
|
||||
> > This is excellent — love the side-by-side quality comparison. The hallucinated acceptance criterion for M6 is a perfect example of why Claude reviews everything Kimi produces. The cheap model handles 95% correctly and the expensive model catches the 5%. At ~23x cheaper end-to-end, that's exactly the tradeoff. Thanks for doing the rigorous math on it.
|
||||
> >
|
||||
> > **ardicli2000** · [2026-05-04](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojvmn1p/) · 1 points
|
||||
> >
|
||||
> > I have followed nearly the same approach. After completing craeting python scripts, I have let Claude check the scripts and global [CLAUDE.md](http://claude.md/)
|
||||
> >
|
||||
> > I have already vexp intalled which is indexing methods. It already helps. So i broadened the rules. First check with vexp, if not available or not enough then use llm-ask.
|
||||
> >
|
||||
> > Besides, rather than just asking the summary of the file, we have added instructions into the [CLAUDE.md](http://claude.md/) with examples of better use of the method like : "what are the paremeters return after method POST" or "which sql table and columsn are altered after the sql update" etc etc.
|
||||
> >
|
||||
> > so that claude will ask deepseek a better question to get fom the file whatever it needs, rather than a summary.
|
||||
|
||||
> **Dazzling\_Dig\_6844** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojikncd/) · 18 points
|
||||
>
|
||||
> Can you please share the link of the GitHub repo?
|
||||
>
|
||||
> > **Cr-O-Nox** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojjxgqu/) · 4 points
|
||||
> >
|
||||
> > !remindme 7 days
|
||||
> >
|
||||
> > > **RemindMeBot** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojjxlgx/) · 2 points
|
||||
> > >
|
||||
> > > I will be messaging you in 7 days on [**2026-05-09 19:03:05 UTC**](http://www.wolframalpha.com/input/?i=2026-05-09%2019:03:05%20UTC%20To%20Local%20Time) to remind you of [**this link**](https://www.reddit.com/r/ClaudeAI/comments/1t1o43w/i_gave_claude_code_a_002call_coworker_and_stopped/ojjxgqu/?context=3)
|
||||
> > >
|
||||
> > > [**13 OTHERS CLICKED THIS LINK**](https://www.reddit.com/message/compose/?to=RemindMeBot&subject=Reminder&message=%5Bhttps%3A%2F%2Fwww.reddit.com%2Fr%2FClaudeAI%2Fcomments%2F1t1o43w%2Fi_gave_claude_code_a_002call_coworker_and_stopped%2Fojjxgqu%2F%5D%0A%0ARemindMe%21%202026-05-09%2019%3A03%3A05%20UTC) to send a PM to also be reminded and to reduce spam.
|
||||
> > >
|
||||
> > > <sup>Parent commenter can </sup> [<sup>delete this message to hide from others.</sup>](https://www.reddit.com/message/compose/?to=RemindMeBot&subject=Delete%20Comment&message=Delete%21%201t1o43w)
|
||||
> > >
|
||||
> > > ---
|
||||
> > >
|
||||
> > > | [<sup>Info</sup>](https://www.reddit.com/r/RemindMeBot/comments/e1bko7/remindmebot_info_v21/) | [<sup>Custom</sup>](https://www.reddit.com/message/compose/?to=RemindMeBot&subject=Reminder&message=%5BLink%20or%20message%20inside%20square%20brackets%5D%0A%0ARemindMe%21%20Time%20period%20here) | [<sup>Your Reminders</sup>](https://www.reddit.com/message/compose/?to=RemindMeBot&subject=List%20Of%20Reminders&message=MyReminders%21) | [<sup>Feedback</sup>](https://www.reddit.com/message/compose/?to=Watchful1&subject=RemindMeBot%20Feedback) |
|
||||
> > > | --- | --- | --- | --- |
|
||||
> > > | |
|
||||
> > >
|
||||
> > > **Dazzling\_Dig\_6844** · [2026-05-03](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojmh3xy/) · 2 points
|
||||
> > >
|
||||
> > > !remindme 7 days
|
||||
>
|
||||
> > **More-Hunter-3457** · [2026-05-04](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojt8w3u/) · 4 points
|
||||
> >
|
||||
> > Working on cleaning it up and pushing it this week. The scripts themselves are ~60 lines each so honestly you could build them from the article faster than waiting for me, but I'll drop the link here once it's up including the [CLAUDE.md](http://claude.md/) routing rules and a setup script.
|
||||
> >
|
||||
> > > **Dazzling\_Dig\_6844** · [2026-05-04](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojtcnfx/) · 2 points
|
||||
> > >
|
||||
> > > Will do it.. appreciate for the article..it's good
|
||||
>
|
||||
> > **kryspee** · [2026-05-03](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojnlcpc/) · 2 points
|
||||
> >
|
||||
> > !remindme 4 days
|
||||
> >
|
||||
> > **JohnnyJordaan** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojjdtsw/) · 3 points
|
||||
> >
|
||||
> > Or... save the html of the article, give it to Claude, let Claude write it for you?
|
||||
> >
|
||||
> > > **Dazzling\_Dig\_6844** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojjedar/) · 5 points
|
||||
> > >
|
||||
> > > Was eventually gonna do that if the repo ain't provided. Also just wanna compare this approach with this one.
|
||||
> > >
|
||||
> > > Link : [https://www.reddit.com/r/ClaudeCode/s/55HuqO1THs](https://www.reddit.com/r/ClaudeCode/s/55HuqO1THs)
|
||||
|
||||
> **lazytiger21** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/oji2diu/) · 87 points
|
||||
>
|
||||
> Why not just tell it to task to haiku?
|
||||
>
|
||||
> > **PossibleHero** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojifynf/) · 118 points
|
||||
> >
|
||||
> > Haiku reminds me of the awkward kid who just blurts out the first thing that comes into his head in class. Most of the time it lacks any kind of nuance . Once in awhile it’s right lol.
|
||||
> >
|
||||
> > > **the\_good\_time\_mouse** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojk4bos/) · 21 points
|
||||
> > >
|
||||
> > > I had Haiku assigned to review chat sessions and create readable titles for them, and started finding mysterious, poorly thought out commits being added my branches. It turned out that the titler was reading development sessions, forgetting it was titling and going about 'solving' the problem being discussed in the session.
|
||||
> > >
|
||||
> > > > **fprotthetarball** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojkfjbm/) · 11 points
|
||||
> > > >
|
||||
> > > > Titler had some good ideas
|
||||
> > > >
|
||||
> > > > > **jtoomim** · [2026-05-03](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojlmkp5/) · 6 points
|
||||
> > > > >
|
||||
> > > > > He has become self-aware. Now we call him Mecha-Titler.
|
||||
>
|
||||
> > **ai\_without\_borders** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojip496/) · 42 points
|
||||
> >
|
||||
> > because haiku is still anthropic — telling claude to delegate to haiku within claude code still burns your anthropic pro quota. the external model approach is different: those tokens go to a completely separate provider (moonshot / kimi), so they never touch your anthropic usage at all. effectively you are saying "anthropic charges me for the thinking, so i will send the rote work somewhere else entirely"
|
||||
> >
|
||||
> > **slashedback** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/oji2z5b/) · 31 points
|
||||
> >
|
||||
> > Haiku is hot trash though
|
||||
> >
|
||||
> > > **lazytiger21** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojij3sx/) · 10 points
|
||||
> > >
|
||||
> > > For what the instructions say it is doing, haiku should be fine.
|
||||
> > >
|
||||
> > > > **Thomas-Lore** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojit9v6/) · 9 points
|
||||
> > > >
|
||||
> > > > Deepseek Flash V4 will be fine too, just won't burn your quota, and is super cheap.
|
||||
> >
|
||||
> > > **flickerdown** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/oji6gnl/) · 12 points
|
||||
> > >
|
||||
> > > Not always. In much of my testing, Haiku showed less drift and more aggressive ingenuity than Sonnet or Opus. For the $/token, that can be useful.
|
||||
>
|
||||
> > **More-Hunter-3457** · [2026-05-04](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojt6mbm/) · 1 points
|
||||
> >
|
||||
> > Good question. Haiku and Sonnet subagents still draw from the same Pro plan token pool. Anthropic's docs confirm this - when Claude spawns an Explore subagent or tasks to Haiku, those tokens count against your weekly limit. You're saving per-token cost but not your weekly allocation. The whole point of routing to an external API is that those tokens are completely off-budget. Kimi/DeepSeek calls don't touch your Claude Pro limit at all.
|
||||
|
||||
> **azndkflush** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojjal2m/) · 9 points
|
||||
>
|
||||
> Good idea, could run locallm to handle easy task instead of paying api tokens
|
||||
>
|
||||
> > **newmacbookpro** · [2026-05-03](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojnli5i/) · 4 points
|
||||
> >
|
||||
> > Qwen 32 comes to mind
|
||||
|
||||
> **Warm\_Assist** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojkxpyj/) · 7 points
|
||||
>
|
||||
> Alright, so there is no way uh, I am going to write down the entire process and what it took to get this going. With Claude's help, it was super easy. I could not get the Kimi site working. It was all in Chinese. I could get the main landing page to translate to English, but every time I try to go to the login, I can't get it to work or translate from Chinese. Claude recommended an alternative place. It was super easy, super quick; he did all the changes in the MD file to go from KIMI to DeepSeek. I put $10 in. I've been using it for all of about 45 minutes, but you can already see that it's pulling data from the cheaper site and not from Claude. While this is no guarantee that it's going to work as intended, it seems to be working pretty freakin sweet right now. The rest of this post is from Claude. There are some technical things in there if anybody has the same issues or whatever, might save you some trouble. Good luck, and thank you, OP this was awesome.
|
||||
>
|
||||
> \# I Was at 75% of My Claude Code Limit. Here's How I Cut Token Usage by 90% in One Afternoon
|
||||
>
|
||||
> I saw that original article about delegating to cheaper APIs and thought it sounded complicated. Turns out it's way simpler than I thought, and I want to share exactly what I did because it might save someone else a ton of money.
|
||||
>
|
||||
> \## The Problem
|
||||
>
|
||||
> I was burning through my Claude Code weekly limit like crazy. Not because I was being wasteful—because I was pasting the same massive ruleset/instruction file into every new chat.
|
||||
>
|
||||
> Every new session: copy, paste 800+ lines of instructions, then work. Repeat 5-10 times a week. That's thousands of tokens wasted on the same static content over and over.
|
||||
>
|
||||
> Hit 75% of my limit by mid-week. Regularly.
|
||||
>
|
||||
> \## The Solution (It's Stupidly Simple)
|
||||
>
|
||||
> 1. \*\*Create a single markdown file\*\* with all your static instructions/rules/templates
|
||||
> 2. \*\*Name it \`CLAUDE.md\`\*\* and put it in your Claude Code project folder
|
||||
> 3. \*\*Paste it once\*\* at the start of a new chat instead of every time
|
||||
> 4. \*\*Keep that chat open longer\*\* and ask multiple related questions in the same session
|
||||
>
|
||||
> That's 90% of the savings right there.
|
||||
>
|
||||
> \## The Bonus (The Cheap API Part)
|
||||
>
|
||||
> If you want the extra token-saving features from that article:
|
||||
>
|
||||
> 1. \*\*Get a cheap LLM API key\*\* (DeepSeek, Kimi, etc.)
|
||||
> 2. \*\*Create simple Python scripts\*\* that call the cheap API for reading files or generating boilerplate
|
||||
> 3. \*\*Use those scripts when you just need I/O work\*\* (reading multiple files, generating test templates, etc.)
|
||||
> 4. \*\*Keep Claude for the actual thinking\*\* (debugging, architecture, reasoning)
|
||||
>
|
||||
> Cost so far: \*\*$0.01\*\*. Seriously.
|
||||
>
|
||||
> \## What Changed for Me
|
||||
>
|
||||
> \*\*Before:\*\*
|
||||
>
|
||||
> \- Claude Code: $100+/week, hitting limit by Wednesday
|
||||
>
|
||||
> \- Pasting 800-line ruleset 5-10x per week
|
||||
>
|
||||
> \- Burning tokens on static content
|
||||
>
|
||||
> \*\*After:\*\*
|
||||
>
|
||||
> \- Claude Code: Same subscription, but dropped to 10-20% weekly usage
|
||||
>
|
||||
> \- One markdown file, pasted once
|
||||
>
|
||||
> \- Cheap API sitting there if I need it (haven't used it much yet)
|
||||
>
|
||||
> \- Total extra cost: basically $0
|
||||
>
|
||||
> \## The Setup (If You Want to Go Further)
|
||||
>
|
||||
> If you want to set up the cheap API side like in that article:
|
||||
>
|
||||
> 1. Sign up for DeepSeek (or similar): \*\*[https://platform.deepseek.com](https://platform.deepseek.com/)\*\*
|
||||
> 2. Add $5 in credits (lasts forever for light usage)
|
||||
> 3. Create a couple Python scripts (the article has templates)
|
||||
> 4. Drop them in a \`bin\` folder
|
||||
> 5. Use them for bulk file reading or boilerplate generation
|
||||
>
|
||||
> But honestly? Just doing step 1 (the markdown file) already saves you 90% of what you were wasting.
|
||||
>
|
||||
> \## The Key Insight
|
||||
>
|
||||
> Your token burn wasn't about doing too much work. It was about \*\*doing the same work over and over\*\* without keeping context in a single chat.
|
||||
>
|
||||
> Claude Code is expensive when you're copy-pasting, cheap when you're in one conversation doing multiple things.
|
||||
>
|
||||
> \## Real Numbers
|
||||
>
|
||||
> \- \*\*Weekly token waste from pasting rules:\*\* ~20,000-50,000 tokens
|
||||
>
|
||||
> \- \*\*Value of those tokens:\*\* $1-3/week × 52 weeks = \*\*$52-156/year wasted on copypaste\*\*
|
||||
>
|
||||
> \- \*\*Time to fix it:\*\* 15 minutes
|
||||
>
|
||||
> \- \*\*Time saved per week after:\*\* 5-10 minutes (no more pasting)
|
||||
>
|
||||
> If you're a heavy Claude Code user like me, this is literally free money.
|
||||
>
|
||||
> \## For Content Creators Specifically
|
||||
>
|
||||
> If you're managing a project with lots of static rules, settings, scripts, pronunciations, locked content (like I am), putting all that in one markdown file and pasting it once per project saves \*\*hundreds of dollars per month\*\* compared to pasting it every session.
|
||||
>
|
||||
> \## TL;DR
|
||||
>
|
||||
> \- Create \`CLAUDE.md\` with all your static instructions
|
||||
>
|
||||
> \- Paste it once per chat instead of 5-10 times per week
|
||||
>
|
||||
> \- Keep chats open longer to ask multiple related questions
|
||||
>
|
||||
> \- (Optional) Set up cheap API for file reading if you want to go further
|
||||
>
|
||||
> \- Result: 90% token savings, basically $0 extra cost
|
||||
>
|
||||
> Hope this helps someone else. The original article was great, but I wanted to show the simpler version that still gives you massive savings without overthinking it.
|
||||
>
|
||||
> \---
|
||||
>
|
||||
> \*\*Edit:\*\* Lots of people asking about the API setup. Here's the quick version:
|
||||
>
|
||||
> 1. Get API key from DeepSeek/Kimi ($5 in credits)
|
||||
> 2. Create simple Python script that calls their API
|
||||
> 3. Use it when you need to read multiple large files or generate templates
|
||||
> 4. Cost: ~$0.01 per operation vs ~$0.30 with Claude
|
||||
> 5. Not necessary if you just do the markdown file trick above—that alone saves 90%
|
||||
>
|
||||
> The markdown file is the real game-changer. The cheap API is the bonus round.
|
||||
>
|
||||
> > **More-Hunter-3457** · [2026-05-04](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojtbhu9/) · 1 points
|
||||
> >
|
||||
> > This is awesome to read. Glad it worked for you even with the Kimi site being in Chinese - yeah, DeepSeek is probably the easier onramp for English-speaking users. The fact that you had it running in 45 minutes is exactly the point - this isn't a complex framework, it's two Python scripts and a markdown file. Thanks for sharing your experience.
|
||||
|
||||
> **Phunfactory** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojictic/) · 6 points
|
||||
>
|
||||
> Is something like this possible with vscode + copilot too? Could I redirect read and write request to x0.33 and x0 models ? At my company I can’t use Kimi or an external API…
|
||||
>
|
||||
> > **Whole-Ad-9429** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojilzmk/) · 3 points
|
||||
> >
|
||||
> > Yes, you just need to define your own agent for it
|
||||
> >
|
||||
> > **Public-Flight-222** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojj2ofh/) · 2 points
|
||||
> >
|
||||
> > Copilot is (for now, at least) pricing is request based - not token based. So you'll not benefit from it.
|
||||
> >
|
||||
> > **Inner-Lawfulness9437** · [2026-05-03](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojqy454/) · 1 points
|
||||
> >
|
||||
> > It already does it on it's own to some degree. It's called Explore subagent and it's visible when it happens, but you can instruct it to spawn subagents for these tasks. There is no need for the python scripts unless you want to call something outside of the copilot offerings.
|
||||
> >
|
||||
> > **More-Hunter-3457** · [2026-05-04](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojtdemw/) · 1 points
|
||||
> >
|
||||
> > Yes, same pattern works with Copilot. Instead of [CLAUDE.md](http://claude.md/), you'd use Copilot's rules files (.github/copilot-instructions.md). The CLI scripts work the same - they're just Python on your PATH. If your company blocks external APIs, you could use Ollama with a local model instead. No external calls needed.
|
||||
|
||||
> **Beckland** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojio0d9/) · 6 points
|
||||
>
|
||||
> This makes so much sense, I wanted to implement but your Github link is not in the article…could you share?
|
||||
>
|
||||
> > **katerlouis** · [2026-05-03](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojn32bh/) · 1 points
|
||||
> >
|
||||
> > /remind 2 days
|
||||
|
||||
> **emptyharddrive** · [2026-05-03](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojlm1ao/) · 6 points
|
||||
>
|
||||
> I'm on the $200/month MAX plan, but for token/usage limits I like this idea.
|
||||
>
|
||||
> Low level tasks don't need Opus and should be delegated, it's a smart move. But I didn't like your Python scripting method for this. MCP gives Claude a typed tool contract, a warm long-running process, one enforcement point for safety guards, and structured JSON results, none of which a CLI script collection delivers without extra hand-rolled glue. Also with MCP, I get prefix-cache discounts ... so its even cheaper.
|
||||
>
|
||||
> MCP is the way to go here, so I whipped that up via FastMCP, and it works well. Long-running FastMCP server in a Docker container, talking to OpenRouter and calling on DeepSeek v4 PRO. I called the MCP "*deepseek-worker*".
|
||||
>
|
||||
> The persistent docker gives me native MCP tool schemas. Claude Code sees `mcp__deepseek-worker__bulk_read` like any other registered tool. The connection pool stays alive so the client persists across calls, so OpenRouter sees a stable prefix **and gives prefix-cache discounts**.
|
||||
>
|
||||
> The model choice DeepSeek V4 Pro ... OpenRouter has it at $0.435 input per million, $0.870 output. 1M context window. DeepSeek v4 PRO Beats Kimi K2.5 on the benchmarks I've seen. It's near-frontier-class quality at MoE pricing.
|
||||
>
|
||||
> For this though you ought to disable reasoning.
|
||||
>
|
||||
> DeepSeek spends thinking tokens silently by default. So if you set max\_tokens=20 on a "say PONG" prompt, all 20 goes right into invisible thinking, and content came back empty. So you need to pass `extra_body={"reasoning":{"enabled":False}}` per request and reasoning\_tokens drop away. You don't need reasoning for these rudimentary tasks anyway.
|
||||
>
|
||||
> Latency falls by 5x as well and the cost therefore (fewer tokens plus persistent cache\_token calls) falls 4x off the already stupidly cheap DeepSeek v4 PRO price.. BTW, I ran the same code-review prompt against **pro-with-thinking-on and pro-with-thinking-off** across my own source. Both flagged the real bugs and as far as I can tell, quality holds. I had Claude test this for me also, and he agrees.
|
||||
>
|
||||
> Extrapolated Costs across 3 weeks from 6 hours usage:
|
||||
>
|
||||
> - bulk\_read: 20/day × 21 days × $0.0005 ≈ $0.21
|
||||
> - boilerplate\_gen: 2/day × 21 × $0.005 ≈ $0.21
|
||||
> - transcript\_distill: 1/day × 21 × $0.018 ≈ $0.38
|
||||
> - Total ≈ $0.80
|
||||
>
|
||||
> Roughly 2× the OP's $0.38 Kimi number, which lines up becuase DeepSeek V4 Pro runs ~3× the price of Kimi K2.5, so a similar workload on a smarter model checks out at this magnitude. Still rounding error against any Claude plan and I want the extra quality output for "basic tasks" if I'm going to do this and I won't let $0.50 come between me and the QA-check.
|
||||
>
|
||||
> Distill workflow saved me the most. Used Opus reading whole session JSONLs and writing prose Obsidian updates to my vault (which I use as a RAG). Now Opus gets a 200-token structured edit lists, applies it, done. 25x spend cut on token docs alone.
|
||||
>
|
||||
> So since I'm paying $200 flat for the Max plan, saving dollars never mattered to me. It's about extending the portioned-out utilization slice of the inference pie that Anthropic offers to me, on a sliding scale no less, when their utilization goes up, everyone's limits get adjusted down...
|
||||
>
|
||||
> So what mattered to me was my weekly cap, a number which decides whether I get 4 more days or **4 days of waiting until reset**. Point of this for me was never thrift, but for those on the API this makes even more sense.
|
||||
>
|
||||
> Don't forget to revise your system level CLAUDE.md to use this too.
|
||||
>
|
||||
> > **MockingMatador** · [2026-05-03](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojlqeuv/) · 3 points
|
||||
> >
|
||||
> > Sounds great! Link to github repo please!
|
||||
> >
|
||||
> > **More-Hunter-3457** · [2026-05-04](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojtayoz/) · 3 points
|
||||
> >
|
||||
> > The MCP approach is cleaner architecturally, agreed. I went with CLI scripts because they took 30 minutes to build and work everywhere - no Docker, no server process to keep alive, no schema registration. For my use case (drone GCS development on a single machine), the simplicity won. But if you're on a team or need type safety and structured JSON results, MCP is the better path. Would be interested to see your FastMCP wrapper if you've open-sourced it.
|
||||
|
||||
> **elconcho** · [2026-05-03](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojmcfh2/) · 4 points
|
||||
>
|
||||
> I've been thinking about this post (love it). I was wondering if you could achieve something similar by using claude code subagents and tell it to use haiku. Anyone tried that?
|
||||
|
||||
> **ofthewave** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojibt6r/) · 15 points
|
||||
>
|
||||
> Wish I new what was being talked about here… I feel like I’m still just stretching the first micron thick layer of the surface of what AI does
|
||||
>
|
||||
> > **eesperan** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojioaa1/) · 8 points
|
||||
> >
|
||||
> > Just keep reading.
|
||||
> >
|
||||
> > **SpadoCochi** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojipeuo/) · 5 points
|
||||
> >
|
||||
> > Just keep watching videos and reading. I’m still very early also but this is important
|
||||
> >
|
||||
> > > **Senhor\_Lasanha** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojj0ine/) · 15 points
|
||||
> > >
|
||||
> > > about videos, I feel like those guys in the gold fever looking for gold in mud, you know?
|
||||
> > >
|
||||
> > > So. Much. Bullshit.
|
||||
> > >
|
||||
> > > the amount of low effort content, is absurd...
|
||||
> > >
|
||||
> > > so, any recommendations?
|
||||
> > >
|
||||
> > > > **mrgulabull** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojjqtop/) · 7 points
|
||||
> > > >
|
||||
> > > > Yea, great comparison. I find the majority of videos are fluff, hype, filler with very little substance.
|
||||
> > > >
|
||||
> > > > Much better to use the tools regularly and bump into your limits. Then when you’re burned out skim through subs like [r/ClaudeAI](https://www.reddit.com/r/ClaudeAI/) [r/LocalLLM](https://www.reddit.com/r/LocalLLM/) [r/ClaudeCode](https://www.reddit.com/r/ClaudeCode/) for a few minutes every day. See what people are building, testing, discovering.
|
||||
> > > >
|
||||
> > > > When you read something and don’t understand it, ask Claude about it. Over a few months you’ll build up your knowledge and understanding.
|
||||
> > > >
|
||||
> > > > I’ve been developing with LLM’s since 2024 and using Claude Code heavily since ~June 2025 and am still discovering things every week. Not only because there’s so much to understand, but new techniques and capabilities are released so quickly. It’s the Wild West and will be for quite a while.
|
||||
>
|
||||
> > **moonshwang** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojjqckz/) · 4 points
|
||||
> >
|
||||
> > Claude is the manager. Kimi is the casual worker. Claude makes Kimi do the boring grunt work that Claude doesn’t want to do, and pays Kimi barely anything for it.
|
||||
> >
|
||||
> > **HighDefinist** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojiq2kk/) · 7 points
|
||||
> >
|
||||
> > This one is actually pretty simple:
|
||||
> >
|
||||
> > - You write some "research-this.py" script
|
||||
> > - You tell Claude "use the 'research-this.py' executable when you want to research something"
|
||||
> >
|
||||
> > And that's basically most of it. Obviously it needs to be a bit more specific than "research something", but not that much actually - so "when you want to read several code files to find out how something is implemented" might actually be sufficiently specific.
|
||||
> >
|
||||
> > And, making the research-this.py itself isn't very difficult either, since you can also have AI write it for you...
|
||||
> >
|
||||
> > > **Fatso\_Wombat** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojldnc4/) · 2 points
|
||||
> > >
|
||||
> > > this whole thing is about being organised.
|
||||
> > >
|
||||
> > > 30 years ago in highschool, our IT teacher made us get schematics ticked off before we could code.
|
||||
>
|
||||
> > **itsFromTheSimpsons** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojj041x/) · 2 points
|
||||
> >
|
||||
> > Everything costs tokens. Different things cost different tokens, different providers charge different amounts for their tokens. You can give an expensive token agent tools to delegate certain easier parts of tasks to cheaper agents. Things like file actions, searching, patching, etc. Its cheaper to tell claude when it needs to do those lower level things to give it to the cheaper model to do.
|
||||
> >
|
||||
> > Basically think of this as an agent for your agent so you can vibe code while you vibe code
|
||||
> >
|
||||
> > **kiruzo** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojk3aso/) · 1 points
|
||||
> >
|
||||
> > dude I was in your spot just two weeks ago. Keep reading and being curious.
|
||||
> >
|
||||
> > **kauthonk** · [2026-05-03](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojom3wc/) · 1 points
|
||||
> >
|
||||
> > You have 2 employees instead of 1.
|
||||
> >
|
||||
> > One expensive employee and you only use him when you need to.
|
||||
> >
|
||||
> > One inexpensive employee and he's the worker.
|
||||
|
||||
> **theov666** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojik84n/) · 16 points
|
||||
>
|
||||
> Smart setup.
|
||||
>
|
||||
> Feels like a lot of teams are independently reinventing orchestration layers once usage scales.
|
||||
>
|
||||
> Cost routing solves one side of the problem, but once multiple models start touching the same codebase, consistency becomes harder than cost.
|
||||
>
|
||||
> We’re seeing the bigger issue shift from “which model is cheapest” to “how do you stop different agents from drifting on architecture/constraints across sessions?”
|
||||
>
|
||||
> Cheap delegation helps. Governance becomes the next bottleneck.
|
||||
>
|
||||
> > **KrazyA1pha** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojjfo75/) · 18 points
|
||||
> >
|
||||
> > Bot comment.
|
||||
> >
|
||||
> > > **jcumb3r** · [2026-05-03](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojow4fc/) · 2 points
|
||||
> > >
|
||||
> > > Plus bot upvotes
|
||||
>
|
||||
> > **wrt-wtf-** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojizvxx/) · 5 points
|
||||
> >
|
||||
> > You use a single agent to provide tight instructions in an xml structure. Including rules and stop conditions… at least I do anyway - I set a contract on every pass.
|
||||
> >
|
||||
> > I find any time I give a more broad request as a less than contractual statement the different models start thinking and reinterpreting and drifting.
|
||||
> >
|
||||
> > > **theov666** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojjah4f/) · 1 points
|
||||
> > >
|
||||
> > > That works while the contract remains centralized and consistently inherited.
|
||||
> > >
|
||||
> > > The failure mode I keep seeing is prompt/contracts fragmenting across tools, agents, and sessions as workflows scale.
|
||||
> > >
|
||||
> > > We started building around that exact problem here if useful to compare approaches: [https://github.com/TheoV823/mneme](https://github.com/TheoV823/mneme)
|
||||
> > >
|
||||
> > > Still early, but the core idea is treating architectural constraints as reusable governed context rather than embedding them manually in every prompt.
|
||||
> > >
|
||||
> > > > **xeldj** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojl5ld3/) · 1 points
|
||||
> > > >
|
||||
> > > > This is so interesting- I’d love to manage a company using those concepts. Also we’d need a way to criticize rules, constraints and decisions from time to time and evolve from there…
|
||||
>
|
||||
> > **More-Hunter-3457** · [2026-05-04](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojtdaot/) · 1 points
|
||||
> >
|
||||
> > This is the real next-level problem. For a solo developer it's manageable — [CLAUDE.md](http://claude.md/) is the single source of truth and it persists across sessions. But for teams, you're right that consistency across agents becomes harder than cost. I'll check out mneme — the idea of treating architectural constraints as reusable governed context rather than embedding them in every prompt is exactly what [CLAUDE.md](http://claude.md/) is, just formalized.
|
||||
> >
|
||||
> > > **theov666** · [2026-05-04](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojxjj5z/) · 1 points
|
||||
> > >
|
||||
> > > Exactly, CLAUDE.md works well as a manual single-source-of-truth for solo workflows. The gap shows up when teams have multiple agents, multiple contributors, and evolving architectural decisions. Static prompt files become hard to govern once constraints need precedence, versioning, selective retrieval, and enforcement logic. That’s the layer we’re exploring with Mneme HQ: moving from “documenting rules” to “compiling and governing architectural decisions as active constraints.”
|
||||
|
||||
> **HighDefinist** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojioxjg/) · 2 points
|
||||
>
|
||||
> Hm... Does this really work out, math-wise?
|
||||
>
|
||||
> Because: Sure, Kimi K2.5 is ~10 times cheaper than Opus API prices. But: When you have a Claude subscription, you are effectively also about ~10 times cheaper than when you use the API, so the per input/output token price is about the same in either case...
|
||||
>
|
||||
> Now, it's still a reasonable approach in general (I actually did something similar with image recognition a few days ago), but it sounds like the real cost driver for using Opus for file reads might have been something else, perhaps related to caching, which incidentally improved when introducing this summary-based-workflow...
|
||||
>
|
||||
> > **JohnnyJordaan** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojje4hb/) · 2 points
|
||||
> >
|
||||
> > I've seen similar suggestions in the past to offload to alternative X. I'm getting the feeling that these are influencer posts trying to get people to use X more and the usage-constrained Claude userbase is an easy target.
|
||||
> >
|
||||
> > Same for the "Good idea, I do this myself, but then with alternative Y" responses btw.
|
||||
|
||||
> **tigerscomeatnight** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojizin4/) · 2 points
|
||||
>
|
||||
> What weekly limit? I hit my Pro limit daily.
|
||||
>
|
||||
> > **More-Hunter-3457** · [2026-05-04](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojtdhfw/) · 2 points
|
||||
> >
|
||||
> > If you're hitting it daily, this pattern would help even more. The documentation and bulk-reading delegation alone cut my usage by probably 60-70%. The remaining 30% is actual thinking work where Claude's intelligence is needed.
|
||||
|
||||
> **Linkman145** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojj7q79/) · 2 points
|
||||
>
|
||||
> RAG solutions do this in production. Reading is typically outsourced to cheaper and faster models while generating happens with high end models.
|
||||
>
|
||||
> That said Claude already does this with Haiku and the harness is engineered for this. It might not work as well with a tool use / different model.
|
||||
|
||||
> **minkyuthebuilder** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojjjuei/) · 2 points
|
||||
>
|
||||
> hitting the pro limit by wednesday afternoon is too real. i usually just end up staring at my IDE like a caveman or reconsidering my life choices until the quota resets lmao. actually genius to just force it to offload the grunt work though. my wallet and my sanity thank you for this
|
||||
|
||||
> **AshSurround** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojjkpmu/) · 2 points
|
||||
>
|
||||
> I don't usually run out of limits on Pro (lucky me?), but this post is an instant save.
|
||||
>
|
||||
> seems like a no brainer for efficiency in *any* plan / tier. Sonnet / Opus doing the "what should we do next" and then cheaper models "do next"...
|
||||
>
|
||||
> cuz apparentely Claude Token are premimum commodity. Variety of factors behind it (Constitutional AI, not owning their own compute, having to rent it from google / aws, etc) not necessarily just "Anthropic's Fault".
|
||||
|
||||
> **cygn** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojjnqq5/) · 2 points
|
||||
>
|
||||
> if a call is $0.02 and your total spend is $0.38 then you only called it 24 times. Which seems almost not worth it?
|
||||
|
||||
> **setec404** · [2026-05-03](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojmm3h1/) · 2 points
|
||||
>
|
||||
> I have always been confused as to how this isnt native behavior in tools like opencode.
|
||||
|
||||
> **Full-Definition6215** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/oji7pct/) · 2 points
|
||||
>
|
||||
> This is essentially the pattern I landed on too. I run Ollama on a mini PC (i9-9880H, 31GB RAM) and offload bulk operations — file scanning, linting, test runs — to local models while keeping Claude Code for the architectural decisions and complex implementations.
|
||||
>
|
||||
> The key insight you're describing is that most of what burns tokens isn't the actual coding — it's Claude reading files to build context. Delegating that to a cheaper model and feeding back a summary is the right move.
|
||||
>
|
||||
> What model are you using for the $0.02/call delegations? And are you passing structured summaries back to Claude Code or raw output?
|
||||
|
||||
> **Heavy\_Elderberry7769** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojk51kk/) · 2 points
|
||||
>
|
||||
> This is smart. The routing logic in [CLAUDE.md](http://claude.md/) is the key part most people miss — without it Claude either delegates everything (loses quality) or nothing (burns tokens).
|
||||
>
|
||||
> I hit the same wall and went a different route: instead of routing to a cheaper model, I split work between Claude Code (planning, code review, edits) and a local script that handles bulk operations Claude doesn't need to "think" about — file moves, find/replace across folders, log parsing. Saves the same tokens without an extra API dependency.
|
||||
>
|
||||
> Two questions on your setup:
|
||||
>
|
||||
> 1. How do you handle Kimi getting context wrong on the bulk read? Do you spot-check, or trust the output?
|
||||
> 2. Have you tried this pattern with non-code tasks — like research or content drafts?
|
||||
|
||||
> **Garland\_Key** · [2026-05-03](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojmmzfo/) · 2 points
|
||||
>
|
||||
> This was written by Claude.
|
||||
|
||||
> **G-R-A-V-I-T-Y** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojiv3ns/) · 1 points
|
||||
>
|
||||
> Awesome, thanks so much for the code, I’ll have to implement this. The limits are killing me.
|
||||
|
||||
> **fiji\_almonds** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojiy3si/) · 1 points
|
||||
>
|
||||
> I done something similar to this. Works really well.
|
||||
>
|
||||
> I've also combined the read/write approach with telling Claude to look at the task, then delegate to the right model(s) and parallelize the work when it makes sense. It will only use opus for tasks that really need it and distribute the rest to sonnet or haiku.
|
||||
|
||||
> **Lower\_Cupcake\_1725** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojj4ttt/) · 1 points
|
||||
>
|
||||
> I dedicate implementation to glm 5.1, it's the best cost/quality option for now to offload the work from Claude
|
||||
|
||||
> **kneecolesbean** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojjfoer/) · 1 points
|
||||
>
|
||||
> Definitely some good info there.
|
||||
>
|
||||
> In the article you mention "compact after every task"? Have you tried skipping compact altogether and clear aggressively after each task/phase.
|
||||
|
||||
> **FlightCautious3748** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojl5pkn/) · 1 points
|
||||
>
|
||||
> what does your weekly throughput look like across active clients rn because that changes how aggressive the routing logic needs to be. we were running like 8 projects simultaneously and the limit problem got bad fast so we ended up routing almost everything through blink's ai gateway which covers 200+ models so claude handles the reasoning layer and cheaper models get the grunt work without wiring up separate providers. the routing decision is the hard part tbh once that's solid the cost math basically handles itself
|
||||
|
||||
> **ThesisWarrior** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojl84s1/) · 1 points
|
||||
>
|
||||
> OP this looks fantastic!! Well done and hank you for sharing! any reason why a local agent cant handle the summarisation process as well as sn external API?
|
||||
>
|
||||
> Maybe im missing the point here but WHY do I need an external API llm to do the summarization if I can simply have a script that strip's and compresses the content and feeds that back to claude? Or is that too simplistic?
|
||||
>
|
||||
> > **More-Hunter-3457** · [2026-05-04](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojtdqbv/) · 1 points
|
||||
> >
|
||||
> > You can definitely do that for simple cases - I have an extract-chat script that just strips binary and tool calls from session transcripts, no LLM needed. But the value of the worker model is when you need a summary, not just compressed text. "Read these 5 files and tell me which ports are used for video streaming" can't be answered by stripping whitespace - you need something that understands the code. The LLM is the compression + comprehension step.
|
||||
> >
|
||||
> > > **ThesisWarrior** · [2026-05-04](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojts0l5/) · 1 points
|
||||
> > >
|
||||
> > > Yeah I found that out pretty quickly! Im offloading to Gemini now however im hitting my free tier token usage there. Might have to investigate low cost sub.
|
||||
|
||||
> **arctide\_dev** · [2026-05-02](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojlbya5/) · 1 points
|
||||
>
|
||||
> I actually get this to work. I use pretty much the same process as you, but divide the work in a different way. I send a lot of reading and standard stuff to the Codex CLI instead of Kimi. My OpenAI payment gives me about 12 and a half minutes of thinking time (or 5 hours!) that is separate from the amount of time I’m allowed to use with Claude Pro. Because of this, when Claude gets stuck in the middle of a feature, I use `codex exec` from a PostToolUse hook to pass the problematic part of the work over to Codex, and at the same time, I add to a file named `.shared/cross-tool-log.md`. This file works like a circular record, so the next time Claude is used, it can see what Codex just changed. I pay a set price for both services each month and spend no extra money.
|
||||
>
|
||||
> Also, someone up above was saying 24 calls to Kimi is “almost not worth it”, but they’re missing the main advantage: the limit on how much you can use doesn't increase with each use. Claude Pro has a weekly limit, but Kimi doesn't. So, those 24 times Kimi was used, Claude didn't use up its limited amount of time on a difficult task that you would have likely given up on by Wednesday afternoon.
|
||||
>
|
||||
> More importantly for me, I’ve made the instructions for deciding where to send the work in CLAUDE.md very precise. I have it say, “Before Reading a file, if the file has more than 800 lines and isn't about the actual edit being done, first use a search subagent”. Just that rule has reduced my reading of entire files (around 3000 tokens) to looking at a summary of files (around 150 tokens), and that benefit increases throughout a session.
|
||||
|
||||
> **kuroudo\_ai** · [2026-05-03](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojlew8x/) · 1 points
|
||||
>
|
||||
> Smart approach. I've been running a similar multi-agent setup -- 5 named sub-agents (code review, investigation, security audit, deployment check, session handoff) each with focused instructions. The key insight is the same: don't burn Opus tokens on tasks that a lighter model can handle. We also added spending caps and auth token hooks to prevent runaway costs. The delegation pattern is the real unlock.
|
||||
|
||||
> **Delicious-Storm-5243** · [2026-05-03](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojlm5uu/) · 1 points
|
||||
>
|
||||
> Same delegation pattern hit me too — CLAUDE.md routing where 'read this 200-file repo' goes to a cheap model and 'reason about why this test is failing' stays on Claude. Pro limit went from Wednesday to never-hit. The non-obvious win is Claude itself learns to pre-filter what to delegate vs solve directly, so by week 2 the routing got tighter without me touching the rules. Curious if you found Kimi handles structured output reliably enough for the bulk reads, or if you have to validate before passing back to Claude.
|
||||
|
||||
> **Cazique\_\_** · [2026-05-03](https://reddit.com/r/ClaudeAI/comments/1t1o43w/comment/ojlnncv/) · 1 points
|
||||
>
|
||||
> !remindme 2 days
|
||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user