TaskFlow — демо-проєкт «З чого складається Claude Code»

Навчальний приклад для вебінару. Це абстрактний проєкт (SaaS для керування задачами, монорепо), єдина мета якого — на одному місці показати всі поверхні конфігурації Claude Code і як вони пов'язані. Сам застосунок не запускається (скрипти — заглушки); цінність — у папці .claude/ та супутніх файлах.

Усі файли проєкту (гайдлайни, конфіги, агенти, команди, скіли, хуки) — англійською, як у реальному репозиторії. Цей README — українською, як гід для глядача.

Як проводити по цьому на вебінарі

Відкрий дерево й проходь зверху вниз — порядок співпадає з логікою плану вебінару: механізм → інструменти → конфігурація. Кожен файл прокоментований зсередини.

Дерево проєкту та що демонструє кожен файл

example/
├── CLAUDE.md                      # Guidelines: системний промпт проєкту (#import, конвенції, заборони)
├── CLAUDE.local.md                # Особистий контекст, НЕ комітиться
├── .mcp.json                      # MCP-сервери проєкту: http / stdio, ${ENV}, alwaysLoad
├── .env.example                   # ENVs: модель, effort, компакція, Bash, MCP, приватність
├── .gitignore                     # що комітимо, а що ні (settings.local, CLAUDE.local)
├── package.json                   # каркас монорепо (workspaces) + npm-скрипти
├── CHANGELOG.md                   # ціль для skill `changelog`
│
├── .claude/
│   ├── settings.json              # КОМАНДНІ налаштування: permissions(allow/ask/deny), env, hooks, mcp
│   ├── settings.local.json        # ОСОБИСТІ оверрайди (НЕ комітиться): інша модель, DATABASE_URL
│   ├── settings.annotated.jsonc   # та сама конфігурація з коментарями (для навчання)
│   ├── managed-settings.example.json # ENTERPRISE рівень: deny непробивний, проксі, allowed/deniedMcpServers
│   │
│   ├── agents/                    # СУБАГЕНТИ — від мінімального до «kitchen sink»
│   │   ├── debugger.md            #   мінімум: лише name + description
│   │   ├── code-reviewer.md       #   звужені tools, model, color, effort
│   │   ├── db-reader.md           #   ПОВНИЙ frontmatter: disallowedTools, mcpServers, hooks, skills, memory, maxTurns
│   │   ├── security-auditor.md    #   isolation: worktree (ізольована копія репо)
│   │   └── researcher.md          #   дешева модель haiku, web-інструменти, background
│   │
│   ├── commands/                  # КАСТОМНІ СЛЕШ-КОМАНДИ ($ARGUMENTS, argument-hint, allowed-tools)
│   │   ├── review.md              #   /project:review [file]
│   │   ├── test-gen.md            #   /project:test-gen <module>
│   │   ├── deploy-check.md        #   pre-deploy чекліст
│   │   ├── refactor.md            #   команда, що запускає dynamic workflow
│   │   └── standup.md             #   без аргументів
│   │
│   ├── skills/                    # SKILLS — SKILL.md + ресурси
│   │   ├── sql-best-practices/    #   чистий промпт-скіл
│   │   ├── api-endpoint/          #   SKILL.md + template.ts (ресурс)
│   │   └── changelog/             #   SKILL.md + допоміжний скрипт
│   │
│   ├── rules/                     # RULES — модульні path-scoped інструкції в системний промпт
│   │   ├── code-style.md          #   без paths → діє завжди (як секція CLAUDE.md)
│   │   ├── api.md                 #   paths: packages/api/**/*.ts
│   │   ├── testing.md             #   paths: **/*.test.{ts,tsx}
│   │   ├── security.md            #   paths: auth/** + payments/** (scoping пріоритету)
│   │   ├── legacy.md              #   paths: packages/legacy/**
│   │   └── frontend/react.md      #   вкладена тека (рекурсивне виявлення)
│   │
│   ├── hooks/                     # HOOKS — детерміновані shell-скрипти на події lifecycle
│   │   ├── audit-bash.sh          #   PreToolUse: аудит-лог кожної Bash-команди
│   │   ├── block-prod-branch.sh   #   PreToolUse: блокує git-мутації в main (exit 2)
│   │   ├── format-on-write.sh     #   PostToolUse(Write|Edit): prettier після запису
│   │   ├── run-tests.sh           #   Stop: ганяє тести, коли агент завершує
│   │   └── block-writes.sh        #   PreToolUse для db-reader: забороняє мутуючий SQL
│   │
│   └── workflows/
│       └── audit-endpoints.md     # DYNAMIC WORKFLOW: план-як-код, паралельні агенти + верифікація
│
├── packages/                      # SCOPES (directory-scoped CLAUDE.md складаються вгору)
│   ├── api/CLAUDE.md              #   правила лише для API-пакета
│   ├── web/CLAUDE.md              #   правила лише для web-пакета
│   └── legacy/CLAUDE.md           #   ⚠️ «обережно, старий код» — додає застереження
│
├── docs/                          # підключаються в кореневий CLAUDE.md через #import
│   ├── architecture.md
│   └── conventions.md
│
└── user-scope-examples/           # USER / GLOBAL scope — те, що живе в ~/.claude/
    └── dot-claude/                # (мапиться на ~/.claude/; названо dot-claude, щоб
        ├── settings.json          #   не плутати з реальним .claude цього проєкту)
        ├── CLAUDE.md              #   особисті глобальні інструкції
        ├── rules/preferences.md   #   user-level Rules (вантажаться перед проєктними)
        ├── commands/standup.md
        └── agents/explore-notes.md

Карта «концепція → де подивитися»

Концепція Claude Code	Файл(и) у прикладі
Guidelines (CLAUDE.md)	CLAUDE.md, packages/*/CLAUDE.md, CLAUDE.local.md
Imports у CLAUDE.md	CLAUDE.md (#import) → docs/*.md
Rules (path-scoped)	.claude/rules/*.md (з paths-фронтматером), user-scope-examples/dot-claude/rules/
Settings.json	.claude/settings.json (+ .annotated.jsonc)
Permissions (allow/ask/deny)	секція permissions у settings.json
Scopes (рівні налаштувань)	settings.json (project) · settings.local.json (local) · managed-settings.example.json (enterprise) · user-scope-examples/ (user)
Scopes (directory CLAUDE.md)	`packages/api
ENVs	.env.example, блок env у settings, managed-settings.example.json
MCP	.mcp.json (http/stdio/${ENV}/alwaysLoad), enabledMcpjsonServers у settings
Субагенти	.claude/agents/*.md (5 рівнів складності)
Кастомні слеш-команди	.claude/commands/*.md
Skills	.claude/skills/*/SKILL.md (+ ресурси)
Hooks	.claude/hooks/*.sh + секція hooks у settings
Dynamic Workflows	.claude/workflows/audit-endpoints.md, commands/refactor.md

Як показати наживо (демо-ідеї)

• Scopes: змінити model у settings.json і settings.local.json → показати, що локальний перемагає; згадати, що managed перемагає все.
• Rules: відкрити файл у packages/api/ → показати, що правило rules/api.md стає активним лише тут; пояснити «scoping пріоритету» (code-style.md без paths діє завжди).
• Hooks: спробувати git commit на main → block-prod-branch.sh блокує (exit 2).
• Субагент: @agent-code-reviewer на свіжий diff; db-reader — показати, що мутуючий SQL не проходить через хук.
• Команда: /project:review packages/api/src/routes/tasks.ts.
• MCP: /mcp — статус серверів; пояснити Tool Search (ENABLE_TOOL_SEARCH=auto).

Підказка: щоб увімкнути цей приклад у власній сесії — відкрий теку example/ як робочу директорію Claude Code. Project-scoped MCP з .mcp.json попросить підтвердити довіру.