docs: engineering standards — toolchain, architecture level, agentic harness - #2
Merged
Conversation
…re, agentic harness Research-validated (2026-07) against Textual, posting, harlequin, FastAPI, pydantic, pydantic-ai, marimo, litellm, aider, uv: - Toolchain: uv + hatchling + Ruff (lint/format/imports) + mypy --strict (+ ty as non-blocking CI) + pytest stack, all configured in a single pyproject.toml. Rejected: black/isort, DI containers, pluggy, commitizen, interrogate, radon, mutation testing - Architecture: pragmatic layered — abc.ABC interfaces at boundaries, constructor injection at the composition root (no DI container: 0 of 6 examined projects use one), UI Bus on Textual Messages (harlequin pipeline pattern), core/agent/k8s Textual-free, entry_points plugins (korvid.provider/panel/tool) - Quality gates in three layers: harness hooks (<1s) → pre-commit (<10s, no tests) → CI (full matrix + tach + deptry + coverage) - Agentic harness: AGENTS.md behavior contract (CLAUDE.md delegates via @AGENTS.md), Claude Code hooks for auto-format/protected-files/ stop-tests, repo gates unbypassable regardless of harness Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
This PR establishes korvid’s development standards and agent/harness expectations before implementation begins, aligning tooling, architecture boundaries, and quality gates with an agent-first workflow.
Changes:
- Adds an engineering standards spec covering toolchain, layered architecture, and quality gates.
- Introduces a repo-root
AGENTS.mdcontract for agent behavior (commands, layer rules, security invariants). - Adds
CLAUDE.mdas a minimal pointer toAGENTS.mdfor Claude Code compatibility.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| docs/specs/2026-07-24-korvid-engineering-standards.md | Defines the proposed toolchain, architecture layering rules, and agentic development gate model. |
| AGENTS.md | Provides a concise agent-facing contract (commands, layer boundaries, style/test rules, PR/security invariants). |
| CLAUDE.md | Delegates Claude Code guidance to the shared AGENTS.md contract. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| |---|---|---| | ||
| | PostToolUse (Edit\|Write, `*.py`) | after each edit | `uv run ruff check --fix` + `ruff format` on the file — agent never sees lint noise in review | | ||
| | PreToolUse (Edit\|Write) | before each edit | **block** edits to protected paths: `uv.lock`, `.github/workflows/`, `tach.toml`, `.pre-commit-config.yaml` (exit 2). Agents must ask the human to change gate files | | ||
| | Stop | agent finishes a turn | `uv run pytest -x -q --tb=short \| tail -20` — failures land in the agent's context immediately | |
![my-reviewer-agent[bot]](https://avatars.githubusercontent.com/in/4343504?s=60&v=4){kind=small}
|
|
||
| The cross-harness standard file (read natively by Copilot/Codex-family tools; Claude Code reads it via `CLAUDE.md` containing the single line `@AGENTS.md` — the uv/marimo pattern). Contents: | ||
|
|
||
| - Quick setup + the exact dev commands (`make lint / format / typecheck / test`) |
There was a problem hiding this comment.
Suggestion — §5.1은 AGENTS.md에 make lint / format / typecheck / test 명령이 담긴다고 기술하지만, 이 PR의 AGENTS.md는 uv run ruff/mypy/pytest ... 직접 호출만 나열하고 Makefile 언급이 없습니다 (Makefile은 §6의 scaffold PR에서 도입 예정). 에이전트가 아직 없는 make 타깃을 실행하려다 실패하지 않도록, 두 문서 중 한쪽으로 표현을 맞추거나 "Makefile 도입 후 갱신" 각주를 추가하는 것을 제안합니다.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Declares how korvid code will be developed, before the first implementation line. Three artifacts:
docs/specs/2026-07-24-korvid-engineering-standards.md— the standards spec:tyas a non-blocking CI job, FastAPI-style) + pytest/pytest-textual-snapshot/pytest-randomly, all configured in a single pyproject.toml. Explicit reject list (black/isort, DI containers, pluggy, commitizen, interrogate, radon, mutation testing, pyrefly)type: ignore, complexity ≤ 10, warnings-as-errors in testsabc.ABCboundary interfaces + constructor injection at a composition root + entry_points plugins. UI Bus rides Textual Messages (harlequin's pipeline pattern);core/agent/k8sstay Textual-free; litellm's monolithic router identified as the anti-pattern to avoid. Full hexagonal rejected as unneeded ceremony; conventions-only rejected because agent-written code needs structural gatesAGENTS.md— the agent behavior contract (cross-harness standard): commands, layer table, style rules agents most often violate, workflow economics ('don't run full checks between edits'), PR rules, security invariants from the design docCLAUDE.md— one line,@AGENTS.md(uv/marimo delegation pattern)Why now
Phase 1 implementation planning is next; the gates must exist before the first scaffold so all agent-written code lands inside them (adoption order in §6).
Research basis
Two dedicated research passes (2026-07-24): (a) modern Python tooling incl. agentic-development hooks across Textual/posting/FastAPI/pydantic/pydantic-ai/marimo/uv; (b) architecture level of fast-rising projects incl. harlequin's entry_points adapter system and pydantic-ai's Model/Provider ABCs. Citations inline in the spec.