[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-Pimzino--claude-code-spec-workflow":3,"tool-Pimzino--claude-code-spec-workflow":62},[4,18,26,36,46,54],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",159267,2,"2026-04-17T11:29:14",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":42,"last_commit_at":43,"category_tags":44,"status":17},8272,"opencode","anomalyco\u002Fopencode","OpenCode 是一款开源的 AI 编程助手（Coding Agent），旨在像一位智能搭档一样融入您的开发流程。它不仅仅是一个代码补全插件，而是一个能够理解项目上下文、自主规划任务并执行复杂编码操作的智能体。无论是生成全新功能、重构现有代码，还是排查难以定位的 Bug，OpenCode 都能通过自然语言交互高效完成，显著减少开发者在重复性劳动和上下文切换上的时间消耗。\n\n这款工具专为软件开发者、工程师及技术研究人员设计，特别适合希望利用大模型能力来提升编码效率、加速原型开发或处理遗留代码维护的专业人群。其核心亮点在于完全开源的架构，这意味着用户可以审查代码逻辑、自定义行为策略，甚至私有化部署以保障数据安全，彻底打破了传统闭源 AI 助手的“黑盒”限制。\n\n在技术体验上，OpenCode 提供了灵活的终端界面（Terminal UI）和正在测试中的桌面应用程序，支持 macOS、Windows 及 Linux 全平台。它兼容多种包管理工具，安装便捷，并能无缝集成到现有的开发环境中。无论您是追求极致控制权的资深极客，还是渴望提升产出的独立开发者，OpenCode 都提供了一个透明、可信",144296,1,"2026-04-16T14:50:03",[13,45],"插件",{"id":47,"name":48,"github_repo":49,"description_zh":50,"stars":51,"difficulty_score":32,"last_commit_at":52,"category_tags":53,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108322,"2026-04-10T11:39:34",[14,15,13],{"id":55,"name":56,"github_repo":57,"description_zh":58,"stars":59,"difficulty_score":32,"last_commit_at":60,"category_tags":61,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[45,13,15,14],{"id":63,"github_repo":64,"name":65,"description_en":66,"description_zh":67,"ai_summary_zh":68,"readme_en":69,"readme_zh":70,"quickstart_zh":71,"use_case_zh":72,"hero_image_url":73,"owner_login":74,"owner_name":74,"owner_avatar_url":75,"owner_bio":76,"owner_company":76,"owner_location":76,"owner_email":77,"owner_twitter":76,"owner_website":76,"owner_url":78,"languages":79,"stars":96,"forks":97,"last_commit_at":98,"license":99,"difficulty_score":32,"env_os":100,"env_gpu":101,"env_ram":101,"env_deps":102,"category_tags":107,"github_topics":76,"view_count":32,"oss_zip_url":76,"oss_zip_packed_at":76,"status":17,"created_at":108,"updated_at":109,"faqs":110,"releases":111},8597,"Pimzino\u002Fclaude-code-spec-workflow","claude-code-spec-workflow","Automated workflows for Claude Code. Features spec-driven development for new features (Requirements → Design → Tasks → Implementation) and streamlined bug fix workflow for quick issue resolution (Report → Analyze → Fix → Verify).","claude-code-spec-workflow 是一款专为 Claude Code 设计的自动化工作流工具，旨在将软件开发过程标准化和智能化。它主要解决了开发过程中需求模糊、任务拆解繁琐以及 Bug 修复缺乏系统性的痛点，通过预设的结构化流程，帮助团队从混乱的手动操作转向有序的自动执行。\n\n该工具特别适合希望提升编码效率的开发者、技术负责人以及追求工程规范化的软件团队使用。其核心亮点在于提供两套完整的闭环工作流：针对新功能开发的“规格驱动”流程（涵盖需求分析、架构设计、任务拆解到代码实现），以及针对问题修复的“快速响应”流程（包含报告、根因分析、修复与验证）。\n\n技术上，claude-code-spec-workflow 引入了多智能体协作机制，内置 4 个专用代理角色，能够根据上下文自动执行原子化任务。用户只需输入简单的斜杠命令（如 `\u002Fspec-create` 或 `\u002Fbug-fix`），即可触发包含文档生成、任务分解及代码实施在内的全套操作。此外，它还支持项目引导设置（Steering Setup），可持久化保存产品与技术标准，确保 AI 输出始终符合项目规范。虽然官方已转向","claude-code-spec-workflow 是一款专为 Claude Code 设计的自动化工作流工具，旨在将软件开发过程标准化和智能化。它主要解决了开发过程中需求模糊、任务拆解繁琐以及 Bug 修复缺乏系统性的痛点，通过预设的结构化流程，帮助团队从混乱的手动操作转向有序的自动执行。\n\n该工具特别适合希望提升编码效率的开发者、技术负责人以及追求工程规范化的软件团队使用。其核心亮点在于提供两套完整的闭环工作流：针对新功能开发的“规格驱动”流程（涵盖需求分析、架构设计、任务拆解到代码实现），以及针对问题修复的“快速响应”流程（包含报告、根因分析、修复与验证）。\n\n技术上，claude-code-spec-workflow 引入了多智能体协作机制，内置 4 个专用代理角色，能够根据上下文自动执行原子化任务。用户只需输入简单的斜杠命令（如 `\u002Fspec-create` 或 `\u002Fbug-fix`），即可触发包含文档生成、任务分解及代码实施在内的全套操作。此外，它还支持项目引导设置（Steering Setup），可持久化保存产品与技术标准，确保 AI 输出始终符合项目规范。虽然官方已转向功能更强大的 MCP 版本，但此工具仍为现有用户提供了一套成熟、开箱即用的自动化解决方案，让开发过程更加流畅可控。","# Claude Code Spec Workflow\n\n> **⚠️ IMPORTANT NOTICE:** Development focus has shifted to the **MCP (Model Context Protocol) version** of this workflow system. The MCP version provides enhanced features, real-time dashboard, and broader AI tool compatibility.\n> \n> **🚀 [View the new Spec Workflow MCP →](https:\u002F\u002Fgithub.com\u002FPimzino\u002Fspec-workflow-mcp)**\n>\n> This Claude Code-specific version remains available for existing users but will receive limited updates.\n\n[![npm version](https:\u002F\u002Fbadge.fury.io\u002Fjs\u002F@pimzino%2Fclaude-code-spec-workflow.svg?cacheSeconds=300)](https:\u002F\u002Fbadge.fury.io\u002Fjs\u002F@pimzino%2Fclaude-code-spec-workflow)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg)](https:\u002F\u002Fopensource.org\u002Flicenses\u002FMIT)\n\n**Automated workflows for Claude Code with intelligent task execution.**\n\nTransform your development with structured workflows: **Requirements → Design → Tasks → Implementation** for new features, plus streamlined **Report → Analyze → Fix → Verify** for bug fixes.\n\n## ☕ Support This Project\n\n\u003Ca href=\"https:\u002F\u002Fbuymeacoffee.com\u002FPimzino\" target=\"_blank\">\u003Cimg src=\"https:\u002F\u002Fcdn.buymeacoffee.com\u002Fbuttons\u002Fv2\u002Fdefault-yellow.png\" alt=\"Buy Me A Coffee\" style=\"height: 60px !important;width: 217px !important;\" >\u003C\u002Fa>\n\n---\n\n## 📦 Installation\n\n1. Install the workflow globally\n```bash\nnpm i -g @pimzino\u002Fclaude-code-spec-workflow\n```\n2. Run the setup command in your project directory\n```bash\nclaude-code-spec-workflow\n```\n**Thats it, you are ready to go!**\n---\n\n## ✨ What You Get\n\n- **📁 Complete .claude\u002F structure** - All files and directories\n- **📝 10 slash commands** - 5 spec workflow + 5 bug fix workflow\n- **🎯 Intelligent task execution** - Automated implementation\n- **🤖 4 specialized agents** - Enhanced automation\n- **📊 Real-time dashboard** - Monitor progress visually\n- **🔧 Auto-generated commands** - One command per task\n- **📋 Document templates** - Professional spec documents\n- **⚙️ Project steering** - Persistent context and standards\n- **⚡ Smart optimization** - Intelligent context sharing and caching\n\n---\n\n## 🔄 Workflows Overview\n\n### 📊 **Spec Workflow** (New Features)\n\n**Complete automation in one command:**\n\n```bash\n\u002Fspec-create feature-name \"Description\"\n```\n\n**What happens:**\n1. **Requirements** → User stories + acceptance criteria\n2. **Design** → Technical architecture + diagrams\n3. **Tasks** → Atomic, agent-friendly breakdown\n4. **Commands** → Auto-generated task commands (optional)\n\n**Execute tasks:**\n```bash\n# Manual control\n\u002Fspec-execute 1 feature-name\n\u002Ffeature-name-task-1        # Auto-generated\n```\n\n### 🐛 **Bug Fix Workflow** (Quick Fixes)\n\n```bash\n\u002Fbug-create issue-name \"Description\"  # Document the bug\n\u002Fbug-analyze                          # Find root cause\n\u002Fbug-fix                             # Implement solution\n\u002Fbug-verify                          # Confirm resolution\n```\n\n### 🎯 **Steering Setup** (Project Context)\n\n```bash\n\u002Fspec-steering-setup  # Creates product.md, tech.md, structure.md\n```\n\n---\n\n## 🛠️ Commands Reference\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>📊 Spec Workflow Commands\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n| Command | Purpose |\n|---------|---------|\n| `\u002Fspec-steering-setup` | Create project context documents |\n| `\u002Fspec-create \u003Cname>` | Complete spec workflow |\n| `\u002Fspec-execute \u003Ctask-id>` | Manual task execution |\n| `\u002F\u003Cname>-task-\u003Cid>` | Auto-generated task commands |\n| `\u002Fspec-status` | Show progress |\n| `\u002Fspec-list` | List all specs |\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🐛 Bug Fix Commands\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n| Command | Purpose |\n|---------|---------|\n| `\u002Fbug-create \u003Cname>` | Document bug with structured format |\n| `\u002Fbug-analyze` | Investigate root cause |\n| `\u002Fbug-fix` | Implement targeted solution |\n| `\u002Fbug-verify` | Verify resolution |\n| `\u002Fbug-status` | Show bug fix progress |\n\n\u003C\u002Fdetails>\n\n---\n\n## 🎯 Key Features\n\n### 🤖 **Intelligent Task Execution**\n- **Streamlined** task implementation\n- **Context-aware** execution with full specification context\n- **Agent-based** implementation with spec-task-executor\n\n### 🧠 **Specialized Agents** (Optional)\n4 AI agents for enhanced automation:\n\n**Core Workflow:** `spec-task-executor`, `spec-requirements-validator`, `spec-design-validator`, `spec-task-validator`\n\n\n> **Note:** Agents are optional - everything works with built-in fallbacks.\n\n### ⚡ **Complete Context Optimization** (NEW!)\n- **Universal context sharing** - Steering, specification, AND template documents optimized\n- **60-80% token reduction** - Eliminates redundant document fetching across all document types\n- **Triple optimization commands** - `get-steering-context`, `get-spec-context`, and `get-template-context`\n- **Smart document handling** - Bug documents use direct reading (no redundancy), templates use bulk loading (high redundancy)\n- **Improved performance** - Faster agent execution with cached context across all workflows\n- **Automatic fallback** - Maintains reliability with individual `get-content` when optimization unavailable\n- **Session-based caching** - Intelligent file change detection and cache invalidation\n\n### 📊 **Real-Time Dashboard**\n```bash\nnpx -p @pimzino\u002Fclaude-code-spec-workflow claude-spec-dashboard\n```\n- Live progress tracking\n- WebSocket updates\n- Git integration\n- Modern UI with Tailwind CSS\n\n---\n\n### 🔗 Dashboard Tunnel (NEW!)\n\nShare your dashboard securely with external stakeholders through temporary HTTPS URLs:\n\n```bash\n# Start dashboard with tunnel\nnpx -p @pimzino\u002Fclaude-code-spec-workflow claude-spec-dashboard --tunnel\n\n# With password protection\nnpx -p @pimzino\u002Fclaude-code-spec-workflow claude-spec-dashboard --tunnel --tunnel-password mySecret123\n\n# Choose specific provider\nnpx -p @pimzino\u002Fclaude-code-spec-workflow claude-spec-dashboard --tunnel --tunnel-provider cloudflare\n```\n\n**Tunnel Features:**\n- **🔒 Secure HTTPS URLs** - Share dashboard with managers, clients, or remote team members\n- **👁️ Read-Only Access** - External viewers cannot modify any project data\n- **🔑 Optional Password** - Protect access with password authentication\n- **🌐 Multiple Providers** - Automatic fallback between Cloudflare and ngrok\n- **📊 Usage Analytics** - Track who accessed your dashboard and when\n- **⏰ Auto-Expiration** - Tunnels close when you stop the dashboard\n- **🚀 Zero Configuration** - Works out of the box with built-in providers\n\n## 📊 Command Line Options\n\n### Setup Commands\n```bash\n# Setup in current directory\nnpx @pimzino\u002Fclaude-code-spec-workflow\n\n# Setup in specific directory\nnpx @pimzino\u002Fclaude-code-spec-workflow --project \u002Fpath\u002Fto\u002Fproject\n\n# Force overwrite existing files\nnpx @pimzino\u002Fclaude-code-spec-workflow --force\n\n# Skip confirmation prompts\nnpx @pimzino\u002Fclaude-code-spec-workflow --yes\n\n# Test the setup\nnpx @pimzino\u002Fclaude-code-spec-workflow test\n```\n\n### Dashboard Commands\n```bash\n# Basic dashboard\nnpx -p @pimzino\u002Fclaude-code-spec-workflow claude-spec-dashboard\n\n# Dashboard with tunnel (share externally)\nnpx -p @pimzino\u002Fclaude-code-spec-workflow claude-spec-dashboard --tunnel\n\n# Full tunnel configuration\nnpx -p @pimzino\u002Fclaude-code-spec-workflow claude-spec-dashboard \\\n  --tunnel \\\n  --tunnel-password mySecret123 \\\n  --tunnel-provider cloudflare \\\n  --port 3000 \\\n  --open\n```\n\n## 🎯 Steering Documents (NEW!)\n\nSteering documents provide persistent project context that guides all spec development:\n\n### **Product Document** (`product.md`)\n- Product vision and purpose\n- Target users and their needs\n- Key features and objectives\n- Success metrics\n\n### **Technology Document** (`tech.md`)\n- Technology stack and frameworks\n- Development tools and practices\n- Technical constraints and requirements\n- Third-party integrations\n\n### **Structure Document** (`structure.md`)\n- File organization patterns\n- Naming conventions\n- Import patterns\n- Code organization principles\n\nRun `\u002Fspec-steering-setup` to create these documents. Claude will analyze your project and help you define these standards.\n\n## 🎨 Features\n\n### ✅ **Zero Configuration**\n- Works out of the box with any project\n- Auto-detects project type (Node.js, Python, Java, etc.)\n- Validates Claude Code installation\n\n### ✅ **Interactive Setup**\n- Beautiful CLI with progress indicators\n- Confirmation prompts for safety\n- Helpful error messages and guidance\n\n### ✅ **Smart File Management**\n- Complete workflow instructions in each command file\n- Creates comprehensive directory structure\n- Includes all necessary templates and configs\n\n### ✅ **Professional Quality**\n- **Full TypeScript implementation** with strict type checking\n- **Frontend converted to TypeScript** for enhanced dashboard development\n- **95%+ type coverage** with no implicit any types\n- **Modern build pipeline** with esbuild bundling and source maps\n- Comprehensive error handling\n- Follows npm best practices\n\n### ✅ **Steering Document Integration**\n- Persistent project context across all specs\n- Automatic alignment with project standards\n- Consistent code generation\n- Reduced need for repetitive explanations\n\n### ✅ **TypeScript Dashboard Frontend**\n- **Type-safe frontend code** with comprehensive interfaces\n- **Real-time WebSocket communication** with typed message handling\n- **Petite-vue integration** with custom type definitions\n- **Build pipeline** supporting development and production bundles\n- **Strict null checking** and modern TypeScript patterns\n- **JSDoc documentation** for all exported functions\n\n## 🏗️ Project Structure After Setup\n\n```\nyour-project\u002F\n├── .claude\u002F\n│   ├── commands\u002F           # 14 slash commands + auto-generated\n│   ├── steering\u002F          # product.md, tech.md, structure.md\n│   ├── templates\u002F         # Document templates\n│   ├── specs\u002F            # Generated specifications\n│   ├── bugs\u002F             # Bug fix workflows\n│   └── agents\u002F           # AI agents (enabled by default)\n```\n\n## 🧪 Testing\n\nThe package includes a built-in test command:\n\n```bash\n# Test setup in temporary directory\nnpx @pimzino\u002Fclaude-code-spec-workflow test\n```\n\n## 📋 Requirements\n\n- **Node.js** 16.0.0 or higher\n- **Claude Code** installed and configured\n- Any project directory\n\n## 🔧 Troubleshooting\n\n### Common Issues\n\n**❓ Command not found after NPX**\n```bash\n# Make sure you're using the correct package name\nnpx @pimzino\u002Fclaude-code-spec-workflow\n```\n\n**❓ Setup fails with permission errors**\n```bash\n# Try with different directory permissions\nnpx @pimzino\u002Fclaude-code-spec-workflow --project ~\u002Fmy-project\n```\n\n**❓ Claude Code not detected**\n```bash\n# Install Claude Code first\nnpm install -g @anthropic-ai\u002Fclaude-code\n```\n\n### Debug Information\n\n```bash\n# Show verbose output\nDEBUG=* npx @pimzino\u002Fclaude-code-spec-workflow\n\n# Check package version\nnpx @pimzino\u002Fclaude-code-spec-workflow --version\n```\n\n## 🌟 Examples\n\n### Basic Usage\n```bash\ncd my-awesome-project\nnpx @pimzino\u002Fclaude-code-spec-workflow\nclaude\n# Type: \u002Fspec-create user-dashboard \"User profile management\"\n```\n\n### Advanced Usage\n```bash\n# Setup multiple projects\nfor dir in project1 project2 project3; do\n  npx @pimzino\u002Fclaude-code-spec-workflow --project $dir --yes\ndone\n```\n\n## 🔧 TypeScript Development\n\n### Frontend Dashboard Development\n\nThe dashboard frontend is fully implemented in TypeScript for enhanced type safety and developer experience:\n\n#### Type Definitions\n```typescript\n\u002F\u002F Core dashboard types\ninterface Project {\n  path: string;\n  name: string;\n  level: number;\n  hasActiveSession: boolean;\n  specs: Spec[];\n  bugs: Bug[];\n  steeringStatus?: SteeringStatus;\n}\n\n\u002F\u002F WebSocket message types with discriminated unions\ntype WebSocketMessage = \n  | { type: 'initial'; data: InitialData }\n  | { type: 'update'; data: UpdateData }\n  | { type: 'error'; data: ErrorData }\n  | { type: 'tunnel-status'; data: TunnelStatusData };\n```\n\n#### Build Commands\n```bash\n# TypeScript compilation and bundling\nnpm run build:frontend:dev   # Build frontend for development\nnpm run build:frontend:prod  # Build frontend for production (minified)\nnpm run watch:frontend       # Watch mode with auto-rebuild\nnpm run typecheck:frontend   # Type checking only (no output)\nnpm run typecheck           # Check both backend and frontend types\n\n# Development workflow  \nnpm run dev:dashboard       # Start dashboard with hot reload (frontend + backend)\nnpm run dev:dashboard:backend-only  # Start only backend (for frontend debugging)\n\n# Full build process\nnpm run build              # Complete build: TypeScript + frontend + static files\nnpm run lint               # Lint TypeScript files with auto-fix\nnpm run format             # Format code with Prettier\n```\n\n#### Type Safety Features\n- **Strict TypeScript configuration** with null checks\n- **Runtime type validation** with type guards\n- **WebSocket message typing** for real-time updates  \n- **State management types** for reactive UI components\n- **Error handling types** with Result\u003CT> pattern\n- **Petite-vue integration** with custom type definitions\n\n#### Type Usage Examples\n\n```typescript\n\u002F\u002F Import dashboard types\nimport type { Project, WebSocketMessage, AppState } from '.\u002Fdashboard.types';\n\n\u002F\u002F Type-safe project handling\nfunction selectProject(project: Project): void {\n  console.log(`Selected: ${project.name} (${project.specs.length} specs)`);\n  \n  \u002F\u002F Safe property access with optional chaining\n  const steeringCount = project.steeringStatus?.totalDocs ?? 0;\n  if (steeringCount > 0) {\n    console.log(`Steering docs: ${steeringCount}`);\n  }\n}\n\n\u002F\u002F WebSocket message handling with discriminated unions\nfunction handleMessage(message: WebSocketMessage): void {\n  switch (message.type) {\n    case 'initial':\n      \u002F\u002F TypeScript knows data is InitialData\n      console.log(`Loaded ${message.data.projects.length} projects`);\n      break;\n    case 'update':\n      \u002F\u002F TypeScript knows data is UpdateData\n      console.log(`Updated project: ${message.data.projectPath}`);\n      break;\n    case 'error':\n      \u002F\u002F TypeScript knows data is ErrorData\n      console.error(`Error: ${message.data.message}`);\n      break;\n  }\n}\n\n\u002F\u002F Type guards for runtime validation\nfunction isValidProject(obj: unknown): obj is Project {\n  return (\n    typeof obj === 'object' &&\n    obj !== null &&\n    'path' in obj &&\n    'name' in obj &&\n    'specs' in obj &&\n    Array.isArray((obj as Project).specs)\n  );\n}\n\n\u002F\u002F Result type for error handling\ntype Result\u003CT, E = Error> = \n  | { success: true; data: T }\n  | { success: false; error: E };\n\nfunction parseProjectData(data: unknown): Result\u003CProject> {\n  if (isValidProject(data)) {\n    return { success: true, data };\n  }\n  return { success: false, error: new Error('Invalid project data') };\n}\n```\n\n#### Development Guidelines\n- **JSDoc documentation** on all exported functions\n- **95%+ type coverage** maintained (no implicit any types)\n- **Modern TypeScript patterns** (optional chaining, nullish coalescing)\n- **Type guards preferred** over type assertions\n- **Interfaces for object shapes**, union types for discriminated unions\n- **Result\u003CT> pattern** for error handling\n- **Runtime validation** with type guards for external data\n\n## 📚 Documentation\n\n- **[Full Documentation](https:\u002F\u002Fgithub.com\u002Fpimzino\u002Fclaude-code-spec-workflow#readme)**\n- **[Tunnel Feature Guide](.\u002Fdocs\u002Ftunnel-feature.md)** - Comprehensive tunnel documentation\n- **[Tunnel Examples](.\u002Fexamples\u002Ftunnel\u002F)** - Ready-to-use tunnel scripts\n- **[Claude Code Docs](https:\u002F\u002Fdocs.anthropic.com\u002Fclaude-code)**\n- **[TypeScript API Reference](.\u002Fdocs\u002Ftypescript-api.md)** - Generated from JSDoc comments\n\n## 🤝 Contributing\n\nContributions are welcome! Please see our [Contributing Guide](https:\u002F\u002Fgithub.com\u002Fpimzino\u002Fclaude-code-spec-workflow\u002Fblob\u002Fmain\u002FCONTRIBUTING.md).\n\n## 📄 License\n\nMIT License - see [LICENSE](https:\u002F\u002Fgithub.com\u002Fpimzino\u002Fclaude-code-spec-workflow\u002Fblob\u002Fmain\u002FLICENSE) for details.\n\n## 🏷️ Changelog\n\nSee [CHANGELOG.md](https:\u002F\u002Fgithub.com\u002Fpimzino\u002Fclaude-code-spec-workflow\u002Fblob\u002Fmain\u002FCHANGELOG.md) for version history.\n\n---\n\n## 🚦 When To Use What\n\n| Scenario | Recommended Approach |\n|----------|---------------------|\n| **New feature, well-defined** | `\u002Fspec-execute` or individual task commands |\n| **Complex\u002Fexperimental feature** | `\u002Fspec-execute` (manual control) |\n| **Bug in existing code** | Bug workflow (`\u002Fbug-create` → `\u002Fbug-verify`) |\n| **Learning the codebase** | Manual execution with individual commands |\n| **Production deployment** | Full spec workflow with completion review |\n\n---\n\n## 🚀 Installation & Setup\n\n### **Installation**\n```bash\n# Install globally (recommended)\nnpm install -g @pimzino\u002Fclaude-code-spec-workflow\n\n# Verify installation\nclaude-code-spec-workflow --version\n```\n\n### **Setup Options**\n```bash\n# Basic setup\nclaude-code-spec-workflow\n\n# Advanced options\nclaude-code-spec-workflow --project \u002Fpath --force --yes\n```\n\n**During setup you choose:**\n- ✅ **Enable agents?** Enhanced automation vs simpler setup\n- ✅ **Project analysis** Auto-detection of frameworks and patterns\n\n---\n\n## 📚 Examples\n**Recommendation: Use Claude Opus 4 to generate the spec documentation '\u002Fspec-create', then use Claude Sonnet 4 for the implementation i.e. '\u002Fspec-execute' or '\u002F{spec-name}-task-\u003Cid>'.**\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Basic Workflow Example\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# 1. Install globally (one time)\nnpm install -g @pimzino\u002Fclaude-code-spec-workflow\n\n# 2. Setup project (one time)\ncd my-project\nclaude-code-spec-workflow\n\n# 3. Create steering documents (recommended)\nclaude\n\u002Fspec-steering-setup\n\n# 4. Create feature spec\n\u002Fspec-create user-authentication \"Secure login system\"\n\n# 5. Execute tasks\n\u002Fspec-execute 1 user-authentication\n\n# 6. Monitor progress\n\u002Fspec-status user-authentication\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Bug Fix Example\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n\u002Fbug-create login-timeout \"Users logged out too quickly\"\n\u002Fbug-analyze\n\u002Fbug-fix\n\u002Fbug-verify\n```\n\n\u003C\u002Fdetails>\n\n---\n\n## ⚡ Context Optimization Commands\n\nThe package includes optimized commands for efficient document loading across all document types:\n\n### **get-steering-context**\nLoad all steering documents at once for context sharing:\n```bash\nclaude-code-spec-workflow get-steering-context\n```\n**Output**: Formatted markdown with all steering documents (product.md, tech.md, structure.md)\n\n### **get-spec-context**\nLoad all specification documents at once for context sharing:\n```bash\nclaude-code-spec-workflow get-spec-context feature-name\n```\n**Output**: Formatted markdown with all spec documents (requirements.md, design.md, tasks.md)\n\n### **get-template-context**\nLoad templates by category for context sharing:\n```bash\n# Load all templates\nclaude-code-spec-workflow get-template-context\n\n# Load specific template category\nclaude-code-spec-workflow get-template-context spec    # Spec templates\nclaude-code-spec-workflow get-template-context bug     # Bug templates\nclaude-code-spec-workflow get-template-context steering # Steering templates\n```\n**Output**: Formatted markdown with requested templates\n\n### **Smart Document Handling**\n- **High-redundancy documents** (steering, specs, templates): Use optimized bulk loading\n- **Low-redundancy documents** (bug reports): Use direct file reading for simplicity\n- **Selective delegation**: Main agents load full context, but pass only relevant portions to sub-agents\n- **Individual files**: Continue using `get-content` for edge cases\n\n### **Benefits**\n- **60-80% token reduction** compared to individual file loading\n- **Faster execution** with cached context across all workflows\n- **Automatic fallback** to individual `get-content` when needed\n- **Session-based caching** with intelligent file change detection\n\n### **Hierarchical Context Management**\nThe system implements a sophisticated **hierarchical context management strategy** for maximum efficiency:\n\n**Main Agents** (Commands like `\u002Fspec-execute`, `\u002Fspec-create`):\n- **Load ALL context once** at the beginning using optimized commands\n- **Store complete context** for task coordination and decision-making\n- **Distribute selective context** to sub-agents without requiring reloads\n\n**Sub-Agents** (Agents like `spec-task-executor`):\n- **Priority 1**: Use provided context from task instructions (steering, specification, task details)\n- **Priority 2**: Fallback to loading context only if not provided above\n- **Never redundantly load** context when it's already been provided by main agents\n\n**Context Distribution Pattern**:\n```\nMain Agent loads: Steering + Full Spec + Task Details\n↓ Delegates to Sub-Agent with:\n├── Complete Steering Context\n├── Selective Spec Context (Requirements + Design only)\n├── Specific Task Details\n└── Clear instruction: \"Do NOT reload context\"\n```\n\nThis approach **eliminates redundant loading** while ensuring each agent has exactly the context it needs.\n\n---\n\n## 🛟 Troubleshooting\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Common Issues\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n**❓ \"Command not found\"**\n```bash\n# Install globally first\nnpm install -g @pimzino\u002Fclaude-code-spec-workflow\n\n# Then use the command\nclaude-code-spec-workflow\n```\n\n**❓ \"Claude Code not detected\"**\n```bash\nnpm install -g @anthropic-ai\u002Fclaude-code\n```\n\n**❓ \"Permission errors\"**\n```bash\nclaude-code-spec-workflow --project ~\u002Fmy-project\n```\n\n\u003C\u002Fdetails>\n\n---\n\n## 📋 Requirements\n\n- **Node.js** 16.0.0+\n- **Claude Code** installed\n- Any project directory\n\n---\n\n## 🔗 Links\n\n- **[Full Documentation](https:\u002F\u002Fgithub.com\u002Fpimzino\u002Fclaude-code-spec-workflow#readme)**\n- **[Claude Code Docs](https:\u002F\u002Fdocs.anthropic.com\u002Fclaude-code)**\n- **[Report Issues](https:\u002F\u002Fgithub.com\u002Fpimzino\u002Fclaude-code-spec-workflow\u002Fissues)**\n\n---\n\n## 📄 License & Credits\n\n**MIT License** - [LICENSE](LICENSE)\n\n**Made with ❤️ by [Pimzino](https:\u002F\u002Fgithub.com\u002Fpimzino)**\n\n**Special Thanks:**\n- @pimzino - Initial setup\n- @boundless-oss - Steering documents\n- @mquinnv - Dashboard feature\n\n**Powered by:** [Claude Code](https:\u002F\u002Fdocs.anthropic.com\u002Fclaude-code) • [Mermaid](https:\u002F\u002Fmermaid.js.org\u002F) • [TypeScript](https:\u002F\u002Fwww.typescriptlang.org\u002F)","# Claude 代码规范工作流\n\n> **⚠️ 重要通知：** 开发重点已转移至该工作流系统的 **MCP（模型上下文协议）版本**。MCP 版本提供了增强功能、实时仪表板以及更广泛的 AI 工具兼容性。\n> \n> **🚀 [查看新的规范工作流 MCP →](https:\u002F\u002Fgithub.com\u002FPimzino\u002Fspec-workflow-mcp)**\n>\n> 此 Claude 代码专用版本仍供现有用户使用，但更新将有限。\n\n[![npm version](https:\u002F\u002Fbadge.fury.io\u002Fjs\u002F@pimzino%2Fclaude-code-spec-workflow.svg?cacheSeconds=300)](https:\u002F\u002Fbadge.fury.io\u002Fjs\u002F@pimzino%2Fclaude-code-spec-workflow)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg)](https:\u002F\u002Fopensource.org\u002Flicenses\u002FMIT)\n\n**针对 Claude 代码的自动化工作流，具备智能任务执行能力。**\n\n通过结构化的工作流彻底变革您的开发流程：针对新功能采用 **需求 → 设计 → 任务 → 实现** 流程；针对 Bug 修复则采用简化的 **报告 → 分析 → 修复 → 验证** 流程。\n\n## ☕ 支持本项目\n\n\u003Ca href=\"https:\u002F\u002Fbuymeacoffee.com\u002FPimzino\" target=\"_blank\">\u003Cimg src=\"https:\u002F\u002Fcdn.buymeacoffee.com\u002Fbuttons\u002Fv2\u002Fdefault-yellow.png\" alt=\"Buy Me A Coffee\" style=\"height: 60px !important;width: 217px !important;\" >\u003C\u002Fa>\n\n---\n\n## 📦 安装\n\n1. 全局安装工作流工具\n```bash\nnpm i -g @pimzino\u002Fclaude-code-spec-workflow\n```\n2. 在您的项目目录中运行设置命令\n```bash\nclaude-code-spec-workflow\n```\n**这样就完成了，您可以开始使用了！**\n---\n\n## ✨ 您将获得的内容\n\n- **📁 完整的 .claude\u002F 目录结构** - 所有文件和子目录\n- **📝 10 条斜杠命令** - 5 条用于规范工作流，5 条用于 Bug 修复工作流\n- **🎯 智能任务执行** - 自动化实现\n- **🤖 4 个专用代理** - 增强自动化能力\n- **📊 实时仪表板** - 可视化监控进度\n- **🔧 自动生成的命令** - 每项任务对应一条命令\n- **📋 文档模板** - 专业规范文档\n- **⚙️ 项目指导** - 持久的上下文与标准\n- **⚡ 智能优化** - 智能上下文共享与缓存\n\n---\n\n## 🔄 工作流概览\n\n### 📊 **规范工作流**（新功能）\n\n**只需一条命令即可完成自动化：**\n\n```bash\n\u002Fspec-create feature-name \"Description\"\n```\n\n**具体流程：**\n1. **需求** → 用户故事 + 接受准则\n2. **设计** → 技术架构 + 图表\n3. **任务** → 细粒度、适合代理执行的任务分解\n4. **命令** → 自动生成的任务命令（可选）\n\n**执行任务：**\n```bash\n# 手动控制\n\u002Fspec-execute 1 feature-name\n\u002Ffeature-name-task-1        # 自动生成\n```\n\n### 🐛 **Bug 修复工作流**（快速修复）\n\n```bash\n\u002Fbug-create issue-name \"Description\"  # 记录 Bug\n\u002Fbug-analyze                          # 查找根本原因\n\u002Fbug-fix                             # 实施解决方案\n\u002Fbug-verify                          # 确认修复结果\n```\n\n### 🎯 **项目指导设置**（项目上下文）\n\n```bash\n\u002Fspec-steering-setup  # 创建 product.md、tech.md、structure.md\n```\n\n---\n\n## 🛠️ 命令参考\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>📊 规范工作流命令\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n| 命令 | 用途 |\n|---------|---------|\n| `\u002Fspec-steering-setup` | 创建项目上下文文档 |\n| `\u002Fspec-create \u003Cname>` | 完成规范工作流 |\n| `\u002Fspec-execute \u003Ctask-id>` | 手动执行任务 |\n| `\u002F\u003Cname>-task-\u003Cid>` | 自动生成的任务命令 |\n| `\u002Fspec-status` | 显示进度 |\n| `\u002Fspec-list` | 列出所有规范 |\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🐛 Bug 修复命令\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n| 命令 | 用途 |\n|---------|---------|\n| `\u002Fbug-create \u003Cname>` | 以结构化格式记录 Bug |\n| `\u002Fbug-analyze` | 调查根本原因 |\n| `\u002Fbug-fix` | 实施针对性解决方案 |\n| `\u002Fbug-verify` | 验证修复效果 |\n| `\u002Fbug-status` | 显示 Bug 修复进度 |\n\n\u003C\u002Fdetails>\n\n---\n\n## 🎯 核心特性\n\n### 🤖 **智能任务执行**\n- **简化**的任务实施流程\n- **上下文感知**的执行，拥有完整的规范上下文\n- **基于代理**的任务执行，由 spec-task-executor 完成\n\n### 🧠 **专用代理**（可选）\n4 个 AI 代理用于增强自动化能力：\n\n**核心工作流：** `spec-task-executor`、`spec-requirements-validator`、`spec-design-validator`、`spec-task-validator`\n\n\n> **注意：** 代理是可选的——所有功能均可在内置回退机制下正常运行。\n\n### ⚡ **全面的上下文优化**（全新！）\n- **通用上下文共享** - 指导文档、规范文档及模板文档均经过优化\n- **减少 60-80% 的 token 数量** - 消除了所有文档类型之间重复获取内容的问题\n- **三重优化命令** - `get-steering-context`、`get-spec-context` 和 `get-template-context`\n- **智能文档处理** - Bug 文档直接读取（无冗余），模板文档批量加载（高冗余）\n- **性能提升** - 缓存上下文后，所有工作流中的代理执行速度更快\n- **自动回退** - 当优化不可用时，仍可通过单独的 `get-content` 保持可靠性\n- **会话级缓存** - 智能检测文件变化并失效缓存\n\n### 📊 **实时仪表板**\n```bash\nnpx -p @pimzino\u002Fclaude-code-spec-workflow claude-spec-dashboard\n```\n- 实时进度跟踪\n- WebSocket 更新\n- Git 集成\n- 使用 Tailwind CSS 构建的现代化 UI\n\n---\n\n### 🔗 仪表板隧道（全新！）\n\n通过临时 HTTPS URL，您可以安全地与外部利益相关者共享仪表板：\n\n```bash\n# 启动带隧道的仪表板\nnpx -p @pimzino\u002Fclaude-code-spec-workflow claude-spec-dashboard --tunnel\n\n# 带密码保护\nnpx -p @pimzino\u002Fclaude-code-spec-workflow claude-spec-dashboard --tunnel --tunnel-password mySecret123\n\n# 选择特定提供商\nnpx -p @pimzino\u002Fclaude-code-spec-workflow claude-spec-dashboard --tunnel --tunnel-provider cloudflare\n```\n\n**隧道特点：**\n- **🔒 安全的 HTTPS URL** - 可与经理、客户或远程团队成员共享仪表板\n- **👁️ 只读访问权限** - 外部查看者无法修改任何项目数据\n- **🔑 可选密码** - 可通过密码认证保护访问权限\n- **🌐 多种提供商** - 自动在 Cloudflare 和 ngrok 之间切换\n- **📊 使用情况分析** - 跟踪谁在何时访问了您的仪表板\n- **⏰ 自动过期** - 当您停止仪表板时，隧道会自动关闭\n- **🚀 无需配置** - 内置提供商即可开箱即用\n\n## 📊 命令行选项\n\n### 设置命令\n```bash\n# 在当前目录设置\nnpx @pimzino\u002Fclaude-code-spec-workflow\n\n# 在指定目录设置\nnpx @pimzino\u002Fclaude-code-spec-workflow --project \u002Fpath\u002Fto\u002Fproject\n\n# 强制覆盖现有文件\nnpx @pimzino\u002Fclaude-code-spec-workflow --force\n\n# 跳过确认提示\nnpx @pimzino\u002Fclaude-code-spec-workflow --yes\n\n# 测试设置\nnpx @pimzino\u002Fclaude-code-spec-workflow test\n```\n\n### 仪表板命令\n```bash\n# 基本仪表板\nnpx -p @pimzino\u002Fclaude-code-spec-workflow claude-spec-dashboard\n\n# 带隧道的仪表板（可对外共享）\nnpx -p @pimzino\u002Fclaude-code-spec-workflow claude-spec-dashboard --tunnel\n\n# 完整隧道配置\nnpx -p @pimzino\u002Fclaude-code-spec-workflow claude-spec-dashboard \\\n  --tunnel \\\n  --tunnel-password mySecret123 \\\n  --tunnel-provider cloudflare \\\n  --port 3000 \\\n  --open\n```\n\n## 🎯 指导文档（新！）\n\n指导文档提供了持久的项目上下文，用于指导所有规范的开发：\n\n### **产品文档** (`product.md`)\n- 产品愿景和目的\n- 目标用户及其需求\n- 关键功能和目标\n- 成功指标\n\n### **技术文档** (`tech.md`)\n- 技术栈和框架\n- 开发工具和实践\n- 技术约束和要求\n- 第三方集成\n\n### **结构文档** (`structure.md`)\n- 文件组织模式\n- 命名规范\n- 导入模式\n- 代码组织原则\n\n运行 `\u002Fspec-steering-setup` 来创建这些文档。Claude 将分析你的项目并帮助你定义这些标准。\n\n## 🎨 功能\n\n### ✅ **零配置**\n- 适用于任何项目，开箱即用\n- 自动检测项目类型（Node.js、Python、Java 等）\n- 验证 Claude Code 是否已安装\n\n### ✅ **交互式设置**\n- 美观的 CLI 界面，带有进度指示器\n- 安全确认提示\n- 有用的错误信息和指导\n\n### ✅ **智能文件管理**\n- 每个命令文件中都包含完整的流程说明\n- 创建全面的目录结构\n- 包含所有必要的模板和配置文件\n\n### ✅ **专业品质**\n- **完全使用 TypeScript 实现**，具有严格的类型检查\n- **前端已转换为 TypeScript**，以增强仪表盘开发\n- **95% 以上的类型覆盖率**，无隐式 any 类型\n- **现代构建管道**，支持 esbuild 打包和源映射\n- 全面的错误处理\n- 遵循 npm 最佳实践\n\n### ✅ **指导文档集成**\n- 在所有规范中保持持久的项目上下文\n- 自动与项目标准对齐\n- 一致的代码生成\n- 减少重复解释的需求\n\n### ✅ **TypeScript 仪表盘前端**\n- **类型安全的前端代码**，具有全面的接口\n- **实时 WebSocket 通信**，支持类型化的消息处理\n- **Petite-vue 集成**，带有自定义类型定义\n- **构建管道**，支持开发和生产版本打包\n- **严格的空值检查** 和现代 TypeScript 模式\n- **JSDoc 文档**，为所有导出函数提供说明\n\n## 🏗️ 设置后的项目结构\n\n```\nyour-project\u002F\n├── .claude\u002F\n│   ├── commands\u002F           # 14 个斜杠命令 + 自动生成\n│   ├── steering\u002F          # product.md、tech.md、structure.md\n│   ├── templates\u002F         # 文档模板\n│   ├── specs\u002F            # 生成的规范\n│   ├── bugs\u002F             # 错误修复流程\n│   └── agents\u002F           # AI 代理（默认启用）\n```\n\n## 🧪 测试\n\n该包包含一个内置的测试命令：\n\n```bash\n# 在临时目录中测试设置\nnpx @pimzino\u002Fclaude-code-spec-workflow test\n```\n\n## 📋 要求\n\n- **Node.js** 16.0.0 或更高版本\n- 已安装并配置好 Claude Code\n- 任意项目目录\n\n## 🔧 故障排除\n\n### 常见问题\n\n**❓ 使用 NPX 后找不到命令**\n```bash\n# 确保使用正确的包名称\nnpx @pimzino\u002Fclaude-code-spec-workflow\n```\n\n**❓ 设置失败并出现权限错误**\n```bash\n# 尝试使用不同的目录权限\nnpx @pimzino\u002Fclaude-code-spec-workflow --project ~\u002Fmy-project\n```\n\n**❓ 未检测到 Claude Code**\n```bash\n# 首先安装 Claude Code\nnpm install -g @anthropic-ai\u002Fclaude-code\n```\n\n### 调试信息\n\n```bash\n# 显示详细输出\nDEBUG=* npx @pimzino\u002Fclaude-code-spec-workflow\n\n# 检查包版本\nnpx @pimzino\u002Fclaude-code-spec-workflow --version\n```\n\n## 🌟 示例\n\n### 基本用法\n```bash\ncd my-awesome-project\nnpx @pimzino\u002Fclaude-code-spec-workflow\nclaude\n# 输入：\u002Fspec-create user-dashboard \"用户资料管理\"\n```\n\n### 进阶用法\n```bash\n# 设置多个项目\nfor dir in project1 project2 project3; do\n  npx @pimzino\u002Fclaude-code-spec-workflow --project $dir --yes\ndone\n```\n\n## 🔧 TypeScript 开发\n\n### 前端仪表盘开发\n\n仪表盘前端完全使用 TypeScript 实现，以增强类型安全性和开发者体验：\n\n#### 类型定义\n```typescript\n\u002F\u002F 核心仪表盘类型\ninterface Project {\n  path: string;\n  name: string;\n  level: number;\n  hasActiveSession: boolean;\n  specs: Spec[];\n  bugs: Bug[];\n  steeringStatus?: SteeringStatus;\n}\n\n\u002F\u002F 带有区分联合类型的 WebSocket 消息类型\ntype WebSocketMessage = \n  | { type: 'initial'; data: InitialData }\n  | { type: 'update'; data: UpdateData }\n  | { type: 'error'; data: ErrorData }\n  | { type: 'tunnel-status'; data: TunnelStatusData };\n```\n\n#### 构建命令\n```bash\n# TypeScript 编译和打包\nnpm run build:frontend:dev   # 构建开发版前端\nnpm run build:frontend:prod  # 构建生产版前端（压缩版）\nnpm run watch:frontend       # 监视模式，自动重新构建\nnpm run typecheck:frontend   # 仅进行类型检查（不输出）\nnpm run typecheck           # 检查后端和前端的类型\n\n# 开发工作流  \nnpm run dev:dashboard       # 启动仪表盘，支持热重载（前端 + 后端）\nnpm run dev:dashboard:backend-only  # 仅启动后端（用于前端调试）\n\n# 完整构建流程\nnpm run build              # 完整构建：TypeScript + 前端 + 静态文件\nnpm run lint               # 使用自动修复功能检查 TypeScript 文件\nnpm run format             # 使用 Prettier 格式化代码\n```\n\n#### 类型安全特性\n- **严格 TypeScript 配置**，包含空值检查\n- **运行时类型验证**，通过类型保护实现\n- **WebSocket 消息类型定义**，用于实时更新\n- **状态管理类型**，适用于响应式 UI 组件\n- **错误处理类型**，采用 Result\u003CT> 模式\n- **Petite-vue 集成**，提供自定义类型定义\n\n#### 类型使用示例\n\n```typescript\n\u002F\u002F 导入仪表板类型\nimport type { Project, WebSocketMessage, AppState } from '.\u002Fdashboard.types';\n\n\u002F\u002F 类型安全的项目处理\nfunction selectProject(project: Project): void {\n  console.log(`选择的项目：${project.name} (${project.specs.length} 个规格)`);\n  \n  \u002F\u002F 安全的可选链属性访问\n  const steeringCount = project.steeringStatus?.totalDocs ?? 0;\n  if (steeringCount > 0) {\n    console.log(`转向文档数：${steeringCount}`);\n  }\n}\n\n\u002F\u002F 使用区分联合类型的 WebSocket 消息处理\nfunction handleMessage(message: WebSocketMessage): void {\n  switch (message.type) {\n    case 'initial':\n      \u002F\u002F TypeScript 知道 data 是 InitialData 类型\n      console.log(`加载了 ${message.data.projects.length} 个项目`);\n      break;\n    case 'update':\n      \u002F\u002F TypeScript 知道 data 是 UpdateData 类型\n      console.log(`更新了项目：${message.data.projectPath}`);\n      break;\n    case 'error':\n      \u002F\u002F TypeScript 知道 data 是 ErrorData 类型\n      console.error(`错误：${message.data.message}`);\n      break;\n  }\n}\n\n\u002F\u002F 运行时验证的类型保护函数\nfunction isValidProject(obj: unknown): obj is Project {\n  return (\n    typeof obj === 'object' &&\n    obj !== null &&\n    'path' in obj &&\n    'name' in obj &&\n    'specs' in obj &&\n    Array.isArray((obj as Project).specs)\n  );\n}\n\n\u002F\u002F 用于错误处理的 Result 类型\ntype Result\u003CT, E = Error> = \n  | { success: true; data: T }\n  | { success: false; error: E };\n\nfunction parseProjectData(data: unknown): Result\u003CProject> {\n  if (isValidProject(data)) {\n    return { success: true, data };\n  }\n  return { success: false, error: new Error('无效的项目数据') };\n}\n```\n\n#### 开发指南\n- 对所有导出函数进行 **JSDoc 文档注释**\n- 维持 **95% 以上的类型覆盖率**（无隐式 any 类型）\n- 使用 **现代 TypeScript 模式**（可选链、空值合并等）\n- 优先使用 **类型保护** 而不是类型断言\n- 使用 **接口定义对象结构**，用联合类型表示区分联合\n- 采用 **Result\u003CT> 模式** 处理错误\n- 对外部数据进行 **运行时类型验证**\n\n## 📚 文档\n\n- **完整文档** [https:\u002F\u002Fgithub.com\u002Fpimzino\u002Fclaude-code-spec-workflow#readme](https:\u002F\u002Fgithub.com\u002Fpimzino\u002Fclaude-code-spec-workflow#readme)\n- **隧道功能指南** [.\u002Fdocs\u002Ftunnel-feature.md](.\u002Fdocs\u002Ftunnel-feature.md) - 隧道功能的全面文档\n- **隧道示例** [.\u002Fexamples\u002Ftunnel\u002F](.\u002Fexamples\u002Ftunnel\u002F) - 可直接使用的隧道脚本\n- **Claude Code 文档** [https:\u002F\u002Fdocs.anthropic.com\u002Fclaude-code](https:\u002F\u002Fdocs.anthropic.com\u002Fclaude-code)\n- **TypeScript API 参考** [.\u002Fdocs\u002Ftypescript-api.md](.\u002Fdocs\u002Ftypescript-api.md) - 根据 JSDoc 注释生成\n\n## 🤝 贡献\n\n欢迎贡献！请参阅我们的 [贡献指南](https:\u002F\u002Fgithub.com\u002Fpimzino\u002Fclaude-code-spec-workflow\u002Fblob\u002Fmain\u002FCONTRIBUTING.md)。\n\n## 📄 许可证\n\nMIT 许可证 - 详情请参阅 [LICENSE](https:\u002F\u002Fgithub.com\u002Fpimzino\u002Fclaude-code-spec-workflow\u002Fblob\u002Fmain\u002FLICENSE)。\n\n## 🏷️ 更改记录\n\n版本历史请查看 [CHANGELOG.md](https:\u002F\u002Fgithub.com\u002Fpimzino\u002Fclaude-code-spec-workflow\u002Fblob\u002Fmain\u002FCHANGELOG.md)。\n\n---\n\n## 🚦 何时使用什么\n\n| 场景 | 推荐方法 |\n|----------|---------------------|\n| **新功能，定义明确** | `\u002Fspec-execute` 或单个任务命令 |\n| **复杂或实验性功能** | `\u002Fspec-execute`（手动控制） |\n| **现有代码中的 bug** | Bug 工作流（`\u002Fbug-create` → `\u002Fbug-verify`） |\n| **学习代码库** | 使用单个命令手动执行 |\n| **生产部署** | 使用完整的规范工作流，并进行完成审核 |\n\n---\n\n## 🚀 安装与设置\n\n### **安装**\n```bash\n# 全局安装（推荐）\nnpm install -g @pimzino\u002Fclaude-code-spec-workflow\n\n# 验证安装\nclaude-code-spec-workflow --version\n```\n\n### **设置选项**\n```bash\n# 基本设置\nclaude-code-spec-workflow\n\n# 高级选项\nclaude-code-spec-workflow --project \u002Fpath --force --yes\n```\n\n**在设置过程中，您可以选择：**\n- ✅ **启用代理？** 增强自动化功能 vs 更简单的设置\n- ✅ **项目分析** 自动检测框架和模式\n\n---\n\n## 📚 示例\n**建议：使用 Claude Opus 4 生成规范文档 '\u002Fspec-create'，然后使用 Claude Sonnet 4 进行实现，即 '\u002Fspec-execute' 或 '\u002F{spec-name}-task-\u003Cid>'。**\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>基本工作流示例\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# 1. 全局安装（一次）\nnpm install -g @pimzino\u002Fclaude-code-spec-workflow\n\n# 2. 设置项目（一次）\ncd my-project\nclaude-code-spec-workflow\n\n# 3. 创建指导文档（推荐）\nclaude\n\u002Fspec-steering-setup\n\n# 4. 创建功能规范\n\u002Fspec-create user-authentication \"安全登录系统\"\n\n# 5. 执行任务\n\u002Fspec-execute 1 user-authentication\n\n# 6. 监控进度\n\u002Fspec-status user-authentication\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Bug 修复示例\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n\u002Fbug-create login-timeout \"用户登录后过快被登出\"\n\u002Fbug-analyze\n\u002Fbug-fix\n\u002Fbug-verify\n```\n\n\u003C\u002Fdetails>\n\n---\n\n## ⚡ 上下文优化命令\n\n该包包含针对各类文档高效加载的优化命令：\n\n### **get-steering-context**\n一次性加载所有指导文档以共享上下文：\n```bash\nclaude-code-spec-workflow get-steering-context\n```\n**输出**：格式化的 Markdown，包含所有指导文档（product.md、tech.md、structure.md）\n\n### **get-spec-context**\n一次性加载所有规范文档以共享上下文：\n```bash\nclaude-code-spec-workflow get-spec-context feature-name\n```\n**输出**：格式化的 Markdown，包含所有规范文档（requirements.md、design.md、tasks.md）\n\n### **get-template-context**\n按类别加载模板以共享上下文：\n```bash\n# 加载所有模板\nclaude-code-spec-workflow get-template-context\n\n# 加载特定类别的模板\nclaude-code-spec-workflow get-template-context spec    # 规范模板\nclaude-code-spec-workflow get-template-context bug     # Bug 模板\nclaude-code-spec-workflow get-template-context steering # 指导模板\n```\n**输出**：格式化的 Markdown，包含请求的模板\n\n### **智能文档处理**\n- **高冗余文档**（指导文档、规范、模板）：使用优化的批量加载\n- **低冗余文档**（Bug 报告）：直接读取文件以简化操作\n- **选择性委派**：主代理加载完整上下文，但只将相关部分传递给子代理\n- **单个文件**：对于特殊情况，继续使用 `get-content` 命令\n\n### **优势**\n- 与单独加载文件相比，**减少60%-80%的令牌使用量**\n- 在所有工作流中利用缓存上下文实现**更快的执行速度**\n- 在需要时自动回退到单独的 `get-content` 操作\n- 基于会话的缓存机制，并具备智能的文件变更检测功能\n\n### **层次化上下文管理**\n系统采用了一种**层次化的上下文管理策略**，以实现最高效率：\n\n**主代理**（如 `\u002Fspec-execute`、`\u002Fspec-create` 等命令）：\n- 在开始时通过优化后的命令**一次性加载全部上下文**\n- 存储完整的上下文，用于任务协调和决策制定\n- 向子代理分发选择性上下文，无需重复加载\n\n**子代理**（如 `spec-task-executor` 等代理）：\n- **优先级1**：使用任务指令中提供的上下文（指导信息、规格说明、任务详情）\n- **优先级2**：若未提供上述内容，则回退至加载上下文\n- **绝不重复加载**已由主代理提供的上下文\n\n**上下文分发模式**：\n```\n主代理加载：指导信息 + 完整规格 + 任务详情\n↓ 分配给子代理的内容：\n├── 完整的指导信息上下文\n├── 选择性的规格上下文（仅包含需求和设计部分）\n├── 具体的任务详情\n└── 明确指示：“请勿再次加载上下文”\n```\n\n这种方法**消除了冗余加载**，同时确保每个代理都拥有其所需的精确上下文。\n\n---\n\n## 🛟 故障排除\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>常见问题\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n**❓ “命令未找到”**\n```bash\n# 首先全局安装\nnpm install -g @pimzino\u002Fclaude-code-spec-workflow\n\n# 然后使用该命令\nclaude-code-spec-workflow\n```\n\n**❓ “未检测到 Claude Code”**\n```bash\nnpm install -g @anthropic-ai\u002Fclaude-code\n```\n\n**❓ “权限错误”**\n```bash\nclaude-code-spec-workflow --project ~\u002Fmy-project\n```\n\n\u003C\u002Fdetails>\n\n---\n\n## 📋 系统要求\n\n- **Node.js** 16.0.0及以上版本\n- 已安装 **Claude Code**\n- 任意项目目录\n\n---\n\n## 🔗 链接\n\n- **[完整文档](https:\u002F\u002Fgithub.com\u002Fpimzino\u002Fclaude-code-spec-workflow#readme)**\n- **[Claude Code 文档](https:\u002F\u002Fdocs.anthropic.com\u002Fclaude-code)**\n- **[提交问题](https:\u002F\u002Fgithub.com\u002Fpimzino\u002Fclaude-code-spec-workflow\u002Fissues)**\n\n---\n\n## 📄 许可证与致谢\n\n**MIT 许可证** - [LICENSE](LICENSE)\n\n**由 [Pimzino](https:\u002F\u002Fgithub.com\u002Fpimzino) 用心打造**\n\n**特别感谢：**\n- @pimzino - 初始搭建\n- @boundless-oss - 指导文档\n- @mquinnv - 仪表盘功能\n\n**技术支持：** [Claude Code](https:\u002F\u002Fdocs.anthropic.com\u002Fclaude-code) • [Mermaid](https:\u002F\u002Fmermaid.js.org\u002F) • [TypeScript](https:\u002F\u002Fwww.typescriptlang.org\u002F)","# claude-code-spec-workflow 快速上手指南\n\n## 环境准备\n\n在开始之前，请确保您的开发环境满足以下要求：\n\n*   **Node.js**: 版本 16.0.0 或更高。\n*   **Claude Code**: 必须已安装并配置好全局命令。\n    ```bash\n    npm install -g @anthropic-ai\u002Fclaude-code\n    ```\n*   **项目目录**: 准备好一个需要开发的现有项目文件夹。\n\n> 💡 **国内加速提示**：如果 npm 下载缓慢，建议临时切换至国内镜像源（如淘宝镜像）：\n> ```bash\n> npm config set registry https:\u002F\u002Fregistry.npmmirror.com\n> ```\n\n## 安装步骤\n\n只需两步即可完成全局安装与项目初始化：\n\n1.  **全局安装工具包**\n    在终端执行以下命令安装工作流系统：\n    ```bash\n    npm i -g @pimzino\u002Fclaude-code-spec-workflow\n    ```\n\n2.  **初始化项目**\n    进入您的项目根目录，运行设置命令。该命令会自动创建 `.claude\u002F` 目录结构、生成斜杠命令文件及文档模板：\n    ```bash\n    claude-code-spec-workflow\n    ```\n    *按提示确认即可，若需跳过确认可添加 `--yes` 参数。*\n\n## 基本使用\n\n安装完成后，您可以在项目中启动 `claude` 交互界面，直接使用内置的自动化工作流命令。\n\n### 1. 启动交互模式\n在项目目录下输入：\n```bash\nclaude\n```\n\n### 2. 新功能开发流程 (Spec Workflow)\n使用一条命令即可自动完成从需求分析、架构设计到任务拆解的全过程：\n```bash\n\u002Fspec-create user-dashboard \"实现用户个人资料管理功能\"\n```\n*执行后，系统将生成需求文档、技术设计图及原子化任务列表。*\n\n**执行具体任务：**\n您可以手动执行特定任务，或使用自动生成的命令：\n```bash\n\u002Fspec-execute 1 user-dashboard\n# 或直接使用自动生成的命令\n\u002Fuser-dashboard-task-1\n```\n\n### 3. 缺陷修复流程 (Bug Fix Workflow)\n针对 Bug 修复提供标准化的四步闭环：\n```bash\n\u002Fbug-create login-error \"用户登录时出现 500 错误\"  # 记录问题\n\u002Fbug-analyze                                      # 分析根本原因\n\u002Fbug-fix                                          # 实施修复方案\n\u002Fbug-verify                                       # 验证修复结果\n```\n\n### 4. 项目上下文引导 (可选)\n首次使用时，建议运行此命令让 AI 分析项目并生成产品、技术及结构规范文档，以提升后续代码生成的一致性：\n```bash\n\u002Fspec-steering-setup\n```\n\n### 5. 可视化监控 (Dashboard)\n如需在浏览器中实时查看任务进度和状态，可在另一终端窗口运行：\n```bash\nnpx -p @pimzino\u002Fclaude-code-spec-workflow claude-spec-dashboard\n```","某电商初创团队的后端工程师需要在两天内紧急上线“用户积分抵扣订单”功能，同时修复一个导致库存扣减错误的严重 Bug。\n\n### 没有 claude-code-spec-workflow 时\n- **需求落地混乱**：开发者需在对话框中反复粘贴需求描述，AI 输出的代码往往缺乏统一的设计架构，导致后续重构成本高。\n- **任务拆解断层**：从想法到代码的中间步骤依赖人工手动拆分，容易遗漏边界条件或测试用例，造成逻辑漏洞。\n- **修 Bug 效率低下**：面对复杂的库存问题，需要在多轮对话中反复陈述上下文，AI 难以精准定位根因，经常“头痛医头”。\n- **进度不可视**：多个并行任务的状态散落在聊天记录中，缺乏全局视图，团队协作时难以同步当前开发进度。\n\n### 使用 claude-code-spec-workflow 后\n- **全流程自动化**：只需运行 `\u002Fspec-create`，工具自动按“需求→设计→任务→实现”生成完整技术文档和可执行代码，确保架构一致性。\n- **原子化任务执行**：系统智能将大功能拆解为独立任务，并通过自动生成的命令（如 `\u002Ffeature-task-1`）逐个击破，显著降低逻辑遗漏风险。\n- **标准化故障修复**：利用 `\u002Fbug-create` 到 `\u002Fbug-verify` 的标准工作流，强制 AI 先分析根因再修复并验证，彻底解决库存扣减异常。\n- **实时进度看板**：通过内置仪表盘和状态命令，团队成员可清晰看到每个规格和 Bug 的实时进展，协作透明度大幅提升。\n\nclaude-code-spec-workflow 将原本碎片化的 AI 辅助编程转变为结构化、可追踪的工程级开发流程，让复杂功能交付与紧急故障修复变得高效且可控。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FPimzino_claude-code-spec-workflow_4ba29be5.png","Pimzino","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002FPimzino_f5de70b9.png",null,"jose@freitasuk.com","https:\u002F\u002Fgithub.com\u002FPimzino",[80,84,88,92],{"name":81,"color":82,"percentage":83},"TypeScript","#3178c6",81.7,{"name":85,"color":86,"percentage":87},"HTML","#e34c26",11.2,{"name":89,"color":90,"percentage":91},"JavaScript","#f1e05a",7,{"name":93,"color":94,"percentage":95},"Rust","#dea584",0.1,3661,258,"2026-04-17T09:40:17","MIT","Linux, macOS, Windows","未说明",{"notes":103,"python":101,"dependencies":104},"该工具是基于 Node.js 的 CLI 工具，非 Python AI 模型。主要运行环境要求为：1. 安装 Node.js 16.0.0 或更高版本；2. 全局安装并配置 Claude Code (@anthropic-ai\u002Fclaude-code)；3. 通过 npm 安装本工作流包。无需 GPU 支持，具体内存需求取决于项目规模及 Claude Code 的运行负载。",[105,106],"Node.js>=16.0.0","@anthropic-ai\u002Fclaude-code",[35,13,45],"2026-03-27T02:49:30.150509","2026-04-18T02:20:23.730602",[],[]]