convez.ai
SkillDevOps & InfraestruturaIntermediário
Aodusk-Future

OpenLog Skill

Aodusk-Future/openlog-skill

Diário de dev por módulo — arquitetura, log e breakpoint em <1k tokens

Ver no GitHub
InicialPluginScore · de 0 a 100

Uma skill para Claude Code e Codex CLI que cria um diário de desenvolvimento por módulo, registrando arquitetura, log de mudanças e ponto de interrupção atual. Permite que agentes e sessões futuras retomem o trabalho em menos de 1k tokens, eliminando reexploração de código e derivas arquiteturais.

Instalação

$npx convez-ai Aodusk-Future/openlog-skill

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Retomar trabalho em projetos grandes sem reexploração de contexto
  • Manter histórico arquitetural e decisões de design centralizadas
  • Facilitar handoff entre sessões de IA ou entre múltiplos agentes
  • Reduzir tokens gastos em re-leitura de código e derivação de estado

Veredito

OpenLog resolve um problema real em fluxos de trabalho com IA: handoff eficiente entre sessões e agentes em projetos complexos. Implementação clara e bem documentada, embora exija disciplina do usuário em manter os registros atualizados.

README

A tradução para o português deste README ainda está na fila.

OpenLog

A lightweight per-module development journal for Claude Code and Codex CLI — keep architecture, dev log, and current-stage notes for every module of a large project, so any future session or agent can pick up the work in under 1k tokens.

一个轻量级的"按模块开发档案"工具,同时支持 Claude Code 和 Codex CLI——为大型项目的每个模块沉淀架构说明、开发日志、当前断点,让未来任何会话 / agent 都能在 1k token 以内接手工作。

中文版说明 ↓


Why OpenLog?

When a project grows past a handful of modules, three things start to hurt:

  1. High handoff cost — a new session (or a new agent) has to re-derive "where did we stop?" and "why is it built this way?"
  2. Design / implementation drift — architectural decisions live in chat history and slowly disappear.
  3. Wasted tokens on re-exploration — every fresh context has to grep / read the same files to rebuild understanding.

OpenLog fixes this by writing the three pieces of context that matter — architecture, dev log, current breakpoint — into three fixed files per module, then standardising how Claude reads and updates them.

Quick Start

Works with both Claude Code and Codex CLI — they use the same SKILL.md format.

# For Claude Code
git clone https://github.com/Aodusk-Future/openlog-skill ~/.claude/skills/openlog

# For Codex CLI (identical workflow, same trigger commands)
git clone https://github.com/Aodusk-Future/openlog-skill ~/.codex/skills/openlog

Using both tools? Clone once to ~/openlog-skill/, then symlink to both locations so future updates stay in sync automatically:

git clone https://github.com/Aodusk-Future/openlog-skill ~/openlog-skill
mkdir -p ~/.claude/skills/openlog ~/.codex/skills/openlog
ln -s ~/openlog-skill/SKILL.md ~/.claude/skills/openlog/SKILL.md
ln -s ~/openlog-skill/SKILL.md ~/.codex/skills/openlog/SKILL.md

Then in any Claude Code or Codex session, type:

/openlog

…or just say something like "let's work on the Combat module" / "start the Combat module" — the agent will recognise the trigger and run the OpenLog workflow.

How It Works

Data layout (lives in your project root)

OpenLog/
├── INDEX.md                          # Minimal table of all modules + one-liner + status
├── <ModuleA>/
│   ├── ARCHITECTURE.md               # Module architecture — kept up to date
│   ├── DEV_LOG.md                    # Dev log, newest entries on top
│   ├── DEV_LOG.archive/              # Auto-archive when DEV_LOG > 500 lines
│   │   └── YYYY-MM.md
│   └── CURRENT.md                    # Current breakpoint, <30 lines
└── <ModuleB>/...

The OpenLog/ directory is committed to your project's git, so multiple worktrees / multiple agents / multiple humans share the same journal.

Two-phase workflow

Startup phase (when you invoke the skill):

  1. Read OpenLog/INDEX.md (the only full read).
  2. Try to fuzzy-match the module name from what you just said.
  3. If matched → read ARCHITECTURE (full), DEV_LOG (first ~40 lines = newest ~5 entries), CURRENT (full). Output a 2-3 sentence handoff summary.
  4. If not matched → ask which module, or create a new one.

Wrap-up phase (only triggered by explicit user signal — "done", "wrap it up", "next task", /openlog commit, etc.):

  1. Prepend a new entry to DEV_LOG (timestamp + summary + key files + link to CURRENT items).
  2. Update CURRENT (move "in progress" items, log new blockers, refresh timestamp).
  3. Update ARCHITECTURE only if interfaces / dependencies / key files changed.
  4. Auto-archive old DEV_LOG entries when the file exceeds 500 lines.

Designed for low token cost

  • Resuming a module: typically 700-1000 tokens of reads, no grep, no whole-codebase exploration.
  • Creating a module: ~300 tokens.
  • Wrap-up: ~150-400 tokens (ARCHITECTURE updates are skipped most of the time).

Customisation

The skill is a single markdown file at SKILL.md. Edit the rules, file templates, or wrap-up triggers to match your team's conventions.

A reference English-language version of the skill body is provided at SKILL.en.md. To use it, replace the YAML body of SKILL.md with the English content, or rename it directly.

License

MIT — do whatever you want with it; attribution appreciated but not required.


中文

为什么需要 OpenLog?

当项目模块数超过几个,就会遇到三个痛点:

  1. 接手成本高——新会话或新 agent 要重新摸清"上次做到哪""为什么这么设计"
  2. 设计与实现分裂——架构决策散落在对话里,没有沉淀
  3. 重复探索浪费 token——每次新上下文都要 grep / read 同一批文件重建理解

OpenLog 把"架构说明 + 开发日志 + 当前断点"沉淀到每个模块固定的三个文件里,并标准化 Claude 读写它们的方式。

快速上手

同时支持 Claude Code 和 Codex CLI——两者用相同的 SKILL.md 格式。

# Claude Code
git clone https://github.com/Aodusk-Future/openlog-skill ~/.claude/skills/openlog

# Codex CLI(工作流完全一致,触发命令也相同)
git clone https://github.com/Aodusk-Future/openlog-skill ~/.codex/skills/openlog

两个工具都用?建议 clone 一份到 ~/openlog-skill/,然后用 symlink 链到两个位置,以后更新只需 git pull 一次:

git clone https://github.com/Aodusk-Future/openlog-skill ~/openlog-skill
mkdir -p ~/.claude/skills/openlog ~/.codex/skills/openlog
ln -s ~/openlog-skill/SKILL.md ~/.claude/skills/openlog/SKILL.md
ln -s ~/openlog-skill/SKILL.md ~/.codex/skills/openlog/SKILL.md

之后在任何 Claude Code 或 Codex 会话里输入:

/openlog

…或者直接说"开始开发 Combat 模块" / "接手战斗模块"等,agent 会识别触发条件并走 OpenLog 工作流。

工作原理

数据布局(位于项目根目录)

OpenLog/
├── INDEX.md                          # 模块清单(极简表格 + 一句话定位 + 状态)
├── <模块A>/
│   ├── ARCHITECTURE.md               # 模块架构(保持最新)
│   ├── DEV_LOG.md                    # 开发日志(倒序,最新在最上)
│   ├── DEV_LOG.archive/              # DEV_LOG > 500 行时自动归档
│   │   └── YYYY-MM.md
│   └── CURRENT.md                    # 当前断点(< 30 行)
└── <模块B>/...

OpenLog/ 目录跟随项目 git 仓库提交,团队 / 多 worktree / 多 agent 共享同一份档案。

两阶段工作流

启动阶段(唤起 skill 时):

  1. Read OpenLog/INDEX.md(唯一允许的全量读)
  2. 尝试从你的指令里模糊匹配模块名
  3. 匹配到 → 读 ARCHITECTURE(全文)+ DEV_LOG(前 40 行 ≈ 最近 5 条)+ CURRENT(全文),输出 2-3 句话接手摘要
  4. 未匹配 → 询问要开发哪个模块,或新建

收尾阶段(仅在用户明确发信号时触发——"做完了""收尾""下一个任务""/openlog 收尾"等):

  1. 在 DEV_LOG 顶部插一条新记录(时间戳 + 摘要 + 关键文件 + 关联 CURRENT 条目)
  2. 更新 CURRENT("进行中"移走 / 标记新阻塞 / 刷新时间戳)
  3. 仅当接口 / 依赖 / 关键文件变化时才改 ARCHITECTURE
  4. DEV_LOG > 500 行时自动归档老条目

为低 token 设计

  • 接手已有模块:~700-1000 tokens,无需 grep,无需全代码库探索
  • 新建模块:~300 tokens
  • 收尾:~150-400 tokens(多数情况下跳过 ARCHITECTURE 更新)

自定义

整个 skill 就是一个 markdown 文件 SKILL.md,规则、模板、触发口令都可以按团队习惯改。

如需英文版 skill body,参考 SKILL.en.md。把 SKILL.md 的正文替换为英文内容,或者直接改名使用即可。

许可证

MIT——随便用,署名鼓励但不强制。

Ver o original no GitHub

Bom para

Relacionados