Topics: claude-code · claude-code-skills · agent-skills · ai-agents · project-scaffolding · software-architecture · documentation · vibe-coding
Jump to: What it generates · Install · Usage · How it works · Evaluation · License · 中文说明
A universal, tech-stack-agnostic Claude Code skill that lays down a project's agent-governance rules, documentation, and architecture before the first line of code — and keeps them the source of truth as the project grows.
The governing idea, learned the hard way from AI-assisted "vibe coding":
- Version control from day 0 — initialize the repo before writing any code.
- Documentation before code — requirements, architecture, roadmap, conventions are decided up front, not back-filled.
- Architecture > UI > polish — a project where any bug can instantly be pinned to one module outlives a pretty but tangled one by an order of magnitude.
ADS turns those lessons into an executable workflow. Run it in any repo and it scaffolds a complete governance system, then interviews you to fill it with real, project-specific content.
你应当第一步先单独与 agent沟通 PRD，之后在 Skills 问你你的项目是关于什么的时候，直接把 PRD 提供进去，跳过引导你完成 PRD。UIUX 同理，你也可以自己准备，同样可以跟随引导。 You should first communicate the PRD with the agent individually. Then, when the Skills ask you what your project is about, directly provide the PRD and skip the guidance on completing the PRD. The same applies to UIUX; you can also prepare it yourself and follow the guidance accordingly.
.project.agents/
├── CLAUDE.md # project-level agent guide (what/how/rules)
├── AGENTS.md # cross-vendor contributor guide (Codex etc.)
├── SELF_CONSTRAINTS.md # hard constraints — checked before every task
├── VIBECODING_GUIDE.md # the practice guide (the "why")
├── settings.json # agent hooks/permissions (contained here)
├── docs/context/
│ ├── PRD.md # product requirements (source of truth for behavior)
│ ├── ARCHITECTURE.md # module cards + dependency DAG + interface contracts
│ ├── ROADMAP.md # milestones with acceptance checks
│ ├── CONVENTIONS.md # naming / style / commits / testing
│ └── UIUX.md # visual tokens + interaction (UI projects only)
└── log/ # execution logs
Plus git init and a zero-point skeleton commit.
- Greenfield — a fresh/empty project: scaffold everything, then a guided requirements→architecture interview fills the docs.
- Retrofit — an existing codebase with no governance: it reads the code (CodeGraph-aware), reverse-engineers a draft
ARCHITECTURE.mdfor you to correct, and flags drift (god-modules, layer violations, dead code) — without touching your source.
/agent-development-specification (the skill's init) runs four phases:
- Detect state — greenfield vs. existing code vs. already-scaffolded.
- Mechanical scaffold —
scripts/scaffold.pybuilds the tree and writes the governance files. It is idempotent and non-destructive: it never overwrites a file you've tuned, and re-running only fills what's missing. - Guided interview — the spec's Step 1–7 flow (requirements → domain model → module cards → dependency DAG → roadmap → conventions), filling each doc with real content.
- Completion gate — before committing, it greps for any unfilled
{{token}}/ marker and resolves every one, so no half-written doc ships.
The skill is a folder named agent-development-specification/ placed in a Claude Code skills directory.
Option A — from the prebuilt bundle (dist/agent-development-specification.skill, a zip):
# all projects (personal):
unzip dist/agent-development-specification.skill -d ~/.claude/skills/
# or one project:
unzip dist/agent-development-specification.skill -d /path/to/project/.claude/skills/Option B — clone this repo into the skills dir:
git clone https://github.com/SmartSunruiyang/agent-development-specification \
~/.claude/skills/agent-development-specificationThen start a new Claude Code session (skills are discovered at session start).
/agent-development-specification
…or just ask in natural language — "set up the agent governance / project spec for this project", "建立这个项目的起步指南与 Agent 规范" — and it triggers.
- Claude Code (the skill runtime).
- Python 3 —
scripts/scaffold.pyneeds it (python3 --version). - No other dependencies.
.
├── SKILL.md # the orchestrator (frontmatter + workflow)
├── references/
│ ├── spec.md # the canonical, tech-agnostic spec (the "why")
│ ├── interview-flow.md # the Step 1–7 interview script
│ └── retrofit.md # reverse-engineering architecture from code
├── assets/templates/ # the files written into the target repo
│ └── docs/ # PRD / ARCHITECTURE / ROADMAP / CONVENTIONS / UIUX skeletons
├── scripts/scaffold.py # idempotent, non-destructive scaffolder
├── evals/evals.json # test cases
└── dist/ # prebuilt .skill bundle
- Config passed to
scaffold.py(PROJECT_NAME,SOURCE_DIR, build/test/run commands,TECH_STACK,include_uiux, …) is substituted into the docs deterministically. Setinclude_uiux: falsefor CLI/library/backend projects and no UIUX references are generated (conditionalADS:IFblocks). - Language — generated docs follow your working language; the shipped templates default to Chinese (matching the canonical spec).
AGENTS.mdstays English by convention (it's the cross-vendor file). - Paths — the agent-config dir defaults to
.project.agents/and docs to.project.agents/docs/context/; override in config if your repo differs.
Benchmarked with the skill-creator harness across three scenarios (greenfield UI app, non-UI library, retrofit existing API), each run with and without the skill:
| with skill | genuine no-skill baseline | |
|---|---|---|
| mean pass-rate | ~93% | ~5% |
The strongest run was the retrofit: it reverse-engineered the architecture and flagged both planted drift issues (a grab-bag util module and a layer violation) without modifying any source file.
ADS generalizes a governance system that was first built and battle-tested inside a real iOS/SwiftUI project, then de-projected into a stack-agnostic spec (bundled here as references/spec.md). The templates are derived from that spec, not from any single project — so nothing stack-specific leaks in.
- 📦 This repo — https://github.com/SmartSunruiyang/agent-development-specification
- ⬇️ Prebuilt bundle —
dist/agent-development-specification.skill - 📖 The canonical spec —
references/spec.md(the tech-agnostic "why") - 🧠 Skill entry point —
SKILL.md - 🐛 Issues / feedback — https://github.com/SmartSunruiyang/agent-development-specification/issues
- 🤖 Claude Code — product · docs
MIT © 2026 SmartSunruiyang
一个通用、不绑定技术栈的 Claude Code 技能：在写第一行代码之前，先为项目铺好 Agent 规则、文档与架构，并在项目演进中持续把它们当作"源真相"。
核心三条教训（AI 协作"vibe coding"踩坑沉淀）：
- 版本控制从第 0 天开始——写代码前先初始化仓库。
- 文档先于代码——需求/架构/路线图/规范是"做之前定的"，不是"做完补的"。
- 架构 > UI > 体验——一个出 bug 能立刻指认"是哪个模块"的项目，存活率高一个数量级。
一整套 .project.agents/ 治理体系：CLAUDE.md / AGENTS.md / SELF_CONSTRAINTS.md（硬约束）/ VIBECODING_GUIDE.md（讲"为什么"）+ 上游文档 PRD / ARCHITECTURE（模块卡片 + 依赖 DAG + 接口契约）/ ROADMAP / CONVENTIONS / UIUX，外加 git init 与一个空骨架 commit。
- 全新项目：脚手架 + 需求→架构的引导式访谈，把文档填成真实内容。
- 存量代码库：读你的代码，逆向出一份草稿版
ARCHITECTURE.md供你修正，并标出技术债（语义为空的"大杂烩"模块、跨层访问、死代码）——不动你的源码。
技能就是一个名为 agent-development-specification/ 的文件夹，放进 Claude Code 的 skills 目录：
# 从预打包文件（dist 里的 .skill，本质是 zip）：
unzip dist/agent-development-specification.skill -d ~/.claude/skills/
# 或克隆本仓库到 skills 目录：
git clone https://github.com/SmartSunruiyang/agent-development-specification ~/.claude/skills/agent-development-specification装完新开一个会话即可发现。
输入 /agent-development-specification，或直接说「帮这个项目建立起步指南与 Agent 规范」即可触发。
Claude Code + Python 3（脚手架脚本要用），无其他依赖。