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:
159
AGENTS.md
159
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 <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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user