From 2d9da1227567c3239e76d55ebd7880283a8eba9b Mon Sep 17 00:00:00 2001 From: speech115 <201258852+speech115@users.noreply.github.com> Date: Wed, 1 Jul 2026 12:31:46 +0400 Subject: [PATCH] Document developer workflow conventions in AGENTS.md and add root CLAUDE.md Derived branch naming, commit message style, attribution, and PR body conventions from actual git/PR history instead of inventing new ones, and gave Claude Code sessions a root-level entrypoint matching mcp/CLAUDE.md's canon-plus-summary pattern. Co-Authored-By: Claude Sonnet 5 --- AGENTS.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++- CLAUDE.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 96 insertions(+), 1 deletion(-) create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md index 368d6d6..87a0f9e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,10 +17,59 @@ working inside those directories. - Use the `git-safe-workflow` skill for commits and PRs. - Default path is branch -> local checks -> exact-file commit -> PR. - Do not push directly to `main` unless the user explicitly asks for direct-main - behavior. + behavior in that specific request. A prior approval to push does not carry + forward to later sessions or later commits — ask again each time. - Do not merge PRs, close issues, post public GitHub comments, tag, or release without a separate explicit user request. +## Developer Workflow Conventions + +Derived from this repo's actual commit/PR history (`git log`, `gh pr list`), +not just the templates. Follow the observed pattern, not an invented one. + +**Branch naming** — prefix by session origin, then a kebab-case topic slug: +- `codex/` — dominant pattern for Codex CLI sessions (e.g. + `codex/control-plane-operator-gates`, `codex/thermonuclear-fixes`). +- `claude/` — use this for Claude Code sessions; no Claude-specific + prefix existed before, this mirrors the established `codex/` convention so + branch origin stays identifiable. +- `docs/issue--` — docs-only PRs that close a numbered issue. + +**Commit messages** — single-line, capitalized, imperative, verb-first summary +(`Harden Telegram MCP control surfaces`, `Add Telegram metadata fast lane`). +No conventional-commit type prefix is required or consistently used — only +2 of the last 24 commits use one (`Chore: ...`, `docs: ...`), so don't invent +a strict `feat:`/`fix:` scheme. For multi-part changes, add a body with `-` +bullets (mirrors what a squashed PR's `## Summary` becomes). Squash-merged PRs +get GitHub's `(#)` suffix automatically — don't add it by hand on direct +commits. + +**Attribution** — 22 of the last 24 commits in this repo carry no co-author +trailer at all; this repo has not historically used `Co-Authored-By`. Claude +Code's own default behavior appends a `Co-Authored-By: Claude ... ` +trailer on commits it authors — keep doing that for Claude-authored commits +(it accurately discloses tooling and costs nothing), but don't backfill it +onto older Codex-authored history or expect it there. + +**PR body structure** — two header variants appear, use this shape: +``` +## Summary +- one bullet per change + +## Verification +- exact command(s) run +- actual result, not "tests pass" (e.g. "control-plane 204 passed, MCP 337 tests OK") +``` +Add an optional `## GitHub context` section when the PR interacts with CI +state or another open PR (see PR #13). This should satisfy +`.github/PULL_REQUEST_TEMPLATE.md`'s checklist directly — fill it in, don't +leave it as unchecked boilerplate. + +**Test plan / evidence** — run `scripts/safe-gate` before every non-trivial +commit (see Local Gate below); quote real test counts in the PR, not vague +claims. For live-behavior changes, also run local live smoke and paste +redacted output per `CONTRIBUTING.md`. + ## Local Gate Run `scripts/safe-gate` before committing non-trivial changes. It checks: diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..2f48aca --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,46 @@ +# Claude Code Notes + +Canonical behavior contract for this repo is [`AGENTS.md`](AGENTS.md) — read +it first. This file adds Claude-specific context so a session that only +loads `CLAUDE.md` still has the essentials. + +## Language +Respond in Russian. Code, git commit messages, and CLI output stay in English. + +## Scope +Three coupled surfaces — prefer the more specific `mcp/AGENTS.md` / +`mcp/CLAUDE.md` and `control-plane/AGENTS.md` when working inside those +directories: +- `mcp/` — Telegram MCP server and live tool behavior. +- `control-plane/` — local operator commands, release checks, agent docs. +- `plugin/` — packaged Codex plugin and bundled Telegram skill. + +## Developer Workflow (summary — see `AGENTS.md` for the full derivation) + +- **Branch**: `claude/` for work you start (mirrors the repo's + established `codex/` convention; do not invent another prefix). +- **Commit message**: single-line, capitalized, imperative summary + (`Add X`, `Harden Y`) — no type prefix required; this repo doesn't use + conventional commits consistently. Bullet body only for multi-part changes. +- **Attribution**: this repo's own history carries no `Co-Authored-By` + trailers, but keep Claude Code's default trailer on commits you author — + it's accurate disclosure, just don't backfill it onto older commits. +- **PR body**: `## Summary` (bullets) + `## Verification` (exact commands and + real output, not "tests pass") + optional `## GitHub context`. +- **Before committing anything non-trivial**: run `scripts/safe-gate`. Quote + its actual output in the PR, don't paraphrase. +- **main**: default path is branch -> PR, never push directly to `main` + unless the user explicitly asks for that in the current request — an + earlier approval to push doesn't carry forward. + +## Commands + +- `./scripts/safe-gate` — MCP tests + control-plane tests (portable mode) + + agent docs sync drift + whitespace hygiene. Run before every non-trivial + commit. +- `./scripts/ci-release-gate.sh` — full release verification. +- `PYTHONPATH=src .venv/bin/python -m unittest discover -s tests -p 'test_*.py'` + — run from `mcp/` directly when iterating on that surface. Zero extra deps. + `CONTRIBUTING.md` shows `pytest` instead — that also works, but `pytest` + isn't a declared dependency, so a fresh `.venv` needs + `uv pip install pytest` before `uv run pytest` will find it.