mcpField
D
doc-append-log

doc-append-log

github.com/shyxinDocuments552 installsUpdated today
Repository

About doc-append-log

doc-append-log is a documentation history workflow for project teams and agents. It uses an indexed, append-only record and helper scripts to preserve past notes while tracking which documents are current or superseded.

Key features

  1. 01Append-only historical documents
  2. 02Date-prefixed filenames
  3. 03Status index in INDEX.md
  4. 04Scripts to locate directories and initialize indexes
  5. 05Protection against overwriting existing files

Use cases

  1. 01Recording design decisions and change logs
  2. 02Superseding documentation while retaining its history
  3. 03Helping agents follow project changes across sessions

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/shyxin/skills --skill doc-append-log

After installing, type/doc-append-login Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

references/
convention.md
scripts/
append_entry.sh
init_index.sh
locate_docs.sh

Details

From the project README

文档/日志追加历史机制（doc-append-log）

把项目的文档与日志沉淀成只追加、不改写的历史，让任何智能体（CodeBuddy / Claude Code / Codex）读 INDEX.md 就能拼出全貌，且原始记录永不被覆盖。

何时使用

  • 项目里要新增一份设计记录、决策纪要、改造日志、复盘、变更说明。
  • 已有文档需要被"取代"但不想改写原文件，只想加新文件并在索引里标注状态。
  • 智能体需要在多次会话间保持对项目演进的连续理解。

核心约定（只追加，不改写）

  1. 每篇历史/结论文档创建后不再修改其内容，保留原貌作为历史。
  2. 新增内容时新建一个 YYYY-MM-DD_主题.md 文件，并在 INDEX.md 末尾追加一行索引项；不回改旧文档。
  3. 智能体阅读顺序：先读 INDEX.md → 按"状态"定位需关注的文档 → 按需精读对应 md。
  4. 状态含义：
    • 当前事实：最新且生效
    • 当前参考：仍有效，但属于某专题沉淀
    • 历史背景：已被取代，仅作溯源

文件名用日期前缀（2026-08-14_改造全过程日志.md）是为了让目录天然按时间有序；即使不重命名旧文件，也能靠 INDEX.md 里记录的日期掌握先后。

用法（脚本辅助，保证结构统一）

脚本位于 scripts/，目录无关：不硬编码 docs/，而是先定位文档目录（用 locate_docs.sh），也接受显式路径参数。不破坏任何已有文件。

# 0) 定位文档目录（优先已有 INDEX.md 的目录；否则 docs/log/logs/ 等常见候选；否则回退 docs）
bash scripts/locate_docs.sh            # 打印要用的目录
bash scripts/locate_docs.sh log        # 也可显式指定，如同事放在 log/

# 1) 初始化索引（已存在则跳过，绝不覆盖）
bash scripts/init_index.sh             # 用定位到的目录
bash scripts/init_index.sh log         # 或显式指定

# 2) 追加一篇新文档 + 自动在索引末插入一行
bash scripts/append_entry.sh "" "改造全过程日志" 当前事实 "从三版演进到新版改造的完整记录"
bash scripts/append_entry.sh log "故障排查复盘" 当前参考 "某次线上故障的排查与结论"
  • locate_docs.sh [目录]：返回文档目录——传了路径就用路径；否则优先返回已有 INDEX.md 的目录，再退而求其次返回第一个存在的常见候选（docs/doc/document/documentation/log/logs/logs/docs/wiki），都没有则回退 docs。
  • init_index.sh [目录]：在目录下生成 INDEX.md（含约定说明、时间线表格、追加哨兵）。若已存在则提示跳过。
  • append_entry.sh [目录] <主题> [状态] [摘要]：创建 YYYY-MM-DD_<主题>.md（同名已存在则跳过创建，不覆盖），并在 INDEX.md 的哨兵前插入索引行（已存在则跳过追加）。

阅读入口

智能体介入任意项目时，先用 locate_docs.sh 定位文档目录（或采用用户指定的路径，可能叫 docs/、log/、logs/，也可能是你中途加入的某个项目的 docs/），再阅读其中的 INDEX.md；若不存在且用户希望沉淀历史，可调用 init_index.sh 建索引，之后每次变更用 append_entry.sh 追加。

设计取舍

  • 为什么不改写原 md：智能体在后续会话读取时，能拿到当时真实写下的结论，避免被后来的"修订"误导；溯源也靠原文。
  • 为什么用 INDEX.md 而非纯靠文件名排序：纯文件名排序无法表达"哪篇是当前事实、哪篇已被取代"；索引用状态标记解决这一点，且是智能体的单一入口。
  • 为什么脚本也要轻量：约定若只写在文档里，容易被多次会话写歪；两个小脚本把"建索引 / 追加一行"固化成命令，结构才稳定。

Comments

Markdown supported