docs(agents): translate task lifecycle section to English

Update the task lifecycle documentation from Russian to English to improve
readability for English‑speaking contributors and ensure consistency across
the repository.
This commit is contained in:
claude_code
2026-06-22 18:40:32 +03:00
parent 8f01a01122
commit e598394f46

159
AGENTS.md
View File

@@ -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 <short-feature-name>
```
Никогда не пилит фичу прямо в `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/<name>`). 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 <claude_code@vvzvlad.xyz>
# both lines must show claude_code <claude_code@vvzvlad.xyz>
```
### 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: <branch>`. В теле PR — что сделано, что вне scope,
результаты верификации (tsc/lint/tests).
`base: develop`, `head: <branch>`. 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/<task>.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/<task>.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