smartsunruiyang/agent-development-specification

This is a skill for Claude Code, the AI coding assistant, that sets up a project's documentation and governance structure before any actual code gets written. The core idea is that AI-assisted coding goes wrong when requirements, architecture, and conventions are fuzzy from the start. By front-loading those decisions into organized documents that the AI can reference, the project stays coherent as it grows. When you run this skill in a project folder, it creates a set of files covering what the project does, how the code is organized, what the roadmap looks like, and what conventions to follow for naming, testing, and commits. It then conducts a guided interview, asking you questions about your project to fill those documents with real content rather than placeholder text. A completion check runs at the end to confirm nothing was left blank. The skill works in two modes. For a brand new project it scaffolds everything from scratch and walks you through requirements and architecture decisions step by step. For an existing project that has no formal documentation, it reads the current code, builds a draft architecture description from what it finds, and flags structural problems like overgrown modules or code that nothing actually calls. It does not touch your source files during this process. The files it creates go into a folder called .project.agents and include an agent guide, a hard constraints list the AI checks before each task, a product requirements document, an architecture document with module descriptions and dependency relationships, a roadmap with milestones, and a conventions guide. There is also an optional UI and design tokens file for projects that have a visual interface. Installing the skill means placing its folder into Claude Code's skills directory, either by cloning the repository or unzipping a prebuilt bundle. Python 3 is the only outside requirement. No framework or language lock-in is involved. The documentation templates default to Chinese but adapt to whatever language you are working in.