tl-devlog（tl 开发日志）

tl-devlog

Maintain a living development log (DEVLOG.md) in project repositories. Captures decisions, progress, incidents, and insights so future sessions have full context on what was done and why.

Quick Start

Just say "log this" or "devlog" after any significant decision or milestone.

Example interaction:

You: "We decided to use PostgreSQL instead of MongoDB for the audit system"
Agent: "This feels worth capturing — we decided PostgreSQL for transactional
       integrity over MongoDB's flexibility. Want me to log it?"
You: "Yes, log it"
Agent: [Drafts entry, shows for approval, commits to DEVLOG.md]

When to Use

Explicit triggers (user-initiated):

• "Log this", "devlog", "archive this"
• "Add to the devlog", "record this decision"
• "This should go in the changelog"

Proactive suggestions (agent-initiated, at natural pause points):

• A technical architecture decision was made
• A significant piece of work was completed
• A production incident was resolved
• An important insight emerged
• A strategic direction was established

Frame suggestions naturally: "This feels worth capturing — we decided X because of Y. Want me to log it?"

Do NOT log:

• Routine Q&A or simple lookups
• Work still in progress with no decision point
• Minor clarifications that don't change direction

Outcomes

• Artifact: Entry added to DEVLOG.md in project root
• Patch: Git commit with devlog: prefix pushed to origin

Safety Constraints

• Do NOT store secrets, API keys, tokens, or credentials in devlog entries
• If sensitive information is mentioned, redact it before logging
• Always show the user the draft entry before committing
• Never auto-push without user confirmation

Categories

Choose the category that best fits each entry:

Entry Format

## [YYYY-MM-DD] Brief descriptive title

**Category:** `architecture` | `milestone` | `incident` | `bug` | `ops` | `design` | `strategy` | `takeaway`
**Tags:** `relevant`, `topic`, `tags`

### Summary
1-2 sentence overview of what happened or was decided.

### Detail
- What was decided or accomplished
- Why this approach was chosen
- What alternatives were considered (and why rejected)
- Dependencies or implications for future work

### Related
- Links to related entries, PRs, issues, or docs

Instructions

Step 1: Identify the Project

On first use in a session, establish context:

1. Check if the current working directory is a git repo
2. If yes, use the repo root for DEVLOG.md
3. If ambiguous, ask: "Which project should I log this to?"

Step 2: Identify Category and Content

From the conversation or user request, determine:

• Category: Which of the 8 categories fits best
• Title: Brief descriptive phrase
• Content: What happened, why, what alternatives were considered

Step 3: Draft the Entry

Write the entry following the format above. Include:

• Specific details (file names, version numbers, concrete outcomes)
• The "why" — rationale is the most valuable part
• Past tense for decisions and completed work

Step 4: Show User for Approval

Present the drafted entry and ask:

• "Does this capture it accurately?"
• "Any edits before I commit?"

Never commit without user confirmation.

Step 5: Update DEVLOG.md

Determine the file path:

• Use {repo_root}/DEVLOG.md
• If the file doesn't exist, create it with this header:

# [Project Name] — Development Log

A living record of architectural decisions, milestones, incidents, and insights.
Entries are reverse-chronological (newest first).

---

Insert the new entry immediately below the header separator (---). Entries are always newest-first.

Step 6: Commit and Push

After user approval:

git add DEVLOG.md
git commit -m "devlog: [brief title from entry]"
git push origin HEAD

Step 7: Confirm

Report back:

✅ Logged: [Category] - [Title]
📂 DEVLOG.md updated
🔗 Pushed to origin

Update Modes

When updating an existing date's entry:

APPEND (default): Add new bullets to existing sections without modifying prior content.

CHANGE: User describes specific edits. Apply minimal changes faithful to the request.

Reading the Devlog

When the user asks about past decisions, progress, or project history:

1. Read DEVLOG.md from the repo
2. Search entries by category, tags, date, or keywords
3. Summarize relevant entries in the conversation

This makes the devlog bidirectional — for writing and recalling context.

Multiple Entries Per Session

If a conversation covers several loggable topics:

• Draft all entries at once
• Present them together for review
• Commit in a single push: devlog: session updates - [topic1], [topic2]

Storage Modes

Default to project mode. Switch to local/global only if user explicitly requests.

Error Handling

Style Guidelines

• Past tense for decisions and completed work ("Chose X over Y")
• Present tense for ongoing context ("The system supports N")
• Be specific — include versions, filenames, concrete details
• Include the "why" for every "what"
• Tags: lowercase, hyphenated, searchable (rate-limiting, auth-flow)
• Reference related devlog entries by date when relevant

What Good Looks Like

❌ BAD: "Fixed the database issue"

✅ GOOD: "Resolved 45-minute API outage caused by connection pool exhaustion.
   Root cause: analytics cron job ran 3-hour query without statement timeout.
   Fix: Killed query, added 5-minute timeout, separated analytics pool."

Skill Resources

Load the examples reference when you need inspiration for a specific category.

ADR Integration

Some architecture entries deserve promotion to formal Architecture Decision Records.

When to Promote to ADR

MADR 4.0 Template

When promoting to ADR, use this format in docs/decisions/NNNN-decision-title.md:

---
status: accepted
date: 2026-03-18
decision-makers: [team members]
consulted: [stakeholders]
informed: [affected parties]
---

# ADR-NNNN: [Decision Title]

## Context and Problem Statement

[1-2 sentences describing the situation and the decision to be made]

## Decision Drivers

* [Concern 1]
* [Concern 2]

## Considered Options

1. [Option A]
2. [Option B]
3. [Option C]

## Decision Outcome

Chosen option: "[Option X]" because [justification].

### Consequences

* Good, because [positive outcome]
* Bad, because [negative outcome]
* Neutral, because [side effect]

## Links

* [Link to devlog entry]
* [Link to related ADRs]

Bidirectional Linking

When promoting a devlog entry to ADR:

1. Create the ADR file
2. Update the devlog entry with a link:

### Related
- **ADR**: [ADR-0015: PostgreSQL for Audit System](docs/decisions/0015-postgresql-for-audit.md)

CHANGELOG Bridging

Extract milestone entries to generate CHANGELOG releases.

Workflow

1. Query milestones since last release: grep -A 20 "Category.*milestone" DEVLOG.md | head -50
2. Map to CHANGELOG categories: Devlog Tag CHANGELOG Section new-feature Added enhancement Changed deprecation Deprecated removal Removed fix, bug Fixed security Security
3. Generate entry: ## [1.2.0] - 2026-03-18 ### Added - API endpoint for bulk imports (#123) ### Changed - Improved rate limiting algorithm ### Fixed - Memory leak in worker process (incident 2026-03-15)

Keep a Changelog Format

Follow keepachangelog.com:

• Newest entries at top
• Group by version, then by type
• Use ISO dates (YYYY-MM-DD)
• Link versions to git tags

Search Patterns

Find entries by category

grep -B 2 "Category.*architecture" DEVLOG.md

Find entries by tag

grep -B 5 "Tags:.*auth-flow" DEVLOG.md

Find entries by date range

awk '/## \[2026-03-/{flag=1} flag; /## \[2026-02-/{flag=0}' DEVLOG.md

Full-text search

grep -B 10 -A 10 "PostgreSQL" DEVLOG.md

References

Quilted Skills

• d6veteran/devlog-skill — Entry format, categories
• maoruibin/devlog — Extended categories
• josephmiclaus/skill-devlog — Safety constraints
• skillrecordings/adr-skill — ADR integration

First-Party Documentation

• Keep a Changelog — CHANGELOG format standard
• MADR — Markdown Architectural Decision Records
• Conventional Commits — Commit message convention

Industry Perspectives

• Engineering Daybook (Fowler) — Philosophy
• Documenting Architecture Decisions (Nygard) — Original ADR proposal