Анатомия проекта

Чтобы понять, как должен выглядеть хороший OpenCode setup, полезно смотреть не на искусственные примеры, а на реальный репозиторий. В этой главе разбирается github.com/ivanshamaev/ai-agent-codex и объясняется роль каждого OpenCode-слоя.

OpenCode-слой в репозитории-примере

ai-agent-codex/
├─ AGENTS.md
├─ opencode.json
├─ docs/
│  └─ specs/
│     ├─ hh-market-interfaces.md
│     └─ hh-vacancies-pipeline.md
└─ .opencode/
   ├─ agents/
   │  ├─ backend-engineer.md
   │  ├─ data-analyst.md
   │  ├─ data-engineer.md
   │  ├─ frontend-engineer.md
   │  ├─ infrastructure-engineer.md
   │  ├─ project-manager.md
   │  └─ system-analyst.md
   └─ skills/
      ├─ airflow-dag-design/SKILL.md
      ├─ dbt-modeling/SKILL.md
      ├─ docker-compose-local/SKILL.md
      ├─ fastapi-async-api/SKILL.md
      ├─ metric-design/SKILL.md
      ├─ python-etl/SKILL.md
      ├─ realtime-analytics-api/SKILL.md
      └─ requirements-spec/SKILL.md

Важно видеть, что это не «магическая папка OpenCode», а набор обычных репозиторных артефактов. Сила не в скрытой механике, а в том, как эти файлы связаны между собой.

Слой 1. AGENTS.md

Согласно документации Rules, AGENTS.md — это проектный instruction file. В репозитории-примере он выполняет очень важную роль: объясняет агенту, что это за система, какие слои считаются правильными, как организован код и какую роль играют docs/specs, .opencode/agents и .opencode/skills.

Хорошо, что этот файл не ограничивается общими лозунгами. В нем зафиксированы цели проекта, priorities, expected repository structure, architecture rules, role routing и delivery workflow. Именно такой формат делает его useful, а не декоративным.

## Expected Repository Structure
- `dags/` Airflow DAG definitions only.
- `src/` Shared Python code used by DAGs and data pipelines.
- `docs/specs/` short functional and technical specs.
- `.opencode/agents/` role-based subagents.
- `.opencode/skills/` reusable domain skills.

Слой 2. opencode.json

Следующий слой — проектный control plane. В примере через opencode.json подключаются инструкции из AGENTS.md и docs/specs/*.md, задаются ограничения на использование skills и настраиваются permissions для встроенных primary agents.

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "AGENTS.md",
    "docs/specs/*.md"
  ],
  "permission": {
    "skill": {
      "*": "deny",
      "requirements-spec": "allow",
      "dbt-modeling": "allow"
    }
  }
}

Это важно, потому что агент получает не только доступ к файлам, но и правила о том, какие модули знаний ему вообще доступны и какие инструкции нужно учитывать всегда.

Слой 3. docs/specs/

Очень сильная часть архитектуры примера — наличие docs/specs как отдельного durable слоя. В этой папке лежат не «заметки для человека», а реальные спецификации, которые агент читает через instructions. Это кардинально уменьшает количество догадок.

Слой 4. .opencode/agents/

Здесь лежат project-specific subagents. И это один из лучших элементов примера, потому что роли названы на языке реальной команды: data-engineer, backend-engineer, frontend-engineer, project-manager, system-analyst.

Такой подход лучше абстрактного «универсального помощника», потому что каждый subagent получает четкую рабочую область, собственный prompt и, при необходимости, отдельные permission overrides.

---
description: Implements ingestion, SQL, Airflow DAGs, dbt models, and Python ETL components for the data platform.
mode: subagent
temperature: 0.1
steps: 12
permission:
  bash:
    "*": allow
    "git push*": ask
---

Здесь видно, что subagent — это не просто название. У него уже есть operational framing: что именно он делает, насколько творчески мыслит, сколько шагов ему допустимо сделать и какие bash-команды стоит дополнительно контролировать.

Слой 5. .opencode/skills/

Skills в OpenCode — это on-demand knowledge modules. В примере они вынесены по доменным областям: от requirements-spec и delivery-planning до python-etl, dbt-modeling и realtime-analytics-api. Это позволяет не раздувать базовый контекст и не держать всю экспертизу в одном giant prompt.

---
name: requirements-spec
description: Produce concise implementation-ready requirements, assumptions, field mappings, and acceptance criteria.
compatibility: opencode
---
## What I do
- Capture business goal and scope.
- Define inputs, outputs, and grain.
- Document source-to-target mapping.

Как эти слои работают вместе