Agentic Practices

Agentic Practices

How this project is built with coding agents, and which of the patterns from Agentic Coding Design Patterns (Kirill Mokevnin) it actually implements. The book is a catalogue in the Gang-of-Four spirit for agent-assisted development: task formulation, context, verification, project organisation, and the anti-patterns.

This page is the honest audit, not an aspiration list: each row says where the pattern lives in this repo, so it can be checked.

Implemented

Pattern	Where it lives here
Executable guardrails	.githooks/pre-commit, committed and wired through core.hooksPath so it applies to everyone. Built exactly as the book prescribes: a deterministic floor that fails hard (secrets, .env, syntax) and an AI layer that is fail-soft and never blocks — when that layer timed out during the v1.237.1 commit, the commit still went through on the deterministic check. Above it: 8 CI workflows including CodeQL and dependency-review.
Skills as packaged workflows	.claude/skills/ — parent-sync (parity releases, 9 phases with hard gates and a Known traps section), contributor-pr, hermes-bridge.
Isolated parallel work	Release fan-outs run one agent per locale and one per ported provider, each restricted to an explicit file list and forbidden the shared files; the orchestrator does shared wiring in one pass afterwards.
Writer / reviewer	Three reviewer agents in .claude/agents/ — spa-view-reviewer, test-isolation-reviewer, web-ui-route-reviewer — plus an AI review workflow in CI.
TDD with an agent	Every ported fix is required to show a failing run first. The v1.237.1 Oracle Cloud port opened with 399 !== 453 — the truncation the fix removes.
Feedback loop the agent can run	npm run test:ci (3210), npm run test:e2e:browser (116), check-changelog-parity, five registry count gates, and behavioural markers executed against the deployed server.
Project memory	CLAUDE.md as a short index (deliberately not a knowledge base — see Bloated memory below), AGENTS.md for non-Claude CLIs, .claude/PROJECT-CONTEXT.md for the per-release record.
Domain dictionary	CONTEXT.md — one accepted name per concept, variants marked do not use. It exists because of a real, recurring confusion: 94 sources vs 89 adapters (the five RU sources have no adapter), and telegram vs telegram-channel, which upstream mistook for duplicates and deleted one.
ADRs	docs/adr/ — keep both telegram sources · defend fork divergences · mirror vs relay · liveness hard/soft tiers.
Progress log	PROGRESS.md — current state, next step, known issues and, most usefully, abandoned approaches so a fresh session does not retry them.
Workflow evals	evals/workflow/ — a fixed task set with graders, separating outcome from trajectory. Each grader corresponds to a mistake that shipped once, and each has been adversarially tested by injecting that mistake and confirming the grader goes red — which is how one of them was caught passing on a defect it was meant to catch. Trajectory graders report SKIP, never a silent pass.
Session handoff	PROGRESS.md plus the per-release qa/QA-REGRESSION-PROMPT-v*.md.

Anti-patterns we actively guard against

• Premature success — "verified" collapsing into "unit tests passed". Countered by behavioural markers on the deployed server and a human browser pass in the QA prompt. Recognising the two shapes matters: a suite failing 116/116 at once was a missing Playwright browser, not a regression; a scattered failure is code.
• Bloated memory — CLAUDE.md is kept as a one-screen index that points at CONTEXT.md, PROGRESS.md and docs/adr/, rather than growing into a document nobody reads to the end.
• One-shotting — parity releases run as nine explicit phases with gates, never as a single "do the release" prompt.
• Vibe coding — counts come from the live registry, never from a number typed into a gate test; every ported fix carries a test that failed first.

Not adopted (yet), and why

• Tracer-bullet tickets and grilling — the release pipeline is already specified end-to-end by the parent-sync skill, so the task-formulation patterns have less to bite on here. They would help on greenfield feature work.
• Trajectory grading at scale — the graders are defined, but scoring which commands an agent ran needs recorded sessions and repeated runs. Currently reported as SKIP.

---

Book: https://mokevnin.github.io/agentic-coding-design-patterns/ · Russian edition: https://mokevnin.github.io/agentic-coding-design-patterns/ru/