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
- ilhae-ai/claude-code-orchestratortheir own version, first seen Oct 20, 2026
- gaebalai/claude-code-orchestratortheir own version, first seen Jan 31, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- gaebalai/claude-code-orchestrator★ 18same name
- ilhae-ai/claude-code-orchestrator★ 18same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository17 other files it gives its agents.
- .agents/AGENTS.mdAGENTS.md
- AGENTS.mdAGENTS.md
- .codex/AGENTS.mdAGENTS.md
- catchupSkill
- checkpointingSkill
- codex-systemSkill
- context-loaderSkill
- featureSkill
- initSkill
- planSkill
- research-libSkill
- simplifySkill
- spikeSkill
- tddSkill
- team-executeSkill
- troubleshootSkill
- update-lib-docsSkill
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
- Distinctive: line 21
Read this before relying on it: nothing in the repository activates this skill automatically.
- Distinctive: line 56
Write a per-invocation input JSON and run the shared writer (see Mechanical Update).
- Distinctive: line 87
Use a per-invocation input path, never a shared one: this skill can run concurrently with other work (and inside a subagent), and two …
- Distinctive: line 118
Run dry-run, read the preview, then apply:
- Very specific: line 134
Always report skipped_duplicates when it is non-zero — that is the honest "already recorded" answer.
- Distinctive: line 147
When recording, report concisely:
≈ “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.
Files
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'spath = ".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 byCODEX_TRIGGERSinagent-router.py, which injects a Codex consultation nudge instead.check-codex-before-write.pyalso nudges whenDESIGN.mdis 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
- 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. - Extract the decision from the conversation.
- Map it to a section and to that section's typed input key (table below).
- 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 Topic | Target Section | Input key | Fields |
| Project goals, problem, stakeholders | ## 背景・目的 (Background & Purpose) | section_updates | heading, content (prose) |
| What is / isn't covered | ## スコープ (Scope) — In / Out of Scope | section_updates | heading, content (bullets) |
| A feature the system must provide | ## 機能要件 (Functional Requirements) | requirements | id, requirement, priority, notes |
| Performance, security, availability, maintainability targets | ## 非機能要件 (Non-Functional Requirements) | nfr | category, requirement, metric |
| System structure, components, agent roles | ## アーキテクチャ (Architecture) — overview + Agent Roles table | section_updates for the overview prose, agent_roles for the table | agent, role, responsibilities |
| Library / framework / infra choice + why | ## 技術選定 (Tech Stack & Rationale) | tech_choices | area, technology, rationale, alternatives |
| Hard limits (technical, org, compatibility) | ## 制約 (Constraints) bullets | section_updates | heading, content (bullets) |
| Why we chose X over Y (significant) | ## Key Decisions | decisions | decision, rationale, alternatives (the date is stamped by the writer) |
| Things to do later, unresolved questions | ## TODO / Open Questions | section_updates | heading, 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}" --createThat 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-changeCompletion 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", anddecisions_appended > 0or somerows_appendedvalue> 0orsections_updatednon-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, andskipped_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
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
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.

