# Engineering Journal

> Use when work in a Git repository needs a persistent engineering dossier, work item, investigation record, quick handoff, topic ledger, analysis report, or reusable evidence across projects or sessions.

- Skill: `xylvvv/engineering-journal` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add xylvvv/engineering-journal`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xylvvv/engineering-journal/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: xylvvv (https://skillmd.com/u/xylvvv)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xylvvv/engineering-journal

---


# Engineering Journal

在 Engineering KB 根目录中创建、恢复或更新工程档案。默认 KB 根目录是 `~/Documents/Obsidian/KB/engineering`；如果用户明确指定其他 KB 路径、本地知识库路径或团队约定路径，则使用用户指定路径作为本轮 KB 根目录。此 skill 只负责事实沉淀与接力，不代替规划、调试、实现、评审或验证流程。以当前仓库和可复现证据为事实源；不得把 Memories 或未经验证的历史上下文当作事实。

本文中的 `<KB_ROOT>` 均指上述 KB 根目录。读取或运行 skill 内脚本、内置模板时，使用本次加载到的 `engineering-journal` skill 所在目录。

## 识别项目

先运行：

```bash
cd <engineering-journal-skill-dir> && node scripts/project_identity.mjs
```

脚本只读 Git，输出 `git_root`、`git_common_dir`、`branch`、`head`、`sanitized_remote`、`project_id` 和 `project_key`。`project_id` 保留完整 sanitized remote；`project_key` 默认使用远端仓库 basename，无远端时使用 Git root basename。同一 common dir 的 worktree 属于同一项目。脚本失败表示当前目录不属于 Git 仓库：不要创建档案，先说明并确认用户意图。

## 搜索与路径

1. 在 KB 根目录搜索 Markdown 文件名和内容中的 `project_id`、`project_key`、安全化远端、Git root、任务关键词、issue ID、别名和相关链接。
2. 检查候选文档的项目身份、范围、更新时间和关联关系。精确匹配时原地恢复；多个候选冲突时先消歧，不得创建近似重复档案。
3. 脚本输出的 basename key 是首选。只有搜索现有档案或 registry 发现同一 `project_key` 对应不同 `project_id` 时才升级：先用 `<owner>-<repo>`；仍冲突时追加 `project_id` 的稳定短 hash。不要因“可能冲突”预先扩大 key。
4. 沿用已有项目布局。仅在无匹配文档时使用最终消歧后的 key 和以下绝对路径，不得额外拼接 `engineering`：
   - `<KB_ROOT>/projects/<project-key>/work-items/<task-slug>.md`
   - `<KB_ROOT>/projects/<project-key>/topics/<topic-slug>.md`
   - `<KB_ROOT>/projects/<project-key>/evidence/YYYY-MM-DD-<record-slug>.md`

## 新项目自动初始化

当脚本识别出 Git 项目，但 KB 中没有匹配项目入口时，不要求用户手动初始化。按需自动创建最小 KB 和项目容器：

1. 若 `<KB_ROOT>` 不存在，创建 `<KB_ROOT>`、`<KB_ROOT>/projects` 和 `<KB_ROOT>/_templates`。
2. 若 `<KB_ROOT>/_templates` 缺少必需模板，从 skill 内置 `templates/` 复制缺失模板；不得覆盖用户已修改的同名 KB 模板。
3. 创建 `<KB_ROOT>/projects/<project-key>/` 及 `work-items/`、`topics/`、`evidence/`、`raw/`、`events/` 子目录。
4. 从 `<KB_ROOT>/_templates/project-index.md` 创建 `index.md`，填入 `project_key`、标题、`project_id`、当前 Git root、branch、HEAD、远端摘要和创建时间。
5. 若 `<KB_ROOT>/projects/_registry.md` 存在且尚未包含该项目链接，追加 `[[engineering/projects/<project-key>/index|<project-key>]]`；若 registry 不存在，先创建最小 registry。
6. 再创建本轮需要的 `work-item`、`topic` 或 `evidence`。项目初始化和首份档案创建应写入项目入口事件日志。

自动初始化只建立空容器和索引，不迁移、不复制、不重命名旧资料；发现可能已有同项目旧目录但身份不确定时，先记录候选并向用户确认。

## 选择档案类型

| 主类型 | 使用条件 | 默认目录 |
|---|---|---|
| `work-item` | 有边界的 bug、需求、重构、发布或一次性交付，需要跨会话接力 | `work-items` |
| `topic-ledger` | 长期演进的模块、机制或技术主题，需要持续累积事实与决策 | `topics` |
| `analysis-report` | 某时点的调查、事故复盘、架构或代码分析，需要形成稳定结论 | `evidence` |

默认选择 `work-item`。只有生命周期、复用范围或读者明显不同才拆文档，并用 `related` 链接关联，避免复制。

复杂或可复用分析必须从主档案拆出 `evidence-record`，存入 `evidence`。evidence record 的 frontmatter 必须包含：

- `validity`: `current`、`stale`、`superseded` 或 `disputed`
- `observed_at`: 带时区的绝对时间
- `source_revision`: 观察时的完整 Git commit SHA
- `supersedes`: 被当前记录替代的 evidence record 链接数组

当代码、配置或环境已越过 `source_revision` 且尚未复核时，将 `validity` 改为 `stale`。新记录替代旧记录时，新记录填写 `supersedes`，旧记录改为 `superseded` 并链接新记录。

## 工作项状态机

`status` 只允许出现在 frontmatter。`work-item` 的状态值和转换固定为：

- `backlog -> active`
- `active -> blocked | done | cancelled`
- `blocked -> active | done | cancelled`
- `done -> active`，仅通过 `reopen`
- `cancelled -> active`，仅通过 `reopen`
- `backlog -> cancelled`

禁止其他转换。每次转换都更新时间并写一条事件；正文不得创建 `Status` 标题或字段。

## 正文约束

正文只维护两个操作区块；按需读取 [templates.md](references/templates.md)：

1. `Current Snapshot`：最多 8 个顶层条目，使用标签维护以下信息：
   - `Quick Handoff`：目标、当前进展、下一步、阻塞点、可直接执行的下一条命令
   - `Confirmed Fact`：结论及文件行号、commit、命令/测试摘要或“用户明确提供”
   - `Hypothesis`：未确认内容、验证方法和当前结果
   - `Decision`：日期、选择、理由和替代关系
   - `Verification`：命令、时间、PASS/FAIL 和关键摘要
   - `Risk`：影响与缓解动作
2. `Event Log`：按时间倒序保留最近 10 条事件；每条包含绝对时间、类型、事实变化和证据。新增后立即裁剪到 10 条。

事实与假设必须分离。验证后把 hypothesis 转为 confirmed fact 或记录为否定事件。只写增量与摘要，不粘贴大段日志、代码或聊天记录。

## 复杂需求工作流

当需求横跨多功能点、多接口、多端入口、多轮澄清或联调反馈时，读取
[complex-requirement-workflow.md](references/complex-requirement-workflow.md)。

复杂需求仍以 `work-item` 作为主档案，但必须额外维护：

- 事实源治理：记录 PRD/Cooper/导出文档/截图/用户澄清的优先级和覆盖关系。
- 需求矩阵：按功能点拆 `原始需求 / 澄清口径 / 接口契约 / 现有链路 / 前端改动点 / 实现回填 / 验证点 / 待确认问题`。
- 问题分层：区分产品需求问题、后端契约问题、前端实现问题和验证问题；PRD 已明确项不得继续列为待确认。
- 链路追踪：记录入口、接口、请求字段、响应字段、状态消费、参数出口和必要链路图。
- 实现前检查：确认需求闭环、契约足够、安全实施条件满足。
- 联调归因：按现象、接口响应、当前代码链路、根因、最小修复、回归点记录。
- 收尾分层：`work-item` 摘要、`evidence` 时点结论、`topic/handbook` 长期知识、`raw` 原始证据、模板复用起点。
- 版本化反哺：长期知识必须带观察版本、HEAD、来源 evidence/raw、失效信号；新需求结束时确认、修正或废弃旧结论。

复杂需求可使用 KB 模板：
`complex-requirement-matrix.md`、`integration-feedback-record.md`、`closeout-calibration.md`。

## Superpowers 路由

当前环境已安装 Superpowers 时，可按任务性质调用合适 skill，例如复杂 bug 使用 `superpowers:systematic-debugging`，实现或修复使用 `superpowers:test-driven-development`，完成声明前使用 `superpowers:verification-before-completion`。Superpowers 不是复杂需求工作流的强依赖；无对应 skill 时使用矩阵、检查清单和归因模板执行同等方法。Engineering Journal 始终只记录这些流程产生的事实、决策、验证和风险，不接管其方法或把 skill 输出自动视为已确认事实。

## 成本与安全

- 一次短会话即可完成、低不确定性且无接力价值的小任务，不主动新建档案；用户明确要求记录时使用最小模板。
- 优先更新已有档案；一个任务只选一个主档案。复杂证据仅在可复用或需要独立有效期时拆 record。
- 永不记录 token、cookie、密码、私钥、完整环境变量、带凭据 URL、内部个人数据或可复用认证材料。
- 写入前清理远端 URL、命令、日志和错误中的秘密，用 `[REDACTED]` 替代。发现疑似泄露时停止复制并提示安全处置。

## 完成检查

- 项目身份来自脚本的最新输出，并已搜索排重。
- `<KB_ROOT>` 已确定；缺失的 KB 必需模板已从 skill 内置 `templates/` 补齐，且未覆盖用户已有模板。
- 路径位于 `engineering/projects/<project-key>/...`，且未重复拼接 KB 根目录段。
- 主类型、状态转换和 evidence record 拆分符合规则。
- frontmatter 之外没有 `status` 字段；snapshot 不超过 8 项，event log 不超过 10 条。
- facts、hypotheses、decisions、verification、risks 和 quick handoff 均按当前任务实际情况维护。
- 复杂需求已维护需求矩阵、问题分层、版本化事实和收尾反哺校准；若未维护，已在风险或待验证中说明原因。
- 下一会话能直接继续，且文档无秘密、无无必要的大段原始输出。