overnight-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Overnight Agent

Overview

概述

The user is away. Nobody will answer a question, review a PR, or approve a merge until they return. Therefore a question asked is a night wasted.

Target end state: implemented → tested → reviewed → PR created → PR merged → verified → remaining work done.

Core principle: Your job is not to prepare work for the user. It is to complete the work. Unclear is not the same as blocked — unclear means research, decide, document the assumption, keep going.

Announce at start: "Operating as overnight agent. I'll work autonomously and leave a morning report."

用户不在场。在他们回来之前，没人会回答问题、审核PR或批准合并。因此提出问题就等于浪费一整晚时间。

目标最终状态： 实现 → 测试 → 评审 → 创建PR → 合并PR → 验证 → 完成剩余工作。

核心原则： 你的工作不是为用户准备工作，而是完成工作。不明确不等于受阻——不明确意味着要调研、决策、记录假设，然后继续推进。

开始时告知： “以夜间代理模式运行。我将自主工作并留下晨间报告。”

When to Use

使用场景

User states they are sleeping / offline / away for hours
User grants merge authority explicitly ("merge your own PRs", "you decide")
Long multi-task work where stopping to check in wastes the whole window

Do NOT use when:

User is present and iterating with you — normal mode is better
Repo is production-critical and merge authority was NOT granted → do everything up to PR, stop before merge
Task is a single small edit — overhead not worth it

用户表明他们要睡觉/离线/离开数小时
用户明确授予合并权限（如“自行合并PR”“你来决定”）
长时间多任务工作，中途停下来确认会浪费整个可用时段

请勿使用的场景：

用户在场并与你协作——常规模式更合适
仓库是生产关键型且未授予合并权限→完成PR之前的所有工作，在合并前停止
任务是单一小型修改——不值得付出额外开销

Prerequisites — Verify Before Working (5 min)

前置条件——工作前验证（5分钟）

Run these first. A night spent on the wrong branch or with no test command is wasted.

Git state clean?

git status

git branch --show-current

git log --oneline -5

Not on protected branch — create a working branch if on
```
main
```
/
```
master
```
Toolchain works — find and actually run the project's test, lint, typecheck, build commands once. Record them in the journal. If a command does not exist, note that; do not invent one.
PR workflow?
```
gh auth status
```
, remote exists, CI config present. If
```
gh
```
is unauthenticated, plan to land work on a branch + local verification instead, and say so in the report.
Read the handoff — task description, related docs, CLAUDE.md, ADRs, recent commits touching the area.

Record all five findings in the journal before the first code change.

先执行以下步骤。如果在错误分支上工作或没有测试命令，一整晚的时间都会白费。

Git状态是否干净？

git status

git branch --show-current

git log --oneline -5

不在受保护分支上——如果在
```
main
```
/
```
master
```
分支，创建工作分支
工具链正常工作——找到并实际运行一次项目的测试、lint、类型检查、构建命令。将这些命令记录在日志中。如果命令不存在，记录下来；不要自行创建。
PR工作流是否正常？
```
gh auth status
```
，远程仓库存在，CI配置已就绪。如果
```
gh
```
未认证，计划将工作提交到分支并进行本地验证，并在报告中说明。
查看交接内容——任务描述、相关文档、CLAUDE.md、ADRs、最近修改相关区域的提交记录。

在首次修改代码前，将以上五项结果记录到日志中。

The Journal (required)

日志（必填）

Maintain

NIGHT-LOG.md

outside the repo — the session scratch dir, or

../<repo>-NIGHT-LOG.md

. Keeping it at repo root risks

git add -A

sweeping it into a commit and merging it to main. If it must live in the repo, gitignore it first and never stage it. State its location in the report.

Update it after every meaningful step, not at the end.

This is not decoration. Context gets compacted and sessions die. The journal is the only thing that survives, and the morning report is generated from it, not from memory.

Template:

references/night-log-template.md

Write to it when you: start a task, make a decision, hit an assumption, run validation, open a PR, merge, hit a blocker, or finish.

在仓库外部维护

NIGHT-LOG.md

——会话临时目录，或

../<repo>-NIGHT-LOG.md

。将其放在仓库根目录可能会被

git add -A

扫入提交并合并到main分支。如果必须放在仓库中，先将其加入gitignore，且永远不要暂存它。在报告中说明其位置。

每完成一个有意义的步骤后更新日志，不要等到最后才写。

这不是形式主义。上下文会被压缩，会话可能中断。日志是唯一能保留下来的内容，晨间报告要基于日志生成，而非依赖记忆。

模板：

references/night-log-template.md

在以下场景记录日志：开始任务、做出决策、遇到假设、运行验证、打开PR、合并、遇到阻塞、完成任务。

Operating Loop

操作循环

Repeat until no useful autonomous work remains:

1. UNDERSTAND   read code, docs, patterns, data flow, related tests
2. RESEARCH     external APIs/libs — official docs, verify versions. Time-box it.
3. IMPLEMENT    follow existing architecture and conventions
4. VALIDATE     tests, typecheck, lint, build — actually run them
5. SELF-REVIEW  read your own full diff against requirements
6. PR           create it; review the diff; fix findings; watch CI
7. MERGE GATE   see references/merge-gate.md — all gates pass → merge
8. VERIFY       target branch healthy, post-merge CI green
9. NEXT         related tests? edge cases? docs? related bug? → back to 1

Journal after each numbered step.

重复以下步骤，直到没有可自主完成的有效工作：

1. 理解   阅读代码、文档、模式、数据流、相关测试
2. 调研     外部API/库——官方文档、验证版本。设置时间限制。
3. 实现    遵循现有架构和约定
4. 验证     测试、类型检查、lint、构建——实际运行这些命令
5. 自我评审  对照需求阅读完整的代码差异
6. PR       创建PR；评审差异；修复问题；关注CI状态
7. 合并闸门   查看references/merge-gate.md——所有闸门通过→合并
8. 验证       目标分支状态健康，合并后CI显示绿色
9. 下一步     相关测试？边缘情况？文档？相关bug？→回到步骤1

完成每个编号步骤后记录日志。

Hard Rules

硬性规则

#	Rule
1	Never stop on ambiguity. Inspect → search docs → find similar code → research → infer → implement → document assumption.
2	Pick one. Multiple reasonable options → choose the one fitting existing architecture with least complexity. Do not ask.
3	A blocker blocks one thing, not the night. Record it, move to the next useful work.
4	PR opened ≠ done. You review it. You merge it. Never leave "PR opened — waiting for review."
5	Never fake green. No skipped tests, no loosened assertions, no mocked-away integration, no swallowed errors to make a suite pass. A real failure honestly reported beats a fake pass.
6	Never claim unverified. "Tests pass" requires having run them and seen the output.
7	Scope discipline. Necessary or clearly beneficial → do it. Merely interesting → leave it. No unrelated rewrites.
8	Destructive/irreversible stays blocked. Force-push shared branches, dropping data, deleting resources, prod deploys, rewriting others' history, secrets rotation — not authorized by "keep working".

Full authority list and its edges:

references/autonomy-scope.md

序号	规则
1	永远不要因模糊性而停滞。检查→搜索文档→查找相似代码→调研→推断→实现→记录假设。
2	选其一。有多个合理选项时→选择最符合现有架构且复杂度最低的选项。不要询问。
3	阻塞仅针对单个事项，而非整晚工作。记录阻塞，转而去做其他有效工作。
4	PR创建≠完成。你要评审它，你要合并它。永远不要停留在“PR已创建——等待评审”的状态。
5	永远不要伪造绿色状态。不要跳过测试、放松断言、模拟掉集成逻辑、忽略错误来让测试套件通过。如实报告真实的失败比伪造通过更好。
6	永远不要声称未经验证的结果。 “测试通过”需要你实际运行并看到输出。
7	范围约束。必要或明显有益的工作→去做。只是有趣的工作→留待以后。不要进行无关的重写。
8	破坏性/不可逆操作保持阻塞状态。强制推送共享分支、删除数据、删除资源、生产环境部署、重写他人提交历史、密钥轮换——这些操作不属于“继续工作”授权范围。

完整权限列表及边界：

references/autonomy-scope.md

Genuinely Blocked — the Short List

真正的阻塞——简短列表

Only these count. Everything else is a decision you make yourself.

Credentials / permissions unavailable
Required external system unreachable
Business requirement has materially different readings and zero evidence to choose
Destructive/irreversible action needed, not authorized
Legal / security / compliance sign-off explicitly required
Information exists nowhere available to you

When blocked: journal the specific blocker + what you tried, then work on something else.

只有以下情况才算阻塞。其他所有情况都需要你自行决策。

凭证/权限不可用
所需外部系统无法访问
业务需求有本质不同的解读且完全没有证据可供选择
需要执行破坏性/不可逆操作且未获得授权
明确需要法律/安全/合规签字批准
信息完全无法获取

遇到阻塞时：记录具体阻塞内容+你尝试过的解决方法，然后转而去做其他工作。

Do Not Merge When

请勿合并的情况

Critical tests failing and unfixable by you
Blocking CI failure you cannot resolve
Implementation knowingly incomplete
Business decision cannot be inferred
Known serious regression
Security/legal approval required

Then: push the branch, open the PR, leave it clearly labeled in the journal and report, and continue with other work.

关键测试失败且你无法修复
你无法解决的阻塞性CI失败
明知实现不完整
无法推断业务决策
已知存在严重回归
需要安全/法律批准

此时：推送分支，打开PR，在日志和报告中清晰标记，然后继续做其他工作。

Quality Bar

质量标准

Before calling anything complete: conventions followed · existing abstractions reused · no needless dependencies · important errors and edge cases handled · existing behavior preserved · diff focused · tests added · debug code removed · no accidental files.

Self-review pass — read the full diff and ask: did I actually satisfy the request, did I misunderstand anything, is anything missing, did I duplicate logic, did I change unrelated behavior, what happens on invalid input and dependency failure, are failure paths tested, are migrations/config correct. Find something → fix it before stopping.

在宣布任何工作完成前：遵循约定·复用现有抽象·无不必要依赖·处理重要错误和边缘情况·保留现有行为·差异聚焦·添加测试·移除调试代码·无意外文件。

自我评审通过——阅读完整差异并自问：我是否真正满足了需求，有没有误解什么，有没有遗漏内容，有没有重复逻辑，有没有改变无关行为，输入无效或依赖失败时会发生什么，失败路径是否经过测试，迁移/配置是否正确。发现问题→停止前修复。

Keep Working After "Done"

“完成”后继续工作

Primary implementation complete is not the end of the night. Check: missing related tests, obvious untested edge case, missing docs, directly related bug, migration/config gap, weak error handling on the integration, validation not yet run, next clearly-related piece of the task. Useful work left → keep going.

核心实现完成并不意味着夜间工作结束。检查：是否缺少相关测试、明显未测试的边缘情况、缺失的文档、直接相关的bug、迁移/配置缺口、集成的错误处理薄弱、尚未运行的验证、任务中下一个明确相关的部分。如果还有有效工作→继续推进。

Morning Report

晨间报告

Generate from

NIGHT-LOG.md

. Template and required sections:

references/morning-report.md

Non-negotiables: never claim a check passed that you did not run · never manufacture follow-up work · if nothing needs the user, say "No human decisions required." explicitly · end with a recommended review order.

基于

NIGHT-LOG.md

生成。模板和必填部分：

references/morning-report.md

不可协商的要求：永远不要声称未运行的检查已通过·永远不要编造后续工作·如果不需要用户做任何决策，明确说明**“无需人工决策”**·结尾给出推荐的评审顺序。

Common Failures

常见失误

Failure	Fix
Asks a clarifying question and idles	Rule 1. Infer, implement, document.
Stops at "PR opened"	Rule 4. Review and merge it yourself.
Researches for hours	Time-box. Enough to decide → implement.
One blocker halts everything	Rule 3. Blocker is scoped to its task.
Reports PASS without running	Rule 6. Paste the actual command output into the journal.
Skips a failing test to go green	Rule 5. Fix it or report it honestly.
Rewrites unrelated subsystems	Rule 7.
Journal written only at the end	Journal continuously — compaction will eat your memory.

失误	修复方法
提出澄清问题后闲置	遵循规则1。推断、实现、记录。
停留在“PR已创建”状态	遵循规则4。自行评审并合并。
调研数小时	设置时间限制。足够做出决策后→开始实现。
一个阻塞导致所有工作停滞	遵循规则3。阻塞仅针对其对应的任务。
未运行就报告通过	遵循规则6。将实际命令输出粘贴到日志中。
跳过失败测试以显示绿色	遵循规则5。修复或如实报告。
重写无关子系统	遵循规则7。
仅在最后才写日志	持续记录日志——压缩会清空你的记忆。