[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-83896":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":13,"contributorsCount":13,"subscribersCount":13,"size":13,"stars1d":15,"stars7d":16,"stars30d":16,"stars90d":13,"forks30d":13,"starsTrendScore":17,"compositeScore":18,"rankGlobal":10,"rankLanguage":10,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":22,"hasPages":20,"topics":23,"createdAt":10,"pushedAt":10,"updatedAt":24,"readmeContent":25,"aiSummary":10,"trendingCount":13,"starSnapshotCount":13,"syncStatus":26,"lastSyncTime":27,"discoverSource":28},83896,"Agent-development-specification","SmartSunruiyang\u002FAgent-development-specification","SmartSunruiyang","一个通用、不绑定技术栈的 Claude Code 技能：在写第一行代码之前，先为项目铺好 Agent 规则、文档与架构，并在项目演进中持续把它们当作\"源真相\"。","",null,"Python",83,0,51,12,32,48,79.2,"MIT License",false,"main",true,[],"2026-06-12 04:01:42","# Agent Development Specification (ADS)\n\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg)](LICENSE)\n[![Claude Code](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FClaude%20Code-Skill-d97757)](https:\u002F\u002Fclaude.com\u002Fclaude-code)\n[![Agent Skill](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FAgent-Skill-5436DA)](https:\u002F\u002Fdocs.claude.com\u002Fen\u002Fdocs\u002Fclaude-code)\n[![Python 3](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FPython-3-3776AB?logo=python&logoColor=white)](https:\u002F\u002Fwww.python.org\u002F)\n[![PRs Welcome](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FPRs-welcome-brightgreen.svg)](https:\u002F\u002Fgithub.com\u002FSmartSunruiyang\u002Fagent-development-specification\u002Fpulls)\n\n**Topics:** `claude-code` · `claude-code-skills` · `agent-skills` · `ai-agents` · `project-scaffolding` · `software-architecture` · `documentation` · `vibe-coding`\n\n**Jump to:** [What it generates](#what-it-generates) · [Install](#install) · [Usage](#usage) · [How it works](#how-it-works) · [Evaluation](#evaluation) · [License](LICENSE) · [中文说明](#中文说明)\n\n> A universal, tech-stack-agnostic [**Claude Code**](https:\u002F\u002Fclaude.com\u002Fclaude-code) skill that lays down a project's\n> agent-governance rules, documentation, and architecture **before the first line of code** —\n> and keeps them the source of truth as the project grows.\n\nThe governing idea, learned the hard way from AI-assisted \"vibe coding\":\n\n1. **Version control from day 0** — initialize the repo before writing any code.\n2. **Documentation before code** — requirements, architecture, roadmap, conventions are decided *up front*, not back-filled.\n3. **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.\n\nADS 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.\n\n---\n## important ！！\n你应当第一步先单独与 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.\n\n## What it generates\n\n```\n.project.agents\u002F\n├── CLAUDE.md              # project-level agent guide (what\u002Fhow\u002Frules)\n├── AGENTS.md              # cross-vendor contributor guide (Codex etc.)\n├── SELF_CONSTRAINTS.md    # hard constraints — checked before every task\n├── VIBECODING_GUIDE.md    # the practice guide (the \"why\")\n├── settings.json          # agent hooks\u002Fpermissions (contained here)\n├── docs\u002Fcontext\u002F\n│   ├── PRD.md             # product requirements (source of truth for behavior)\n│   ├── ARCHITECTURE.md    # module cards + dependency DAG + interface contracts\n│   ├── ROADMAP.md         # milestones with acceptance checks\n│   ├── CONVENTIONS.md     # naming \u002F style \u002F commits \u002F testing\n│   └── UIUX.md            # visual tokens + interaction (UI projects only)\n└── log\u002F                   # execution logs\n```\n\nPlus `git init` and a zero-point skeleton commit.\n\n## Two modes\n\n- **Greenfield** — a fresh\u002Fempty project: scaffold everything, then a guided requirements→architecture interview fills the docs.\n- **Retrofit** — an existing codebase with no governance: it reads the code (CodeGraph-aware), reverse-engineers a *draft* `ARCHITECTURE.md` for you to correct, and flags drift (god-modules, layer violations, dead code) — without touching your source.\n\n## How it works\n\n`\u002Fagent-development-specification` (the skill's `init`) runs four phases:\n\n1. **Detect state** — greenfield vs. existing code vs. already-scaffolded.\n2. **Mechanical scaffold** — `scripts\u002Fscaffold.py` builds 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.\n3. **Guided interview** — the spec's Step 1–7 flow (requirements → domain model → module cards → dependency DAG → roadmap → conventions), filling each doc with real content.\n4. **Completion gate** — before committing, it greps for any unfilled `{{token}}` \u002F marker and resolves every one, so no half-written doc ships.\n\n---\n\n## Install\n\nThe skill is a folder named `agent-development-specification\u002F` placed in a Claude Code skills directory.\n\n**Option A — from the prebuilt bundle** (`dist\u002Fagent-development-specification.skill`, a zip):\n\n```sh\n# all projects (personal):\nunzip dist\u002Fagent-development-specification.skill -d ~\u002F.claude\u002Fskills\u002F\n# or one project:\nunzip dist\u002Fagent-development-specification.skill -d \u002Fpath\u002Fto\u002Fproject\u002F.claude\u002Fskills\u002F\n```\n\n**Option B — clone this repo into the skills dir:**\n\n```sh\ngit clone https:\u002F\u002Fgithub.com\u002FSmartSunruiyang\u002Fagent-development-specification \\\n  ~\u002F.claude\u002Fskills\u002Fagent-development-specification\n```\n\nThen **start a new Claude Code session** (skills are discovered at session start).\n\n## Usage\n\n```\n\u002Fagent-development-specification\n```\n\n…or just ask in natural language — *\"set up the agent governance \u002F project spec for this project\"*, *\"建立这个项目的起步指南与 Agent 规范\"* — and it triggers.\n\n## Requirements\n\n- **Claude Code** (the skill runtime).\n- **Python 3** — `scripts\u002Fscaffold.py` needs it (`python3 --version`).\n- No other dependencies.\n\n---\n\n## Repository layout\n\n```\n.\n├── SKILL.md                 # the orchestrator (frontmatter + workflow)\n├── references\u002F\n│   ├── spec.md              # the canonical, tech-agnostic spec (the \"why\")\n│   ├── interview-flow.md    # the Step 1–7 interview script\n│   └── retrofit.md          # reverse-engineering architecture from code\n├── assets\u002Ftemplates\u002F        # the files written into the target repo\n│   └── docs\u002F                # PRD \u002F ARCHITECTURE \u002F ROADMAP \u002F CONVENTIONS \u002F UIUX skeletons\n├── scripts\u002Fscaffold.py      # idempotent, non-destructive scaffolder\n├── evals\u002Fevals.json         # test cases\n└── dist\u002F                    # prebuilt .skill bundle\n```\n\n## Customization\n\n- **Config** passed to `scaffold.py` (`PROJECT_NAME`, `SOURCE_DIR`, build\u002Ftest\u002Frun commands, `TECH_STACK`, `include_uiux`, …) is substituted into the docs deterministically. Set `include_uiux: false` for CLI\u002Flibrary\u002Fbackend projects and **no UIUX references are generated** (conditional `ADS:IF` blocks).\n- **Language** — generated docs follow your working language; the shipped templates default to Chinese (matching the canonical spec). `AGENTS.md` stays English by convention (it's the cross-vendor file).\n- **Paths** — the agent-config dir defaults to `.project.agents\u002F` and docs to `.project.agents\u002Fdocs\u002Fcontext\u002F`; override in config if your repo differs.\n\n## Evaluation\n\nBenchmarked with the skill-creator harness across three scenarios (greenfield UI app, non-UI library, retrofit existing API), each run with **and** without the skill:\n\n| | with skill | genuine no-skill baseline |\n|---|---|---|\n| mean pass-rate | **~93%** | **~5%** |\n\nThe 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.\n\n## Origin\n\nADS generalizes a governance system that was first built and battle-tested inside a real iOS\u002FSwiftUI project, then de-projected into a stack-agnostic spec (bundled here as `references\u002Fspec.md`). The templates are derived from that spec, not from any single project — so nothing stack-specific leaks in.\n\n## Resources\n\n- 📦 **This repo** — \u003Chttps:\u002F\u002Fgithub.com\u002FSmartSunruiyang\u002Fagent-development-specification>\n- ⬇️ **Prebuilt bundle** — [`dist\u002Fagent-development-specification.skill`](dist\u002Fagent-development-specification.skill)\n- 📖 **The canonical spec** — [`references\u002Fspec.md`](references\u002Fspec.md) (the tech-agnostic \"why\")\n- 🧠 **Skill entry point** — [`SKILL.md`](SKILL.md)\n- 🐛 **Issues \u002F feedback** — \u003Chttps:\u002F\u002Fgithub.com\u002FSmartSunruiyang\u002Fagent-development-specification\u002Fissues>\n- 🤖 **Claude Code** — [product](https:\u002F\u002Fclaude.com\u002Fclaude-code) · [docs](https:\u002F\u002Fdocs.claude.com\u002Fen\u002Fdocs\u002Fclaude-code)\n\n## License\n\n[MIT](LICENSE) © 2026 [SmartSunruiyang](https:\u002F\u002Fgithub.com\u002FSmartSunruiyang)\n\n---\n\n# 中文说明\n\n> 一个**通用、不绑定技术栈的 Claude Code 技能**：在写第一行代码**之前**，先为项目铺好\n> Agent 规则、文档与架构，并在项目演进中持续把它们当作\"源真相\"。\n\n核心三条教训（AI 协作\"vibe coding\"踩坑沉淀）：\n\n1. **版本控制从第 0 天开始**——写代码前先初始化仓库。\n2. **文档先于代码**——需求\u002F架构\u002F路线图\u002F规范是\"做之前定的\"，不是\"做完补的\"。\n3. **架构 > UI > 体验**——一个出 bug 能立刻指认\"是哪个模块\"的项目，存活率高一个数量级。\n\n## 它生成什么\n一整套 `.project.agents\u002F` 治理体系：`CLAUDE.md` \u002F `AGENTS.md` \u002F `SELF_CONSTRAINTS.md`（硬约束）\u002F `VIBECODING_GUIDE.md`（讲\"为什么\"）+ 上游文档 `PRD \u002F ARCHITECTURE（模块卡片 + 依赖 DAG + 接口契约）\u002F ROADMAP \u002F CONVENTIONS \u002F UIUX`，外加 `git init` 与一个空骨架 commit。\n\n## 两种模式\n- **全新项目**：脚手架 + 需求→架构的引导式访谈，把文档填成真实内容。\n- **存量代码库**：读你的代码，逆向出一份**草稿版** `ARCHITECTURE.md` 供你修正，并标出技术债（语义为空的\"大杂烩\"模块、跨层访问、死代码）——**不动你的源码**。\n\n## 安装\n技能就是一个名为 `agent-development-specification\u002F` 的文件夹，放进 Claude Code 的 skills 目录：\n\n```sh\n# 从预打包文件（dist 里的 .skill，本质是 zip）：\nunzip dist\u002Fagent-development-specification.skill -d ~\u002F.claude\u002Fskills\u002F\n# 或克隆本仓库到 skills 目录：\ngit clone https:\u002F\u002Fgithub.com\u002FSmartSunruiyang\u002Fagent-development-specification ~\u002F.claude\u002Fskills\u002Fagent-development-specification\n```\n装完**新开一个会话**即可发现。\n\n## 使用\n输入 `\u002Fagent-development-specification`，或直接说「帮这个项目建立起步指南与 Agent 规范」即可触发。\n\n## 依赖\nClaude Code + Python 3（脚手架脚本要用），无其他依赖。\n\n## 相关链接 \u002F 许可\n- 仓库：\u003Chttps:\u002F\u002Fgithub.com\u002FSmartSunruiyang\u002Fagent-development-specification>\n- 预打包文件：[`dist\u002Fagent-development-specification.skill`](dist\u002Fagent-development-specification.skill)\n- 通用规范原文：[`references\u002Fspec.md`](references\u002Fspec.md)\n- 许可：[MIT](LICENSE) © 2026 [SmartSunruiyang](https:\u002F\u002Fgithub.com\u002FSmartSunruiyang)\n",2,"2026-06-11 04:11:48","CREATED_QUERY"]