project-blueprint

Project Blueprint 🏗️

One command to make any project AI-agent-ready. 一键为新项目建立完整 AI 编程规范体系。

Topics ·

中文文档

---

What is this?

Project Blueprint is a reusable AI agent skill that transforms any new project into an AI-ready codebase in one sentence. It's not a static template — it's an autonomous discovery engine: scan your project files, intelligently classify dependencies, and dynamically assemble a customized AGENTS.md, documentation skeleton, CI/CD pipeline, and testing policy from a 95-entry component knowledge base.

Just say: "Initialize this project's development standards" and the agent does the rest.

Quick Install

# Global (GitHub)
npx skills add shuguang1994/project-blueprint

# China (Gitee mirror, no proxy needed)
npx skills add https://gitee.com/shuguang1994/project-blueprint.git

# Update later
npx skills update project-blueprint

DeepSeek Harness (dsh) plugin:

dsh plugin --profile web add 'github:shuguang1994/project-blueprint'

Supported agents: Claude Code, Cursor, GitHub Copilot, Codex, Windsurf, Trae, OpenCode, DeepSeek Harness, and 28+ more.

Why

AGENTS.md is now an industry standard in 2026 — used by 60,000+ open-source repos, co-promoted by OpenAI, Google, Anthropic, and Microsoft. 76% of developers use AI coding assistants (Stack Overflow 2025), but without AGENTS.md, AI agents are like "new hires with no onboarding" — producing inconsistent code styles, broken architecture, and failing CI.

Industry data: Anthropic benchmarks show AGENTS.md reduces wrong-pattern rewrites by 40-60%. But writing a quality AGENTS.md by hand takes half a day to a full day — repeated for every new project.

Project Blueprint's approach: No preset templates. Autonomous scanning → intelligent classification → dynamic assembly. The AGENTS.md you get reflects your project's actual tech stack. And it's the only tool that generates AGENTS.md + docs skeleton + CI pipeline + testing policy + Git conventions — all from one sentence.

Core Capabilities

What It Generates

On demand: small projects only get a single gate + unified entry — no full gate layer or protocol doc (stays lean, avoids over-engineering).

Autonomous Discovery Engine

Project Blueprint doesn't check a fixed list of files. It scans your project and discovers everything.

Dependency Classification: 3-Tier

All detected dependencies
    ↓
Tier 1: Knowledge Base Exact Match
  Hit in 95-entry component KB → instant
    ↓
Tier 2: Name Pattern Heuristic
  29 patterns covering 100+ keywords → auto-classify
  e.g. winston → logging, antdv-next → ui, mysql2 → database
    ↓
Tier 3: Web Search
  Truly unknown → real-time search for latest info

Tech Stack Coverage

Web Search Fallback

Every dimension has a web search fallback — not just language/framework, but CSS, lint, package manager, deployment, UI libraries, database, and state management:

Unknown dep: @shadcn/ui not in knowledge base
→ Heuristic: contains "shadcn" + "ui" → dimension: ui
→ WebSearch: "shadcn/ui component library conventions 2026"
→ Extracts: registration patterns, theming, Tailwind integration
→ Writes into AGENTS.md

Web fallback covers two phases: generation (web search for unknown deps/modules) + coding (the generated AGENTS.md requires verifying third-party library APIs/versions against official docs before writing code).

Unique Innovations

Verified via web search — no existing AGENTS.md generation tool implements these.

What Makes It Different

• Autonomous discovery, not preset — scans what your project actually has
• 3-tier classification — exact match → pattern heuristic → web search
• Full-stack coverage — AGENTS.md + docs + CI + testing policy + Git, one sentence
• Incremental-friendly — auto-detects existing projects, adds only what's missing
• Monorepo closest-file-wins — multi sub-project repos get a root + per-package AGENTS.md, matching the official AGENTS.md semantics
• Self-evolving — generated AGENTS.md is not a dead file; it teaches the AI to maintain itself as the project grows
• MCP-ready tooling — auto-recommends MCP tools + combos from your stack, with an installable doc that never ships outdated commands
• AI mistake prevention + BUG→conventions feedback loop — built-in 7-category 27-item AI common-mistakes KB injected at init; conventions-deficiency bugs auto-feed back into AGENTS.md and B-01, so conventions evolve with real practice
• Conventions that don't rot — not just static docs: every blocking red line ships with an executable check, the gate registry has a single source of truth and a constitution self-check, so conventions grow with the project instead of drifting
• Growable gates — init only seeds generic gates; the project's AI turns real pitfalls into domain gates per the meta-rules (no rule without a gate / every defect closes the loop)
• Conventions that don't drift — a seed gate (drift-check) checks dependencies ↔ tech-stack row, module table ↔ actual dirs, and gate validity, so spec and code can't silently diverge (quality-gates / spec-code drift)
• Progressive disclosure — the skill body is a slim ≤200-line index; Step details load on demand, keeping always-loaded context small without losing depth
• Chinese-first — 7 languages, 15 frameworks, 95 component entries natively in Chinese

How It Works

User says: "Initialize this project"
    ↓
Step 1: Autonomous scan → file classification → dep inference (3-tier)
    ↓ (Step details load on demand from references/step-*.md)
Step 2: Rule engine assembles AGENTS.md from 95-entry component KB
    ↓ (unknown stack → WebSearch fallback)
    ↓ (multi sub-project → root AGENTS.md + per-package AGENTS.md)
Step 3: Dynamic docs skeleton by business type (12 types) + MCP tool recommendation (B-05)
    ↓
Step 4: Configure Git (.gitignore + branch strategy)
    ↓
Step 5: Configure CI/CD (language + platform adaptive)
    ↓
Step 6: Establish testing policy (phase-appropriate, not forced)
    ↓
Step 7: Inject continuous self-maintenance instructions
    ↓
Done: 15+ files generated (multi sub-project adds per-package AGENTS.md), project is AI-ready

Requirements

• Any AI coding agent that supports SKILL.md format
• Node.js (for npx skills add installation)

Contributing

Contributions welcome! Areas to help:

• Knowledge base: Add more language/framework/ORM/UI library entries to references/knowledge-base.md
• MCP tools: Add MCP tool entries (usage/install/combination) to references/mcp-tools.md, expanding dimension coverage
• Code conventions: Add/refine base coding convention rules (naming/directory/error handling/logging/security/performance, with search templates) in references/code-conventions.md
• AI mistakes: Add AI common-mistake entries (mistake/consequence/❌example/✅fix/KB link/search template) to references/ai-common-mistakes.md, expanding anti-pattern coverage
• Gate scripts: write a check script for a common pitfall in some stack (single file, zero external deps) — reusable by any project
• Heuristic rules: Expand Step 1.2 name pattern classification, covering more dependency keywords
• File discovery: Extend Step 1.1 file pattern mapping for more build tools and language ecosystems
• Business types: Expand Step 3.0 config feature inference for more project types
• CI platforms: Add templates for more CI platforms (GitLab CI, Jenkins, CircleCI, etc.)
• Real-world feedback: Share use cases and improvement suggestions from real projects to help the framework evolve
• Translations: README to Japanese, Korean, and other languages

License

MIT — see LICENSE for details.

---

Author: 曙光 (shuguang1994)

Made with ❤️ in China | 始于实战，开源共享