diff --git a/AGENTS.md b/AGENTS.md index 628716ad..333445a9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,49 +5,48 @@ repository. It has two layers: **how to run a task end-to-end** (the sections below), and **how the codebase is built** (the technical sections further down, formerly in `CLAUDE.md`). -## Жизненный цикл задачи +## Task lifecycle -### 1. Старт: синхронизация с develop +### 1. Start: sync with develop -Перед началом **любой** работы обнови локальный `develop` и ветвись от него: +Before starting **any** work, update your local `develop` and branch off it: ```bash git checkout develop git fetch gitea git pull --ff-only gitea develop -git checkout -b <короткое-имя-фичи> +git checkout -b ``` -Никогда не пилит фичу прямо в `develop` и не ветвись от устаревшего -`develop` — иначе PR будет содержать лишние коммиты или конфликтовать. +Never build a feature directly on `develop`, and never branch off a stale +`develop` — otherwise the PR will carry extra commits or conflict. -### 2. Реализация +### 2. Implementation -Веди задачу по workflow из системного промпта (Phase 1 анализ → Phase 3 -реализация → Phase 4 review → Phase 5 верификация → Phase 6 отчёт). Большие -изменения делегируй в general subagent, ревьюй через review subagent. +Run the task through the workflow from the system prompt (Phase 1 analysis → +Phase 3 implementation → Phase 4 review → Phase 5 verification → Phase 6 +report). Delegate large changes to a general subagent; review via the review +subagent. -**Worktree'ы создавай только внутри папки `.claude`** (например, -`.claude/worktrees/<имя>`). Создавать git worktree где-либо ещё — в корне -репозитория, в соседних каталогах или во временных папках — запрещено. +**Create worktrees only inside the `.claude` folder** (e.g. +`.claude/worktrees/`). Creating a git worktree anywhere else — the repo +root, sibling directories, or temp folders — is forbidden. -### 3. Коммит — ТОЛЬКО в Gitea и ТОЛЬКО от `claude_code` +### 3. Commit — ONLY to Gitea and ONLY as `claude_code` -Это правило без исключений: +This rule has no exceptions: -- **Куда:** единственный remote для коммитов/пушей — **`gitea`** - (`gitea.vvzvlad.xyz`). **Никогда** не пушь в `origin` (GitHub-зеркало) и - тем более в `upstream` (оригинальный Docmost). GitHub-зеркало обновляется - CI-процессом владельца, не агентом. -- **От кого:** коммить **только** от агентского identity. Любой коммит, - у которого author или committer — `vvzvlad`, считается ошибкой и должен - быть переписан. +- **Where:** the only remote for commits/pushes is **`gitea`** + (`gitea.vvzvlad.xyz`). **Never** push to `origin` (the GitHub mirror), and + especially not to `upstream` (the original Docmost). The GitHub mirror is + updated by the owner's CI process, not by the agent. +- **Who:** commit **only** as the agent identity. Any commit whose author or + committer is `vvzvlad` is an error and must be rewritten. - **name:** `claude_code` - **email:** `claude_code@vvzvlad.xyz` -Используй `--reset-author` при amend, иначе git оставит оригинального -автора (по умолчанию config на этой машине — `vvzvlad`, поэтому проверяй -после каждого коммита): +Use `--reset-author` when amending, otherwise git keeps the original author +(the default config on this machine is `vvzvlad`, so check after every commit): ```bash GIT_AUTHOR_NAME="claude_code" \ @@ -57,34 +56,33 @@ GIT_COMMITTER_EMAIL="claude_code@vvzvlad.xyz" \ git commit --amend --no-edit --reset-author ``` -Для обычного нового коммита достаточно один раз выставить локальный -config ветки и коммитить штатно: +For a regular new commit, set the branch-local config once and commit normally: ```bash git config user.name "claude_code" git config user.email "claude_code@vvzvlad.xyz" ``` -Проверка перед push: +Check before push: ```bash git log -1 --format='Author: %an <%ae>%nCommitter: %cn <%ce>' -# обе строки должны показать claude_code +# both lines must show claude_code ``` -### 4. Push и PR в develop +### 4. Push and PR to develop -PR всегда в `develop`. Пароль `claude_code` лежит в macOS keychain как -**generic password** под service `gitea-claude-code` (не дублируй его как -internet-password для `gitea.vvzvlad.xyz` — это создаст конфликт с учёткой -владельца в git credential helper): +PRs always target `develop`. The `claude_code` password lives in the macOS +keychain as a **generic password** under service `gitea-claude-code` (do not +duplicate it as an internet-password for `gitea.vvzvlad.xyz` — that creates a +conflict with the owner's account in the git credential helper): ```bash AGENT_PASS=$(security find-generic-password -s gitea-claude-code -w) ``` -Push — через временную подстановку кредов в remote URL, после чего URL -обязательно возвращается в чистый вид (пароль не должен оседать в git +Push by temporarily injecting the credentials into the remote URL, then always +restore the URL to its clean form (the password must not linger in git config / reflog): ```bash @@ -96,7 +94,7 @@ git remote set-url gitea "$ORIG_URL" unset AGENT_PASS SAFE_PASS ``` -PR создаётся через Gitea REST API (Basic Auth от `claude_code`): +The PR is created via the Gitea REST API (Basic Auth as `claude_code`): ```bash curl -s -X POST \ @@ -106,63 +104,62 @@ curl -s -X POST \ "https://gitea.vvzvlad.xyz/api/v1/repos/vvzvlad/gitmost/pulls" ``` -`base: develop`, `head: `. В теле PR — что сделано, что вне scope, -результаты верификации (tsc/lint/tests). +`base: develop`, `head: `. In the PR body: what was done, what is out +of scope, verification results (tsc/lint/tests). -> Если push падает с `User permission denied for writing` — значит у -> `claude_code` нет коллабораторских прав на репо. Попроси владельца -> добавить (один раз, через Gitea UI или -> `PUT /api/v1/repos/vvzvlad/gitmost/collaborators/claude_code` с -> `{"permission":"write"}` от его учётки). +> If push fails with `User permission denied for writing`, then `claude_code` +> lacks collaborator rights on the repo. Ask the owner to add them (once, via +> the Gitea UI or `PUT /api/v1/repos/vvzvlad/gitmost/collaborators/claude_code` +> with `{"permission":"write"}` from their account). -### 5. Мерж и cleanup +### 5. Merge and cleanup -- **Мерж PR в develop делает пользователь** (не агент). Агент не жмёт - кнопку merge. -- **После реализации задачи удали её план из `docs/backlog/.md`** — - это часть закрытия задачи, не пользовательская работа. Файлы в - `docs/backlog/` — это очередь работы, выполненное из неё вычищается. - Сделай это в отдельном коммите от того же `claude_code` в той же ветке - (или попроси пользователя удалить, если PR уже открыт и ты не хочешь - его перепушивать). -- Не закоммичен ли мусор в рабочем дереве? Проверь `git status` перед - финальным отчётом. +- **The user merges the PR into develop** (not the agent). The agent does not + press the merge button. +- **After implementing a task, delete its plan from `docs/backlog/.md`** — + this is part of closing the task, not the user's work. Files in + `docs/backlog/` are the work queue; completed items get cleaned out of it. + Do this in a separate commit from the same `claude_code` on the same branch + (or ask the user to delete it if the PR is already open and you don't want to + repush it). +- Any junk left uncommitted in the working tree? Check `git status` before the + final report. -## Релизный цикл: набор на новую версию +## Release cycle: staging a new version -Когда в `develop` накопилось достаточно изменений для релиза, запускается -**финальное ревью тремя скиллами-оркестраторами** перед мержем/тегом: +When enough changes have accumulated on `develop` for a release, a **final +review by three orchestrator skills** runs before the merge/tag: -1. **test-orchestrator** (skill `code-review-orchestrator` с фокусом на - тестовом покрытии) — проверяет, что новый код покрыт тестами и нет - регрессий в существующих. -2. **review-orchestrator** (skill `code-review-orchestrator`) — - мульти-аспектный код-ревью: безопасность, стабильность, соответствие - конвенциям, регрессии, перегруженность. -3. **red-team-orchestrator** (red-team скилл) — адверсариальный анализ - атакующих сценариев на затронутые компоненты. +1. **test-orchestrator** (the `code-review-orchestrator` skill focused on test + coverage) — verifies new code is covered by tests and there are no + regressions in existing ones. +2. **review-orchestrator** (the `code-review-orchestrator` skill) — + multi-aspect code review: security, stability, convention conformance, + regressions, over-complexity. +3. **red-team-orchestrator** (the red-team skill) — adversarial analysis of + attack scenarios against the affected components. -Порядок: оркестраторы возвращают списки находок → агент правит всё, что -они нашли (через subagent или сам, по правилам делегирования) → повторно -прогоняет ревью затронутых мест → режет тег по процедуре «Cutting a -release» ниже. +Order: the orchestrators return finding lists → the agent fixes everything they +found (via a subagent or itself, per the delegation rules) → re-runs the review +on the affected areas → cuts the tag per the "Cutting a release" procedure +below. -## Шпаргалка по учёткам и endpoint'ам +## Accounts & endpoints cheat sheet -| Что | Значение | +| Item | Value | | --- | --- | -| Единственный remote для коммитов | `gitea` → `https://vvzvlad@gitea.vvzvlad.xyz/vvzvlad/gitmost.git` | -| Агентский user (Gitea/git) | `claude_code` | -| Агентский email | `claude_code@vvzvlad.xyz` | -| Пароль в keychain | `security find-generic-password -s gitea-claude-code -w` | -| PR API | `https://gitea.vvzvlad.xyz/api/v1/repos/vvzvlad/gitmost/pulls` (тут `gitmost` — реальный slug репо на сервере) | -| Базовая ветка | `develop` | -| `origin` | GitHub-зеркало `vvzvlad/gitmost` — **не пушить**, обновляется CI владельца | -| `upstream` | Оригинальный Docmost — **не пушить никогда** | +| Only remote for commits | `gitea` → `https://vvzvlad@gitea.vvzvlad.xyz/vvzvlad/gitmost.git` | +| Agent user (Gitea/git) | `claude_code` | +| Agent email | `claude_code@vvzvlad.xyz` | +| Keychain password | `security find-generic-password -s gitea-claude-code -w` | +| PR API | `https://gitea.vvzvlad.xyz/api/v1/repos/vvzvlad/gitmost/pulls` (here `gitmost` is the repo's real slug on the server) | +| Base branch | `develop` | +| `origin` | GitHub mirror `vvzvlad/gitmost` — **do not push**, updated by the owner's CI | +| `upstream` | The original Docmost — **never push** | --- -# Архитектура и кодовая база +# Architecture and codebase ## What this is