Как подготовить проект и окружение к агентной разработке Кирилл Мокевнин Hexlet

Preparing a project for agent-based development: start from a “runner” interface

The speaker recommends using Makefiles (even in non-C ecosystems) as a standard entry point for an agent to understand and operate a repository.

Why Makefiles work well for agents

Makefiles act as project navigation + documentation for commands like:

• make start
• make test
• make setup/def/build (the exact targets vary by project)

Benefits for agents:

• Agents can see what actions exist and run the appropriate ones (DB reconfiguration, tests, etc.).
• Makefiles can include script calls from the JS/Node ecosystem (via package scripts).
• Make’s structure (including dependencies) helps agent workflows become consistent and reusable across repos.

Key point

Agents like “Ishka” can read the Makefile and then select/run the right commands—reducing the need to redundantly “teach” the agent every step.

---

Choose agent/model tooling with an eye on cost + ecosystem constraints

Mentioned tools include Claude, Codex, Cursor, and “Pi” (plus a note about emerging Chinese tools).

Cost warning: pay via gateways/platforms

A critical warning is that model access is often mediated by another gateway (the speaker references PSGO IP conceptually as pay per access via a platform), leading to unexpected costs.

Practical implication

In many organizations, especially large tech environments, access to models/agents may be restricted by policy. Teams may need to use approved tooling, even if it’s less flexible or more expensive.

---

Context isn’t “the bigger the better” — use selective retrieval/inputs

The speaker pushes back on stuffing the entire project into the LLM context window.

Main principle:

• More unrelated context often worsens prediction.

Instead, prepare the project so the agent can select only relevant pieces—leading to retrieval/connectors and MCP-like approaches rather than “mega-context” stuffing.

---

Knowledge base / agents MD: use a consistent “project knowledge” structure

The speaker discusses Anthropic-flavored “AgencyMD / Knowledge” and suggests standardizing around their system.

Workflow concept

• For a project, the system can generate/update a knowledge artifact (e.g., an index-like artifact) that updates based on project changes.
• Recommendation: periodically restart/rebuild the generated knowledge, because it can change as agent tooling evolves.

---

Versioning is a practical necessity (agent mistakes default version assumptions)

A recurring failure mode:

• If versions aren’t specified, the model may choose version-1 (or the “last remembered version”), causing wrong results.

Recommendation:

• Add explicit versioning information to repo docs so the agent can act deterministically.

---

Connectors/tooling: MCP vs CLI-style tools (and when MCP is mandatory)

For web projects, a “minimum set” mentioned:

• Error collector
• GitHub/GitLab
• Chrome DevTools integration
• Read-only DB access (useful for agents)

MCP vs CLI-style tools

• MCP connectors are stateful service integrations.
• Command-line tools are more limited for stateful services (like browser/UI workflows).

Guidance

• Many modern environments are shifting toward MCP-first for organization-wide rollout.
• Example: in Claude Enterprise-style setups, connectors may be configured centrally so non-developers don’t need to install CLI tooling manually.

---

Preparatory steps depend heavily on “automatic verification”

A major requirement:

• Agents must be able to verify changes automatically.

Verification expectations (typed vs dynamic languages)

The speaker argues verification should include:

• types
• lint
• tests (plus linting)
• logging/SQL checks
• running code and possibly browser checks (even when tests aren’t available)

Agent self-check requirement

In “plan mode”, the agent should output something like:

• “How will I check my own steps?”

If it responds vaguely (e.g., “look for yourself”), the project isn’t ready.

Example behavior

An agent that uses Make-based commands can incorporate logic for:

• make test
• linters
• integration tests
• browser tests, etc.

---

Skills: when to use them vs when to put logic in the repo

The speaker describes skills as reusable “workflow steps” and argues:

• Don’t always encode core routines (like write tests) as skills.
• Skills may not reliably load in the right order.
• Prefer putting always-required checks directly into project files when they’re central.

Best fit for skills

Use skills for truly separate workflows such as:

• SEO/performance analysis
• i18n tasks
• other modular tasks

---

Examples of skills and why they matter

Vendor/official skills

Official or vendor-provided skills are recommended because they can come ready-to-use (“out-of-the-box”).

Code-review workflow example (Claude skill)

The speaker gives a code-review workflow example where the agent:

1) analyzes which rules apply, 2) reads the changes, 3) spawns multiple parallel reviewers (up to five agents), each targeting different rule categories, 4) uses similarity/pattern logic to suggest refactors and abstractions.

---

Domain modeling + spec-driven approaches for better planning (“Home modeling” + docs)

The speaker recommends a stronger upfront step: domain modeling, to build an “ontology/domain apparatus” from existing code/data/docs.

Workflow described

1) A model/interviewer agent extracts domain concepts and reconciles them with: - code/models, - tables, - project texts/designations 2) It produces an “anthology” (structured project knowledge). 3) The planning agent uses it for feature design decisions (e.g., choosing between approaches like “GR with docs” vs “Grilmyl”).

Emphasized output

Not just a plan, but conclusions + alternatives + rejected decisions, stored as persistent project memory.

Benefits

• Each session improves knowledge for the whole team.
• Over time, this reduces the need for manual architecture documentation.

---

Key “hacks” / actionable recommendations distilled

• Use Makefiles as the agent-friendly control plane for repo actions.
• Ensure automatic verification is possible: types, lint, tests, browser/code execution.
• Add explicit versioning to avoid wrong default assumptions.
• Prefer selective context retrieval over dumping entire codebases.
• Prefer MCP connectors for org-wide stateful integration (especially browsers/UI tools).
• Use skills only for truly separate workflows; keep essential checks in repo scripts/files.
• Use domain modeling to build reusable project knowledge and produce structured decision records.

---

Main speakers / sources

• Primary speaker: Kirill Mokevnin (Hexlet)
• Referenced Q&A participant(s): Maxim (questioner)

Referenced ecosystem/tools (not speakers)

• Claude, Codex, Cursor, “Ishka”, Anthropic, MCP, Colina/CLI utilities
• GitHub/GitLab, Chrome DevTools
• Hexlet