К основному содержанию
скилл CX Codex

agent-architecture-analysis — скилл для Claude Code

Скилл agent-architecture-analysis проверяет кодовую базу ИИ-агента по методике 12-Factor Agents и выдаёт отчёт с оценкой каждого фактора и ссылками на файлы.

Apache-2.0 220 установок ★ 89 обновлён 2026-09-15

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add existential-birds/beagle --skill agent-architecture-analysis -a claude-code
Открыть на GitHub

Что делает agent-architecture-analysis

Скилл берёт codebase_path и прогоняет проект по методике 12-Factor Agents: 13 факторов, от схемы валидации tool calls до агентов-редьюсеров без состояния и предзагрузки контекста. Сначала поиск по шаблонам, затем чтение найденных файлов. Дальше — разбор пробелов и рекомендации с примерами кода.

Полная рубрика лежит в references/factors.md: для каждого фактора там принцип, шаблоны поиска, критерии Strong/Partial/Weak и анти-паттерны. На выходе — сводная таблица и разбор по факторам с цитатами вида file:line. Правило жёсткое: оценку ставят только после того, как в коде нашлось доказательство. Если после адресного поиска подтверждений нет, фактор по умолчанию уходит в Weak.

Поле codebase_path обязательное, docs_path с готовыми разборами — по желанию. Без пути к коду скилл просто нечего читать, поэтому запускайте его из корня проекта.

Какие задачи решает

  • проверить, как агент отдаёт tool calls и валидируются ли схемы
  • найти промпты, зашитые в код вместо версионируемых шаблонов
  • оценить, можно ли приостановить агента и продолжить с того же места
  • собрать из находок аудита список правок по приоритету
  • сравнить два фреймворка по одной рубрике

Примеры запросов агенту

  • Проанализируй архитектуру агента в ./src, начни с факторов 1–5
  • Сделай 12-factor аудит этого репозитория и покажи сводную таблицу
  • Насколько этот LLM-проект соответствует 12-Factor Agents? Нужны ссылки на файлы

Как установить agent-architecture-analysis

1Через Skills CLI (Vercel)

npx skills add existential-birds/beagle --skill agent-architecture-analysis -a claude-code

2Вручную: положить файлы

~/.claude/skills/agent-architecture-analysis/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/agent-architecture-analysis/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об agent-architecture-analysis

Как установить agent-architecture-analysis в Claude Code?

Выполните npx skills add existential-birds/beagle --skill agent-architecture-analysis -a claude-code. Файл скилла появится по пути ~/.claude/skills/agent-architecture-analysis/SKILL.md.

Что делает agent-architecture-analysis?

Разбирает кодовую базу агента по 13 факторам методики 12-Factor Agents и ставит каждому оценку Strong, Partial или Weak. К оценке прилагается цитата из кода с путём и номером строки.

Это быстрый чеклист по 12 факторам?

Нет. Скилл делает глубокий разбор каждого фактора по коду: сначала поиск по шаблонам, потом чтение файлов. Без найденного доказательства оценка не ставится.

Исходный текст

SKILL.md · Apache-2.0
---
name: agent-architecture-analysis
description: "Use when auditing an agent codebase against the 12-Factor Agents methodology, reviewing LLM-powered system architecture, or assessing agentic app compliance. Triggers on \"analyze agent architecture\", \"12-factor audit\", \"how compliant is this agent\", or \"evaluate this LLM app\". Also applies when comparing frameworks or planning agent improvements. Not for quick checklists \u2014 this performs deep per-factor codebase analysis with file-level evidence."
---

# 12-Factor Agents Compliance Analysis

> Reference: [12-Factor Agents](https://github.com/humanlayer/12-factor-agents)

## Input Parameters

| Parameter | Description | Required |
|-----------|-------------|----------|
| `docs_path` | Path to documentation directory (for existing analyses) | Optional |
| `codebase_path` | Root path of the codebase to analyze | Required |

## Analysis Framework

The full per-factor rubric — principle, search patterns, file patterns, compliance criteria (Strong/Partial/Weak), and anti-patterns for each of the 13 factors — lives in [references/factors.md](references/factors.md). During the [Analysis Workflow](#analysis-workflow), read the relevant factor sections there for the search patterns to run and the criteria to score against.

| # | Factor | Focus |
|---|--------|-------|
| 1 | Natural Language to Tool Calls | Schema-validated structured outputs from LLM |
| 2 | Own Your Prompts | Prompts as first-class, versioned, templated code |
| 3 | Own Your Context Window | Custom formatting of history/state/tool results |
| 4 | Tools Are Structured Outputs | Validated JSON triggers deterministic code |
| 5 | Unify Execution State | Single state object merging execution + business state |
| 6 | Launch/Pause/Resume | APIs to launch, pause anywhere, resume |
| 7 | Contact Humans with Tools | Human contact as a structured tool call |
| 8 | Own Your Control Flow | Custom routing/retries, not framework defaults |
| 9 | Compact Errors into Context | Errors fed back for self-healing + escalation |
| 10 | Small, Focused Agents | Narrow responsibility, 3-10 steps each |
| 11 | Trigger from Anywhere | CLI/REST/WebSocket/chat/webhook entry points |
| 12 | Stateless Reducer | Pure `(state, input) -> (state, output)` agents |
| 13 | Pre-fetch Context | Fetch likely-needed data upfront |

See [references/factors.md](references/factors.md) for the complete rubric for every factor above.

---

## Output Format

**Gate order:** Do not assign Strong / Partial / Weak or treat recommendations as observed facts until **Hard gates** (after [Analysis Workflow](#analysis-workflow)) are satisfied for the factors in scope.

### Executive Summary Table

```markdown
| Factor | Status | Notes |
|--------|--------|-------|
| 1. Natural Language -> Tool Calls | **Strong/Partial/Weak** | [Key finding] |
| 2. Own Your Prompts | **Strong/Partial/Weak** | [Key finding] |
| ... | ... | ... |
| 13. Pre-fetch Context | **Strong/Partial/Weak** | [Key finding] |

**Overall**: X Strong, Y Partial, Z Weak
```

### Per-Factor Analysis

For each factor, provide:

1. **Current Implementation**
   - Evidence with file:line references
   - Code snippets showing patterns

2. **Compliance Level**
   - Strong/Partial/Weak with justification

3. **Gaps**
   - What's missing vs. 12-Factor ideal

4. **Recommendations**
   - Actionable improvements with code examples

---

## Analysis Workflow

1. **Initial Scan**
   - Run search patterns for all factors
   - Identify key files for each factor
   - Note any existing compliance documentation

2. **Deep Dive** (per factor)
   - Read identified files
   - Evaluate against compliance criteria
   - Document evidence with file paths

3. **Gap Analysis**
   - Compare current vs. 12-Factor ideal
   - Identify anti-patterns present
   - Prioritize by impact

4. **Recommendations**
   - Provide actionable improvements
   - Include before/after code examples
   - Reference roadmap if exists

5. **Summary**
   - Compile executive summary table
   - Highlight strengths and critical gaps
   - Suggest priority order for improvements

---

## Hard gates (evidence before scores)

Run these in order. Do not skip ahead: each **Pass** is an objective condition you can check (paths on disk, citations present), not internal certainty.

1. **Scan gate** — After the initial scan (workflow step 1), **Pass:** for every factor (1–13) you have either (a) ≥1 repo-relative path or glob hit to inspect, or (b) a one-line note with rationale (e.g. search command/output, or “no matches — codebase may omit this concern”). Empty hand-waving (“looks fine”) fails this gate.
2. **Evidence gate (per factor)** — Before writing Strong / Partial / Weak for that factor, **Pass:** “Current Implementation” includes ≥1 citation with **file path** plus **line range or short quoted snippet** from `codebase_path`, or an explicit **no evidence located** statement after targeted reads. If evidence is missing after search, default that factor to **Weak** unless the criterion is clearly N/A (say why).
3. **Synthesis gate** — Executive summary table and per-factor analysis sections, **Pass:** only after gates 1–2 are satisfied for the factors in scope. Recommendations may name new files or patterns only as proposals; they must not be presented as observed facts without matching citations from step 2.

---

## Quick Reference: Compliance Scoring

| Score | Meaning | Action |
|-------|---------|--------|
| **Strong** | Fully implements principle | Maintain, minor optimizations |
| **Partial** | Some implementation, significant gaps | Planned improvements |
| **Weak** | Minimal or no implementation | High priority for roadmap |

## When to Use This Skill

- Evaluating new LLM-powered systems
- Reviewing agent architecture decisions
- Auditing production agentic applications
- Planning improvements to existing agents
- Comparing frameworks or implementations

© existential-birds · Apache-2.0 · existential-birds/beagle

Похожие скиллы

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →
competitors-analysis daymade Скилл competitors-analysis для Claude Code клонирует репозитории конкурентов, читает их исходный код и формирует технический аудит с точными ссылками на строки файлов. CX Codex +1 724установок agentic-ai-risk-assess OWASP Скилл agentic-ai-risk-assess проводит аудит автономных ИИ-агентов и мультиагентных систем по стандарту OWASP Top 10 for Agentic Applications 2026. CX Codex +1 156установок agent-architecture-audit affaan-m Скилл agent-architecture-audit для Claude Code ищет сбои в приложениях с агентами и LLM. Запускайте его, когда причина странного поведения неизвестна или перед выпуском приложения. CX Codex +1 6 500установок agent-architecture официальный github Скилл agent-architecture для Claude Code помогает проектировать архитектуру ИИ-агента и находить дефекты готовой системы. Проводит аудит и собирает требования до начала написания кода. CX Codex +1 42установок roblox-architecture TabooHarmony Скилл roblox-architecture разбирает, кому принадлежит поведение в проекте Roblox, где границы клиента и сервера и почему ломается порядок загрузки. CX Codex +1 3 500установок clean-architecture pproenca Скилл clean-architecture с 42 правилами из книги Роберта Мартина: подсказывает агенту, куда направлять зависимости и где проводить границы слоёв. CX Codex +1 2 100установок

Из того же набора68

Весь набор →
review-verification-protocol Скилл review-verification-protocol обязывает проверить каждую находку перед тем, как внести её в отчёт — читать исходный код, искать контекст, отличать баги от стиля. Снижает ложные срабатывания в ревью. CX Codex +1 252установок pytest-code-review Скилл pytest-code-review проверяет тесты pytest на корректность асинхронных вызовов, скоуп фикстур, параметризацию и пути для моков. Помогает находить утечки и ошибки патчинга до запуска CI. CX Codex +1 239установок sqlalchemy-code-review Скилл sqlalchemy-code-review проверяет SQLAlchemy-код на ошибки в сессиях, связях, запросах и миграциях. Нужен при ревью проектов на SQLAlchemy 2.0 и Alembic. CX Codex +1 228установок pydantic-ai-common-pitfalls Скилл pydantic-ai-common-pitfalls разбирает типичные ошибки в агентах на PydanticAI и подсказывает, что править: декораторы инструментов, зависимости, схемы вывода, стриминг. CX Codex +1 221установок pydantic-ai-agent-creation Скилл pydantic-ai-agent-creation помогает создавать типобезопасных агентов на PydanticAI: со структурированным выводом, зависимостями и настройками модели. Нужен при сборке AI-агентов и чат-систем. CX Codex +1 219установок ai-elements Скилл ai-elements для Claude Code, Codex, Cursor, Copilot, Gemini CLI и OpenCode: помогает собирать интерфейсы чата, очереди задач, отображение инструментов и подтверждений. CX Codex +1 211установок go-code-review Скилл go-code-review проверяет Go-код на идиоматичность, обработку ошибок и гонки: сначала читает go.mod, потом разбирает функции целиком. CX Codex +1 206установок shadcn-code-review Скилл shadcn-code-review проверяет React-компоненты на базе shadcn/ui, Radix и Tailwind CSS на доступность, работу с CVA и шаблоны asChild. Помогает находить ошибки в кастомной вёрстке. CX Codex +1 206установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой