Large Project Work Maintenance

触发与时机

两个调用时机，分工不同：

时机	做什么
进入时（动手写代码前）	阶段 1（读文档知上下文）+ 阶段 2 准备
完成时（变更验证通过后）	阶段 3（强制文档同步）+ 阶段 4（验证无遗漏）

• 显式触发：CLAUDE.md 写明"每次启动会话必须先调用本 skill"；用户说"更新 PROGRESS/同步文档/记录工作"。
• 隐式触发：根目录有 CLAUDE.md 且定义了同步规则；完成了任何代码变更（修 bug/功能/重构）。
• 不触发：无四文件体系（先「myworkflow:project-init」）、纯问答/代码解释/文件阅读（无变更）、单文件脚本/临时小工具。

核心原则

文档是工作的副产品，不是额外负担——边做边在脑中组织 PROGRESS 条目，写时就是填空。

前置强制步骤

1. 向上查找 CLAUDE.md 找到项目根目录。
2. 读 CLAUDE.md 了解规则和同步约定。
3. 读 PROGRESS-LITE.md 了解最近动态（≤200 行全读，否则读最近 3 天）。

四阶段维护

主线：进入时 阶段1（工作前）→ 阶段2（工作中准备）→ 实际开发 → 完成时 阶段3（工作后）→ 阶段4（验证）。

阶段 1：工作前 — 读文档知上下文

• 必须读：CLAUDE.md（规则）、PROGRESS-LITE.md（最近动态）。
• 按需读：STRUCTURE.md（找文件时）、PROGRESS.md 相关条目（了解之前类似工作）。

阶段 2：工作中 — 边做边记

以对话中简短 Markdown 列表维护变更草稿：开始前列预期修改文件清单 → 每完成一个文件标注操作（Add/Modify/Delete）+ 一句话原因 → 全部完成后核对验证结果。它为阶段 3 提供原材料，避免空白开始。

阶段 3：工作后 — 强制文档同步

代码变更完成且验证通过后立即按顺序更新，不可跳过、不可推迟。

3.1 更新 PROGRESS.md（详细条目）

新条目永远插在 --- 分隔线下一行（内容区最顶部，最新在最前）；今日日期标题已存在则其下追加子标题。

## YYYY-MM-DD

### [标签] 简短标题

问题描述 / 变更原因：
（背景和动机）

根因分析：（仅 bug 修复需要）
（为什么会发生、为什么之前没发现、为什么这样修复）

修改文件：
- [操作]: `路径/到/文件` — 改了什么

验证：
（构建/测试/手动验证结果）

标签：[New Feature] 新增 / [Debug] 修复 / [Change] 重构优化 / [Build] 构建部署。

好条目示例（坏例 = 3 个月后看不懂的"修复了一个 bug/修好了"）：

### [Debug] 修复登录超时后未重定向到登录页
问题描述：用户会话过期后 API 返回 401，前端未拦截重定向，将 401 当正常数据显示 "undefined"。
根因分析：axios 拦截器只处理 200/201/404/500，401 落 default 分支；该拦截器 2026-03 重构时移入 AuthContext，遗漏 401 case；测试期 token 有效期 7 天从未触发过期。
修改文件：
- Modify: `src/api/interceptors.ts` — 新增 401 case，清 token 并 redirect 到 /login
- Modify: `src/api/interceptors.test.ts` — 新增 401 拦截测试（2 tests）
验证：pnpm test（48 files, 312 tests）通过；手动清除 cookie 刷新确认跳转登录页。

根因分析怎么写：不只说现象（"少一行代码"），追问"为什么少？什么时候少？为什么之前没暴露"——指向流程问题（重构遗漏）、假设错误、测试覆盖不足。

3.2 更新 PROGRESS-LITE.md（精简条目）

同样插在 --- 下一行，最新在前。格式：## YYYY-MM-DD 下每行一条 - [标签] 一句话做了什么。

约束：每条严格一行（LITE 的价值是能一次读几百条）；只写"做了什么"不写"为什么"；同日多条按重要性排序 [New Feature] > [Debug] > [Change] > [Build]；同日 >10 条用子标题分组。

3.3 检查并更新 STRUCTURE.md

需要更新：新增/删除/重命名文件或目录；不需要：仅修改文件内容。更新对应目录树条目、加用途注释、更新顶部日期。

3.4 检查并更新 CLAUDE.md

仅在根目录结构变化、核心规则变化、新增子项目时更新；大多数日常变更不需要。

阶段 4：验证 — 确保无遗漏

4.1 变更覆盖检查（git）

# Bash: 覆盖有历史commit/仅一个commit/无commit
(git rev-parse --verify HEAD >/dev/null 2>&1 && git diff --name-only HEAD~1 2>/dev/null) || git status --short

# PowerShell 等效
if (git rev-parse --verify HEAD 2>$null) { git diff --name-only HEAD~1 2>$null } else { git status --short }

确保每个变更文件都在 PROGRESS.md 有记录。局限：只查最近一次提交；一次会话多次独立提交可能漏——每次同步完立即提交，或 git log --oneline 手动比对。单 commit 仓库 fallback 到 git status --short 时只看 M/A/D 忽略 ??。git 不可用则手动回忆逐一核对。

4.2 结构一致性检查

Glob 扫描关键目录（src/tests/docs/config），对照 STRUCTURE.md：文件系统有而文档无 → 补上；文档有而文件系统无 → 删过时条目；路径不匹配 → 修正。文件 >100 时只查本次变更涉及的目录。

4.3 日期检查

PROGRESS.md 和 PROGRESS-LITE.md 顶部是否有今天的日期标题？没有 → 现在补。

4.4 输出验证摘要

📋 文档同步完成：
✓ PROGRESS.md — 已追加 1 条详细记录
✓ PROGRESS-LITE.md — 已追加 1 条精简记录
✓ STRUCTURE.md — 无需更新（本次无文件增删）
✓ CLAUDE.md — 无需更新

如有遗漏已补正，用 ⚠️ 已补正 标记。

项目规模适配

规模	文件数	处理
小型	<20	PROGRESS 简短条目（一句话根因）；STRUCTURE 顶层+1层
中型	20-100	标准条目（bug 必写根因）；STRUCTURE 顶层+2层
大型	100-500	完整条目（全写根因）；LITE 可按阶段分组；STRUCTURE 顶层+3层+核心事实
超大型	>500	根+子项目各自维护

常见问题

• 改一行也要更新？ 独立有意义的变更——是；连续小改动可合并一条。
• PROGRESS.md 太大？ 先读 LITE，需要细节用 Grep 定位：grep -A 50 "## 2026-07-09" PROGRESS.md，别用 Read 读整个大文件。
• 忘了实时记录？ 看 git log 回顾今天的变更补写；阶段 4 日期检查会发现遗漏。
• 一次会话多组独立变更？ 各占一条 ### 子标题共享日期标题；LITE 各占一行，按重要性排序。
• CLAUDE.md vs STRUCTURE.md？ CLAUDE.md 是行为手册（怎么做），STRUCTURE.md 是空间地图（文件在哪）。