agentleFS
DeL-TaiseiOzakiDeL-TaiseiOzaki/claude-code-orchestra/.claude/skills/design-tracker/SKILL.md

design-tracker

Skill199 starsChanged 2 months agoMITView on GitHub

Record a project design decision into .claude/docs/DESIGN.md through the shared typed writer. Use when the user says "record this", "add to design", "document this", "記録して", or asks what has been decided so far — and when a design decision has just been made and should not be lost.

2 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 5 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read this before relying on it: nothing in the repository activates this skill automatically.

    line 21
  2. Distinctive:

    Write a per-invocation input JSON and run the shared writer (see Mechanical Update).

    line 56
  3. Distinctive:

    Use a per-invocation input path, never a shared one: this skill can run concurrently with other work (and inside a subagent), and two …

    line 87
  4. Distinctive:

    Run dry-run, read the preview, then apply:

    line 118
  5. Very specific:

    Always report skipped_duplicates when it is non-zero — that is the honest "already recorded" answer.

    line 134
  6. Distinctive:

    When recording, report concisely:

    line 147

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Design Tracker Skill

Purpose

This skill keeps the project's 要件定義書 (.claude/docs/DESIGN.md) current. DESIGN.md is the macro requirements & design document (what the project builds and why); micro work progress lives in PROGRESS.md. It covers:

  • Background & purpose, scope
  • Functional & non-functional requirements
  • Architecture (including agent roles)
  • Tech stack choices and their rationale
  • Constraints, key decisions, and open questions

How This Skill Is Reached

Read this before relying on it: nothing in the repository activates this skill automatically. The description above is the entire trigger surface, and it works only through the runtime's own description-based skill selection.

  • Explicit request — "record this", "add to design", "update DESIGN", "記録して", /design-tracker. This is the reliable path.
  • Model invocation from the description, at the runtime's discretion. Claude Code discovers the skill through .claude/skills → .claude/skills; Codex through .codex/config.toml's path = ".claude/skills/design-tracker".
  • No hook mechanism. .claude/hooks/ contains no design-tracker branch, and the words a design conversation actually uses (設計 / design / architecture) are claimed by CODEX_TRIGGERS in agent-router.py, which injects a Codex consultation nudge instead. check-codex-before-write.py also nudges when DESIGN.md is edited, but it blocks nothing — a freehand edit still lands.

So an agent in a design conversation must decide to record the decision; no automation will decide for it. If a decision was made and this skill was not reached, record it at the next checkpoint — /checkpointing describes recording decisions via update_design.py for exactly that reason.

Previous versions of this file promised proactive, automatic activation ("Do NOT wait for user to ask"). That promise was enforced by nothing, so it has been removed rather than left as a false statement in a normative document.

Workflow

Recording Decisions

  1. Decide whether this is a design decision, and whether it is already recorded. Grep the target table (e.g. grep -n "^| " .claude/docs/DESIGN.md) instead of reading the whole document — the writer locates the table and heading itself.
  2. Extract the decision from the conversation.
  3. Map it to a section and to that section's typed input key (table below).
  4. Write a per-invocation input JSON and run the shared writer (see Mechanical Update).

Sections to Update

DESIGN.md uses these fixed sections (Japanese + English headings). Every target has a typed input key, so no markdown row is ever hand-written:

Conversation TopicTarget SectionInput keyFields
Project goals, problem, stakeholders## 背景・目的 (Background & Purpose)section_updatesheading, content (prose)
What is / isn't covered## スコープ (Scope) — In / Out of Scopesection_updatesheading, content (bullets)
A feature the system must provide## 機能要件 (Functional Requirements)requirementsid, requirement, priority, notes
Performance, security, availability, maintainability targets## 非機能要件 (Non-Functional Requirements)nfrcategory, requirement, metric
System structure, components, agent roles## アーキテクチャ (Architecture) — overview + Agent Roles tablesection_updates for the overview prose, agent_roles for the tableagent, role, responsibilities
Library / framework / infra choice + why## 技術選定 (Tech Stack & Rationale)tech_choicesarea, technology, rationale, alternatives
Hard limits (technical, org, compatibility)## 制約 (Constraints) bulletssection_updatesheading, content (bullets)
Why we chose X over Y (significant)## Key Decisionsdecisionsdecision, rationale, alternatives (the date is stamped by the writer)
Things to do later, unresolved questions## TODO / Open Questionssection_updatesheading, content (checklist)

The four prose sections have no typed key because they have no fixed shape — their content is a sentence or a bullet an agent writes, and there is no correct rendering for a script to own. Every section that does have a fixed shape (a table) has a typed key, and the writer refuses table rows passed through section_updates: it exits 2 naming the key you should have used, so the unescaped-cell and orphaned-row corruptions are now unreachable from this skill.

Choosing the section stays judgment. Rendering the row does not.

Mechanical Update

Use a per-invocation input path, never a shared one: this skill can run concurrently with other work (and inside a subagent), and two recordings sharing one input file overwrite each other. Resolve the path from the shared workspace registry rather than deriving it by hand, so the slug rule is the same one every other skill uses:

python3 .claude/skills/_shared/workspace.py \
  --skill design-tracker --title "{decision topic}" --create

That prints one JSON object whose paths.design_input is .claude/logs/design-input-{slug}.json. Use it verbatim as ${input} below. Exit 0 resolved/created · 1 bad args · 3 .claude/logs/ could not be created.

Example input (use only the keys you need):

{
  "decisions": [
    {"decision": "Use ReAct pattern", "rationale": "Better tool-use control", "alternatives": "Function calling only"}
  ],
  "tech_choices": [
    {"area": "Agent loop", "technology": "ReAct", "rationale": "Tool-use control", "alternatives": "Function calling only"}
  ],
  "section_updates": [
    {"heading": "## TODO / Open Questions", "content": "- [ ] Evaluate streaming support"}
  ]
}

Run dry-run, read the preview, then apply:

python3 .claude/skills/_shared/update_design.py --input "${input}"
# Read the file named by preview_file in the JSON output, then:
python3 .claude/skills/_shared/update_design.py --input "${input}" --apply --require-change

Completion test. "ok": true alone is not it — a duplicate or empty entry used to return ok: true with result: "no-op" and exit 0 while nothing was written. Require all of:

  • result == "applied", and
  • decisions_appended > 0 or some rows_appended value > 0 or sections_updated non-empty.

Always report skipped_duplicates when it is non-zero — that is the honest "already recorded" answer. --require-change makes the writer enforce the same thing: a no-op becomes ok: false and exit 2, so "recorded" can never be reported for a run that wrote nothing.

Other exit codes: 1 bad arguments or input-schema violation · 2 DESIGN.md structure invalid or missing (run /init first), a duplicate requirement ID, a table row passed through section_updates, or a no-op under --require-change · 3 DESIGN.md changed while the writer held it, or the write failed — re-read and retry.

Output Format

When recording, report concisely:

  • What was recorded, and into which DESIGN.md section
  • The writer's result, the appended counts, and skipped_duplicates
  • Anything you decided not to record, and why

Language Rules

  • Reasoning / code examples: English
  • Document content: English (technical terms); Japanese descriptions are acceptable to match the existing 要件定義書 headings
  • Report to the user: per .claude/rules/language.md

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.