log-session

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Log Session

会话日志记录

Capture the why and the what-next of a working session — the context that git history alone never records. A commit says what changed; a session log says what you were trying to do, what you decided, and where to resume.

Deliberately cheap (

sonnet

medium

): this is structured summarization, not judgment. It must never reach for an expensive model.

记录工作会话的动机和后续计划——这些是仅靠git历史无法记录的上下文信息。提交记录仅说明发生了什么变更；而会话日志则会说明您试图完成的目标、做出的决策以及后续从何处继续工作。

刻意选用低成本模型（

sonnet

medium

）：此工具仅用于结构化总结，而非评判。绝对不允许使用高成本模型。

Turn contract — verify before ending the turn

回合约定——结束回合前请验证

✓ The entry was APPENDED to docs/LOGS.md (file edited, not just drafted) with accurate git facts
✓ No past entry was edited
✓ Artifact language: explicit user instruction > the project's declared docs language > English. The CONVERSATION language never decides — a Spanish prompt still produces English PRs/issues/commits/SPECs unless one of the first two says otherwise
✓ The closing `→ Next:` block is printed as the ABSOLUTE last output

About to end the turn with any box unchecked? The turn is NOT done — complete the missing box first (weak models drop end-of-document duties; this list is first on purpose).

✓ 条目已追加至docs/LOGS.md（已编辑文件，而非仅草稿），且git相关信息准确
✓ 未编辑过往条目
✓ 文档语言优先级：明确的用户指令 > 项目声明的文档语言 > 英文。会话语言不决定文档语言——除非前两者有明确要求，否则即使使用西班牙语提示，仍会生成英文PR/议题/提交/SPEC文档
✓ 结尾的`→ Next:`块是最后输出的内容

如果结束回合时有任何一项未勾选？则回合未完成——请先完成未勾选的项（弱模型可能会忽略文档收尾工作，因此将此列表放在最前面）。

When to use

使用时机

Before
/clear
(or your agent's context-reset equivalent) — you're about to wipe context; capture it first.
Before closing your agent for the day.
At a natural stopping point — a feature paused mid-way, a thread you want to be able to resume cold.
After a long session with several decisions worth remembering.

This is the manual, rich counterpart to the lightweight auto-logging hooks the

template/

ships (see

template/.claude/

). The hooks capture the mechanical facts for free on every exit; this skill writes the thoughtful entry when you want one.

执行
/clear
前（或您的Agent的上下文重置等效操作）——您即将清除上下文，请先记录下来。
每日关闭Agent前。
自然停顿点——功能开发中途暂停、需要后续能直接继续的工作线程。
长会话结束后——会话中做出了多个值得记录的决策。

此工具是

template/

自带的轻量自动日志钩子（详见

template/.claude/

）的手动增强版。钩子会在每次退出时自动记录机械性信息；而当您需要更详尽的记录时，可使用此技能编写有思考性的条目。

Step 0 — Discover the project (always first)

步骤0——先了解项目（必做第一步）

Per the agent guide's Workflow conventions + documentation map, locate the session log. Default path:

docs/LOGS.md

. If the documentation map names a different location, use that. If no log file exists yet, create it from the shape in

template/docs/LOGS.md

(a short header + the entry format below) and say so.

If a session-start marker exists (

.claude/.session-*.start

, written by the template's SessionStart hook), read it to bound the session precisely — it holds the HEAD sha and start time at session open.

根据Agent指南的工作流约定 + 文档映射，找到会话日志的位置。默认路径：

docs/LOGS.md

。如果文档映射指定了其他位置，则使用该位置。如果日志文件尚未存在，请根据

template/docs/LOGS.md

的格式（简短标题 + 下方的条目格式）创建文件，并告知用户。

如果存在会话开始标记（

.claude/.session-*.start

，由模板的SessionStart钩子生成），请读取该标记以精准界定会话范围——它包含会话开启时的HEAD哈希值和开始时间。

Process

流程

Establish the session boundary.
- If a marker is present, the session spans
```
marker_sha..HEAD
```
  plus any uncommitted work.
- Otherwise, use your own conversation context as the source of truth for what happened this session, and corroborate with
```
git log
```
  of the recent commits and
```
git status
```
  /
```
git diff --stat
```
  for uncommitted changes.
Gather the mechanical facts (cheaply, with git):
- branch (
```
git branch --show-current
```
  ),
- commits this session (
```
git log --oneline <since>..HEAD
```
  ),
- files touched (
```
git diff --stat <since>..HEAD
```
  + uncommitted).
Write the narrative — the part only you can add:
- Summary: 1–3 sentences on what this session set out to do and what actually got done.
- Decisions: the non-obvious choices made and why (the rationale that would otherwise be lost). Link related docs/issues.
- Next: the concrete next step(s) — the command to run, the unfinished thread, the open question. Write it so a cold reader knows exactly where to resume.

Append the entry to

docs/LOGS.md

, newest at the bottom (append-only, chronological). Use this format so the auto-hook entries and these stay compatible:

markdown

## <ISO-8601 timestamp> — <branch> — manual
- **Commits:** <n> (`<short-sha>…<short-sha>`)
- **Files:** <comma-separated paths, or a count if many>
- **Summary:** <what this session did>
- **Decisions:** <key choices + why; omit the line if none>
- **Next:** <the concrete next step>

If the user passed a note as an argument, prepend it to the Summary.

Commit policy.
```
docs/LOGS.md
```
is documentation — keep it coherent, but do not open a PR just for a log entry. If you're mid-feature on a branch, the entry rides along with the next commit. If the working tree is otherwise clean and the user wants it persisted, ask before committing a standalone
```
docs(log): session <date>
```
commit. Never push without the project's push convention.

确定会话范围
- 如果存在标记，会话范围为
```
marker_sha..HEAD
```
  加上所有未提交的工作。
- 如果没有标记，则以您的会话上下文为事实来源，结合
```
git log
```
  查看近期提交记录，以及
```
git status
```
  /
```
git diff --stat
```
  查看未提交变更，来确认本次会话的内容。
收集机械性信息（通过git低成本获取）：
- 当前分支（
```
git branch --show-current
```
  ），
- 本次会话的提交记录（
```
git log --oneline <since>..HEAD
```
  ），
- 涉及的文件（
```
git diff --stat <since>..HEAD
```
  + 未提交文件）。
编写叙事内容——这部分只有您能补充：
- 摘要：1-3句话说明本次会话的目标及实际完成的工作。
- 决策：记录非显而易见的选择及其原因（否则这些理由会丢失）。关联相关文档/议题。
- 下一步：具体的后续步骤——要执行的命令、未完成的工作线程、待解决的问题。内容需清晰到让不了解上下文的人也知道从何处继续。

追加条目至
docs/LOGS.md
，最新条目放在底部（仅追加，按时间顺序）。使用以下格式，确保自动钩子生成的条目与手动条目兼容：

markdown

## <ISO-8601时间戳> — <分支名称> — manual
- **Commits:** <数量> (`<短哈希>…<短哈希>`)
- **Files:** <逗号分隔的路径，若文件数量过多则写数量>
- **Summary:** <本次会话完成的工作>
- **Decisions:** <关键选择及原因；若无则省略此行>
- **Next:** <具体下一步计划>

如果用户传入了备注作为参数，请将其添加到摘要开头。

提交策略。
```
docs/LOGS.md
```
属于文档——保持内容连贯，但不要仅为日志条目创建PR。如果您正在分支上开发功能，日志条目可随下一次提交一起提交。如果工作树已清理，且用户希望持久化日志条目，请先询问用户是否要单独提交一条
```
docs(log): session <日期>
```
的记录。未遵循项目推送约定时，切勿推送。

Guardrails

约束规则

Never use an expensive model for this. It's summarization;
```
sonnet
```
is the ceiling, and the hooks do the free mechanical version.
Don't invent facts. Decisions and next steps come from the actual session (your context + git), not plausible-sounding filler. If a section has nothing real, omit its line rather than padding.
Append, never rewrite. Past entries are a historical record — don't edit or "tidy" them. Same reasoning as not rewriting a delivered feature's planning artifacts.
One file, append-only. Don't fan session logs across files.

绝对不要使用高成本模型。此工具仅用于总结，
```
sonnet
```
已是上限，钩子会处理免费的机械性记录。
不要编造信息。决策和下一步计划必须来自实际会话（您的上下文 + git信息），而非看似合理的填充内容。如果某部分没有实际内容，省略该行而非凑数。
仅追加，绝不改写。过往条目是历史记录——不要编辑或“整理”它们。这与不修改已交付功能的规划文档是同一道理。
单一文件，仅追加。不要将会话日志分散到多个文件中。

Portability (agents other than Claude Code)

可移植性（非Claude Code的Agent）

The workflow is the contract; Claude Code features are conveniences. On an agent that lacks one, apply the fallback — never skip the step the feature enables:

No Claude Code hooks — the template's auto-logging hooks (SessionStart marker, SessionEnd entry) don't run on other agents, so there is no marker file and no free mechanical entry: this skill is the only journal writer. Run it before ending every session, and bound the session with git alone (Process step 1's no-marker path).
No
/clear
— read it as your agent's context-reset / new-conversation equivalent, in the triggers and in the closing block alike.
No per-skill
model:
/
effort:
— the intent stands: use a cheap model for this. It's summarization, never judgment.

工作流是核心约定；Claude Code的功能只是便利项。如果使用的Agent缺少某项功能，请使用替代方案——绝不能跳过该功能对应的步骤：

无Claude Code钩子——模板的自动日志钩子（SessionStart标记、SessionEnd条目）在其他Agent上无法运行，因此没有标记文件，也没有免费的机械性条目：此技能是唯一的日志记录工具。每次会话结束前都要运行它，并仅通过git界定会话范围（流程步骤1中无标记的情况）。
无
/clear
命令——将其视为您的Agent的上下文重置/新建会话等效操作，在触发指令和结尾块中均按此处理。
无针对单个技能的
model:
/
effort:
设置——核心意图不变：使用低成本模型。此工具仅用于总结，而非评判。

Relationship to other skills

与其他技能的关系

Complements the
```
template/
```
's SessionEnd hook (free, mechanical, automatic on
```
/clear
```
and exit) and the opt-in SessionStart restore hook (re-injects the last entry to resume context). This skill is the rich, manual entry.
Pairs with
```
execute-phase
```
's per-feature
```
progress.md
```
: that tracks progress within a feature; the session log is cross-cutting — whatever you touched this session, across features/fixes.
Not part of the PR gate — it's a working-memory aid, not a merge artifact.

补充
```
template/
```
的SessionEnd钩子（免费、机械性、
```
/clear
```
和退出时自动运行）和可选的SessionStart恢复钩子（重新注入最后一条条目以恢复上下文）。此技能是更详尽的手动条目工具。
与
```
execute-phase
```
的每个功能对应的
```
progress.md
```
搭配使用：
```
progress.md
```
跟踪单个功能内的进度；而会话日志是跨功能的——记录本次会话中涉及的所有工作，包括不同功能/修复任务。
不属于PR审核要求——它是工作记忆辅助工具，而非合并工件。

Done when

完成标志

A new entry is appended to
```
docs/LOGS.md
```
with at least Summary and Next.
The mechanical facts (branch, commits, files) are accurate to git.

The closing
→ Next:
block is printed:

→ Next: /clear (or your agent's context reset) is now safe — the session is captured
  · resume later → the command named in the entry's **Next** line

```
docs/LOGS.md
```
中已追加新条目，至少包含摘要和下一步计划。
机械性信息（分支、提交记录、文件）与git信息一致。

已输出结尾的
→ Next:
块：

→ Next: /clear（或您的Agent的上下文重置操作）现在可以安全执行——会话内容已记录
  · 后续继续工作 → 执行条目**Next**行中指定的命令