Files

caoxiaozhu 6b0756a55f chore(logs): split agent change log outputs

2026-06-25 09:35:18 +08:00

6.3 KiB

Raw Blame History

name, description

name	description
agent-change-log	Use when working in X-Financial after bug fixes that need a split dev log, when maintaining document/development/YYYY-MM-DD/dev-logs/bugs, or when generating the daily 17:00 combined work-logs.med from same-day feature docs and bug logs.

Agent Change Log

Overview

This skill keeps split development logs for X-Financial. Bug fixes are recorded under the same-day dev-logs/bugs folder. Daily summaries combine same-day feature documents and bug records into one work-logs.med.

The log should sound like a careful teammate writing for tomorrow's teammate: concrete, warm, and honest.

When To Use

After fixing a bug.
When a post-commit hook detects a bug-like commit.
At the daily 17:00 summary pass.
Before updating the log in a branch where other agents may have pushed commits.
After verification, so the entry can include what was actually checked.
When a failed attempt changed files, generated artifacts, or revealed a risk worth preserving.

Do not create legacy document/work-log/YYYY-MM-DD.md entries for new work.

Log Location

Use the same date root as development documents:

document/development/YYYY-MM-DD/
├── feature/<feature-point>/CONCEPT.md + TODO.md
├── dev-logs/bugs/<bug-slug>.md
└── work-logs.med

If the date folder exists, reuse it. If not, create it.

Bug Log Structure

For bug fixes, create or update one file per bug:

document/development/YYYY-MM-DD/dev-logs/bugs/<bug-slug>.md

The file must contain ## 修复记录 and timestamped bullets similar to the old 当日工作内容. Do not add 遗留问题 or TODO sections to bug logs.

Use the helper when possible:

python3 tools/agent-change-log/update_change_log.py \
  --kind bug \
  --bug-title "<bug 名称>" \
  --bug-slug <bug-slug>

Required Git Check

Before writing or updating a bug log, manually check Git for upstream and local-ahead commits from other agents.

Run:

date '+%Y-%m-%d %H:%M:%S %Z'
git fetch --all --prune
git status -sb
git rev-parse --abbrev-ref --symbolic-full-name @{u}
git log --oneline --decorate --max-count=20 HEAD..@{u}
git log --oneline --decorate --max-count=20 @{u}..HEAD

Rules:

Treat git fetch --all --prune as the default safe "pull check"; it updates remote refs without merging into a dirty worktree.
Treat HEAD..@{u} as upstream commits not yet in local history.
Treat @{u}..HEAD as local commits not yet in upstream history; these may also come from another agent working in the same checkout.
If the worktree is clean and the branch is only behind upstream, git pull --ff-only may be used to fast-forward before analysis.
If the worktree is dirty, diverged, or likely to conflict, do not merge/rebase automatically. Record the upstream commits from HEAD..@{u} in the bug fix entry.
If there is no upstream branch, record that fact in the bug fix entry and continue with local-only logging.
When HEAD..@{u} has commits, summarize those commits in the bug fix entry before describing local edits. Mention commit hash, subject, and inferred impact.
When @{u}..HEAD has commits that were not created in the current task, summarize them too, because another local agent may have committed without pushing yet.
When no upstream or local-ahead commits exist, still record "Git 提交检查：未发现 upstream 新提交或本地 ahead 新提交" in the work entry.

Bug Entry Rules

Get the current local time first:
```
date '+%Y-%m-%d %H:%M:%S %Z'
```
Run the required Git check and capture whether upstream or local-ahead has new commits.
Ensure document/development/YYYY-MM-DD/dev-logs/bugs/ exists.
Create or update one <bug-slug>.md file for the specific bug.
Append a new timestamped bullet under ## 修复记录.
Mention Git commits, changed files or modules, the operation, the intent, and the verification result.
Do not add leftover issue or TODO sections.

Daily Summary

At 17:00 every day, generate the combined work log:

python3 tools/agent-change-log/update_change_log.py --kind summary

This reads:

document/development/YYYY-MM-DD/feature/
document/development/YYYY-MM-DD/dev-logs/bugs/

Then writes:

document/development/YYYY-MM-DD/work-logs.med

The summary should cover:

Today's feature points from feature/*/CONCEPT.md and TODO.md.
Today's bug fixes from dev-logs/bugs/*.md.
A concise combined analysis of what changed that day.

Entry Rules

For each bug entry, append a new timestamped bullet under ## 修复记录.
Mention Git commits, changed files or modules, the operation, the intent, and the verification result.
Do not write 遗留问题.
Do not write TODO.
If the change is a feature rather than a bug, use the development document skill to keep feature/<feature-point>/CONCEPT.md and TODO.md current instead of writing a bug log.

Writing Style

Write in Simplified Chinese.
Be specific and a little human: "我把...", "这次先...", "还需要留意..." are good.
Keep the tone factual. Do not turn the log into a victory lap.
Prefer concise file names and module names in prose, but include enough context to find the change.
Work content should be detailed enough that a future agent can continue without asking "你到底改了啥？"

Bug Entry Template

- HH:MM：记录 bug 修复：<bug 名称>。
  - Git 提交检查：<git fetch 后 HEAD..upstream 与 upstream..HEAD 的结果；没有就写未发现 upstream 或本地 ahead 新提交>。
  - 修改：<文件/模块>，<做了什么>。
  - 操作：<运行了什么命令、迁移了什么状态、重启了什么服务等>。
  - 验证：<测试/构建/检查结果；如果没跑，说明原因>。
  - 影响：<用户可见变化或工程边界变化>。

Final Response Checklist

Before saying work is complete:

For bug fixes, today's bug log exists under document/development/YYYY-MM-DD/dev-logs/bugs/.
For non-bug feature work, relevant feature/<feature-point> documents are current.
Git check ran for bug logs, and upstream plus local-ahead commits were summarized or explicitly marked as absent.
No new legacy document/work-log/YYYY-MM-DD.md entry was created.
The final response mentions whether a bug log, feature document, or daily work-logs.med was updated.

6.3 KiB Raw Blame History Unescape Escape