system-dev-template

繁體中文 | English

Turn Claude Code from a "sprinting engineer" into a "disciplined engineer."

CC is an excellent engineer, but not a good project manager. It sprints to get work done — great for small projects, but on large ones it tends to:

• Fix one thing, break another: no global view, no SDD constraints
• Let docs rot: its built-in memory is unreliable, knowledge vanishes with the conversation, and it loves writing docs it never reads back — scattering them everywhere

This template solves both problems with two systems:

System	What it solves	Core mechanism
SDD system	Global view, think before doing	No code change without a design.md + tasks.md first
LLM Wiki	Memory that compounds, ordered docs	Two spaces: raw source (human-written) + .claude/wiki/ (AI-curated)

Not just code projects, not just Claude Code. LLM Wiki now also recognizes Logseq / Obsidian vaults — at install time it auto-detects which kind of folder you're in, writes the matching "raw source" into CLAUDE.md, reads only from there when curating the wiki, and never moves your vault structure (see "Not just code — Logseq / Obsidian vaults too" below). The curator isn't limited to Claude Code either — claude.ai's Cowork can use the same rules to scan and curate every wiki on your machine (see "Cowork can curate wikis too" below).

• SDD: already popular. The most thorough implementation is probably Amazon Kiro, but it's hard to pay for in Taiwan. This approach beats any flashier method — it forces CC not to do whatever it pleases.
• LLM Wiki: the latest RAG idea from the legendary Karpathy. It's a pre-compile approach — better and less fiddly than the embedding-and-chunk-into-vectors method your company bought, and far easier to run.

---

Two ways to use it

Option 1: New project

git clone https://github.com/uncle6me-web/system-dev-template
cp -r system-dev-template/template/. your-new-project/
cd your-new-project

Then in a CC conversation:

/wiki-init

Option 2: Existing project (retrofit)

cd your-existing-project
curl -sSL https://raw.githubusercontent.com/uncle6me-web/system-dev-template/main/scripts/install.sh | bash

The script only creates what's missing — it never touches files you already have.

Just one piece? The two systems install separately (sometimes you only need the wiki, not SDD):

# Download, then run with a flag
curl -sSL .../install.sh -o install.sh && bash install.sh --wiki   # LLM Wiki only
bash install.sh --sdd    # SDD only
bash install.sh --all    # both (default)

When run directly in a terminal (with a tty), running it without a flag asks interactively which piece to install — friendliest for non-engineers. With no tty, curl | bash safely defaults to --all. The hooks in settings.json are assembled automatically based on the modules you choose.

After installing, in a CC conversation:

/wiki-init

CC will scan your existing docs, build the wiki, and tidy up the docs structure.

CC loves writing docs and scattering them everywhere; the bigger and older a project gets, the messier its folders — yet it's afraid to move anything. With the folder conventions written down, it can file everything for you in one pass. LLM Wiki won't touch your original files, but it builds a separate wiki and fixes your entry point — which is CLAUDE.md. So even though things get reorganized, your documents won't disappear.

---

🔄 Already on an older version? Update with one line

Heard there are new features and want the latest? Just run this:

cd your-project
curl -sSL https://raw.githubusercontent.com/uncle6me-web/system-dev-template/main/scripts/update.sh | bash

It first compares your version with the latest, tells you which new features you'd gain, and then:

Action	Target
🆕 Add new features (hooks / commands / templates the old version lacked)	Template files
⬆️ Update template logic (hooks, commands, TEMPLATE-* swapped for new versions)	Template files
🔒 Never touch your content and settings	wiki/status.md, mistakes.md, decisions-summary.md, .wikiignore, settings.json, CLAUDE.md

Why use curl the first time? Old installs don't have update.sh locally yet, so the first run has to fetch it from the remote. After running, it installs itself to scripts/update.sh, so next time just run bash scripts/update.sh — no more curl.

Updates only touch "installed modules" (wiki installed → wiki updated; SDD installed → SDD updated), detected automatically. If settings.json is missing a hook that only the new version has, it won't change your settings for you — but it will list them at the end as a reminder to add them manually (it never edits your settings without asking).

📜 Want to know what changed each time and which version you're on? See the CHANGELOG.

---

Not just code — Logseq / Obsidian vaults too

LLM Wiki originally assumed "raw source lives in docs/", but note vaults like Logseq and Obsidian have their own directory conventions. Now install.sh auto-detects the folder type before creating CLAUDE.md, and writes the matching "raw source" into CLAUDE.md:

Detected	Type	Raw source
logseq/ folder	Logseq	pages/, journals/
.obsidian/ folder	Obsidian	all .md under the root
Neither	Regular project	docs/ (original behavior)

The declaration written into CLAUDE.md is an instruction for the AI — it tells the curator "here's where the raw source is, read only from there when curating the wiki", and for vaults it explicitly forbids moving, renaming, or re-classifying .md files; curation output always goes only into .claude/wiki/. This way, even with a note vault, the original structure stays intact and your notes never become unreadable.

Already have a CLAUDE.md? It's never overwritten (the "don't touch what exists" principle). Instead, the declaration you should add is listed at the end of the install for you to paste manually.

---

Cowork can curate wikis too

The wiki curator is no longer limited to Claude Code in the terminal — claude.ai's Cowork can do it too. docs/SKILL.md provides a skill for Cowork (wiki-cowork-scan) that shares the same rules as CC's /wiki-init and /wiki-capture:

• Scans every folder under ~/Documents that has system-dev-template installed (i.e. has a .claude/wiki/)
• Uses the same detection logic as install.sh to decide whether each folder is a regular project / Logseq / Obsidian
• Reads only the raw source and only appends to .claude/wiki/ (no overwrite, no delete); never touches raw source, CLAUDE.md, logseq/, .obsidian/, assets/

CC and Cowork share an identical output format, so whatever one curates, the other sees and skips or supplements — no duplication, no overwriting. Great for a scheduled Cowork run that keeps every wiki on your machine up to date automatically.

To use it: give docs/SKILL.md to your Cowork as a skill reference, then tell it "curate the wiki".

---

Directory guide

system-dev-template/
├── template/           ← skeleton copied into new projects
│   ├── CLAUDE.md       ← fill-in-the-blanks navigation sign
│   ├── docs/           ← docs structure (six-layer taxonomy)
│   └── .claude/
│       ├── wiki/        ← CC's memory space (incl. .wikiignore for sensitive exclusions)
│       ├── commands/    ← slash commands
│       ├── hooks/       ← hard interceptors (recall + SDD protocol + wiki secret scan)
│       └── settings.json ← wires up hooks (install.sh assembles by module)
│
├── skills/
│   └── llm-wiki/       ← copy into Legacy-Workspace/.claude/skills/
│
├── scripts/
│   ├── install.sh      ← retrofit script for existing projects
│   └── update.sh       ← one-line update for old versions (swaps templates only, never your data)
│
└── docs/               ← this repo's own documentation
    ├── why.md          ← design philosophy
    ├── wishlist.md     ← pending features and completed records
    └── SKILL.md        ← wiki-curation skill for claude.ai Cowork (wiki-cowork-scan)

---

Slash Commands

Available in any CC conversation after install:

Command	What it does
/wiki-init	Initialize the wiki (new project or retrofit)
/wiki-recall	At session start, manually resume (fallback when the hook doesn't fire)
/wiki-capture	Save this conversation's conclusions into the wiki
/wiki-update	At session end, update status.md
/sdd-check	Check whether the current task has a matching SDD
/issue-handle	Handle GitHub issues (read back from your own repo / cross-repo posting asks first / no auto-polling)

The naming loop: init (create) → update (save, end of session) ↔ recall (resume, start of session) → capture (save conclusions anytime).

---

Hooks (soft norms → hard interception)

Norms are no longer just soft reminders in CLAUDE.md; there's a backstop:

Hook	Role
session-start-recall.sh	Auto-injects the key points of status at session start — doesn't rely on CC remembering
sdd-guard.sh	Touching a code file with no SDD → block (exit 2); the automated version of /sdd-check
wiki-secret-scan.sh	A sensitive value about to be written into .claude/wiki/ → block (exit 2); a mechanical backstop for passwords/keys/PII
pre-write-guard.sh	Skeleton for project-specific bans (disabled by default; takes effect once you fill in a pattern)

---

Wiki secret protection (content you don't want indexed)

Like .gitignore, it keeps content you don't want in the wiki (passwords, keys, PII) from being indexed. Three layers:

Layer	Mechanism	What it blocks	Nature
L1	.claude/wiki/.wikiignore (glob)	An entire sensitive file is not indexed	Protocol (CC complies)
L2	Inline markers <!-- wiki:ignore -->…<!-- wiki:end -->	A section within a file is not indexed	Protocol (CC complies)
L3	wiki-secret-scan.sh hook	A sensitive value actually being written into the wiki → exit 2 blocks it	Hard interception (mechanical detection)

L1/L2 are markers you set proactively; L3 is the automatic backstop — if CC misses the first two, the moment a secret is written into the wiki it's caught by regex (password assignments, PEM private keys, AWS/GitHub/Slack keys, JWTs, connection-string credentials, national IDs, credit-card numbers).

Honest limits: L1/L2 rely on CC's self-discipline; L3 relies on pattern matching (with false positives/negatives). This is a mechanism to reduce accidental leaks, not a vault — real secrets shouldn't be in version control in the first place. On a false positive: add wiki-secret-ok at the end of the line to allow it; for a whole sensitive file, add it to .wikiignore.

Honest limits: the hook blocks syntactically obvious violations (writing directly to a file); it can't catch detours hidden in helpers / bash. Its value is "trying to skip it gets caught + leaves an auditable trace", not technical tamper-proofing — the docs (mindset) and the hook (backstop) are both indispensable.

---

Design principles

• Additive, not destructive: when retrofitting an existing project, your existing norms stay; the wiki system layers on top
• Structure is protocol: CC and you share the same taxonomy, no need to re-explain every time
• CLAUDE.md doesn't grow: past 100 lines is an architecture problem, not a reason to add more content
• Capture conclusions on the spot: after a discussion, use /wiki-capture so knowledge stops vanishing

---

Acknowledgments

This template stands on the shoulders of giants:

• Andrej Karpathy — originator of the LLM Wiki concept. This template's two-space memory system comes directly from his April 2026 idea: using an LLM to "pre-compile" knowledge into interlinked markdown, rather than re-running embedding retrieval on every query. One line of his captures the spirit: "Obsidian is the IDE, the LLM is the programmer, the wiki is the codebase."

  • Further reading: The Andrej Karpathy LLM Wiki Idea, Beyond RAG (Level Up Coding)

• Amazon Kiro — this template's SDD (Spec-Driven Development) approach is learned from Kiro. It takes "have a structured spec before you start" to the furthest extreme; paying for it is inconvenient in Taiwan, but its methodology deserves respect and borrowing.

• Claude (Claude Code / Anthropic) — this template's hooks, secret protection, modular install, and this very README were all pair-developed with Claude. The template itself exists to turn Claude Code "from a sprinting engineer into a disciplined engineer" — it's both the tool and a co-author.