npm package: @happytools/ai-cowork
Description: Cross-stack AI development workflow system - Standards, workflows, and skills for AI-assisted development
Author: AdemKao
Latest version: 0.2.2

<h1 align="center">🤖 ai-cowork</h1>

<p align="center">
  <strong>可攜式 AI 開發工作流系統</strong><br>
  <em>將 AI 編程助手無縫整合到任何技術棧的開發流程中</em>
</p>

<p align="center">
  <a href="https://opensource.org/licenses/MIT">
    <img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="License: MIT">
  </a>
  <a href="https://opencode.ai">
    <img src="https://img.shields.io/badge/OpenCode-ready-purple?style=flat-square" alt="OpenCode">
  </a>
  <a href="https://claude.ai">
    <img src="https://img.shields.io/badge/Claude%20Code-ready-green?style=flat-square" alt="Claude Code">
  </a>
  <a href="https://cursor.sh">
    <img src="https://img.shields.io/badge/Cursor-ready-blue?style=flat-square" alt="Cursor">
  </a>
</p>

<p align="center">
  <a href="#安裝">安裝</a> •
  <a href="#快速開始">快速開始</a> •
  <a href="#功能特色">功能特色</a> •
  <a href="#cli-指令">CLI</a> •
  <a href="#貢獻">貢獻</a>
</p>

<p align="center">
  <a href="./README.md">English</a>
</p>

---

## 為什麼選擇 ai-cowork？

現代開發者每天都在使用 AI 編程助手，但面臨常見的挑戰：

- **AI 行為不一致** - 不同專案中 AI 的表現差異很大
- **上下文丟失** - 切換專案時需要重新解釋一切
- **重複提示** - 同樣的任務需要反覆說明
- **缺乏標準流程** - AI 輔助開發沒有統一的工作流

**ai-cowork** 提供一個**可攜式、標準化的 AI 工作流**，讓你的開發習慣跟隨你跨越專案和 AI 工具。

### 它提供：

- 🎯 **一致的 AI 上下文** - 你的編碼標準、模式和偏好跟隨每個專案
- 📚 **可重用的 Skills** - 預建的程式碼審查、除錯、重構等提示
- 🏗️ **技術棧模板** - 特定語言/框架的標準（React、Laravel、Node.js 等）
- 🔄 **AI 工具同步** - 一份配置，多個 AI 工具（OpenCode、Claude Code、Cursor）
- 🔧 **可擴展** - 為你的工作流創建自定義的 skills 和 stacks

非常適合跨多種技術棧工作的**自由工作者**、**顧問**和**團隊**。

## 功能特色

- ✅ **多技術棧支援** - React、Laravel、Node.js 等（Python、Go、Rust 即將推出）
- ✅ **AI 工具無關** - 適用於 OpenCode、Claude Code、Cursor
- ✅ **可攜帶工作流** - AI 開發模式跨專案通用
- ✅ **CLI 工具** - 輕鬆初始化和同步
- ✅ **可擴展** - 創建自定義的 stacks、skills 和 agents

## 安裝

### 使用 npm（推薦）

```bash
# 全域安裝
npm install -g @happytools/ai-cowork

# 或直接使用 npx
npx @happytools/ai-cowork init
```

### 使用 Bun

```bash
bun install -g ai-cowork
```

### 從原始碼安裝

```bash
git clone https://github.com/AdemKao/ai-cowork.git
cd ai-cowork/cli
npm install
npm link
```

## 快速開始

### 1. 初始化專案

```bash
# 進入您的專案目錄
cd your-project

# 使用 ai-cowork 初始化
ai-cowork init

# 或指定技術棧
ai-cowork init --stack react-typescript

# 跳過提示（使用預設值）
ai-cowork init --yes
```

這將創建一個 `.ai/` 目錄：

```
.ai/
├── context/          # 編碼標準和工作流
├── skills/           # 可重用的 AI skills
├── agents/           # 專門的 AI agents
└── stacks/           # 技術棧配置
```

### 2. 同步到您的 AI 工具

```bash
# 同步到 OpenCode
ai-cowork sync opencode

# 同步到 Claude Code
ai-cowork sync claude

# 同步到所有支援的工具
ai-cowork sync all
```

### 3. 開始使用 AI 編程

在 OpenCode 或 Claude Code 中使用您的 skills：

```
/code-review     # 執行程式碼審查 skill
/debug           # 執行除錯 skill
/commit          # 生成 commit 訊息
/notify          # 任務完成時發送通知
```

## CLI 指令

| 指令 | 說明 |
|------|------|
| `ai-cowork init` | 在專案中初始化 ai-cowork |
| `ai-cowork init --stack <name>` | 使用指定技術棧初始化 |
| `ai-cowork init --yes` | 使用預設值初始化（跳過提示） |
| `ai-cowork list` | 列出可用的 stacks、skills 和 agents |
| `ai-cowork add stack <name>` | 將技術棧添加到專案 |
| `ai-cowork add skill <name>` | 將 skill 添加到專案 |
| `ai-cowork sync opencode` | 生成 OpenCode 配置 |
| `ai-cowork sync claude` | 生成 Claude Code 配置 |
| `ai-cowork sync all` | 同步到所有 AI 工具 |
| `ai-cowork update` | 更新 ai-cowork |

## 可用的技術棧

| 技術棧 | 說明 | 狀態 |
|--------|------|------|
| `react-typescript` | React + TypeScript + Vite | ✅ 可用 |
| `php-laravel` | PHP + Laravel | ✅ 可用 |
| `node-express` | Node.js + Express | ✅ 可用 |
| `python-fastapi` | Python + FastAPI | 🔜 即將推出 |
| `go-fiber` | Go + Fiber | 🔜 即將推出 |
| `rust-axum` | Rust + Axum | 🔜 即將推出 |

## 可用的 Skills

| Skill | 說明 |
|-------|------|
| `code-review` | 完整的程式碼審查清單 |
| `debug` | 系統化的除錯方法 |
| `commit` | 生成約定式 commit 訊息 |
| `refactor` | 程式碼重構指南 |
| `documentation` | 文件生成 |
| `feature-implementation` | 功能規劃和實作 |
| `feature-decompose` | 將大型功能拆分為堆疊式 PR |
| `worktree-agent` | 使用 git worktrees 進行平行開發 |
| `notify` | 任務完成時發送通知（Telegram、桌面） |
| `ui-ux` | UI/UX 開發指南 |

## 專案結構

```
ai-cowork/
├── .ai/
│   ├── context/           # 核心標準和工作流
│   │   ├── core/
│   │   │   ├── standards/ # 程式碼品質、命名、安全性
│   │   │   └── workflows/ # BDD/TDD、程式碼審查、git
│   │   └── index.md       # Context 入口點
│   ├── skills/            # 可重用的 AI skills
│   ├── agents/            # 專門的 AI agents
│   ├── stacks/            # 技術棧模板
│   └── templates/         # 專案模板
├── cli/                   # CLI 工具原始碼
└── docs/                  # 文件
```

## AI 工具整合

### OpenCode

執行 `ai-cowork sync opencode` 後：

```
.opencode/
├── skill/          # OpenCode 格式的 Skills
├── agent/          # OpenCode 格式的 Agents
├── command/        # 自定義指令
└── plugin/         # Hooks 和 plugins
opencode.json       # 配置檔
AGENTS.md           # 專案上下文
```

### Claude Code

執行 `ai-cowork sync claude` 後：

```
.claude/
├── skills/         # Claude 格式的 Skills
└── commands/       # 自定義指令
CLAUDE.md           # 專案上下文
```

## 主要工作流

### 契約驅動開發

先設計契約，後實作：

1. **DBML** → 定義資料庫 schema
2. **OpenAPI** → 定義 API 規格
3. **實作** → 依照契約建構
4. **測試** → 驗證是否符合契約

### BDD/TDD

行為驅動和測試驅動開發：

- **前端**：元件測試 → 實作 → E2E 測試
- **後端**：功能規格 → 單元測試 → 實作 → 整合測試

### 堆疊式開發

對於大型功能，使用堆疊式 PR：

1. **分解** → 將功能拆分為可審查的小塊
2. **堆疊** → 創建相依的分支
3. **審查** → 獨立審查每個 PR
4. **合併** → 自底向上合併

## 運作原理

```
┌─────────────────────────────────────────────────────────────┐
│                       你的專案                               │
├─────────────────────────────────────────────────────────────┤
│  .ai/                                                       │
│  ├── context/        ← 編碼標準與工作流                      │
│  ├── skills/         ← 可重用的 AI 提示                      │
│  ├── agents/         ← 專門的 AI agents                     │
│  └── stacks/         ← 技術棧配置                           │
├─────────────────────────────────────────────────────────────┤
│                    ai-cowork sync                           │
├──────────────┬──────────────┬───────────────────────────────┤
│  .opencode/  │   .claude/   │        (其他工具)              │
│  OpenCode    │  Claude Code │       Cursor 等               │
└──────────────┴──────────────┴───────────────────────────────┘
```

1. **初始化** - `ai-cowork init` 創建包含標準和 skills 的 `.ai/`
2. **自定義** - 添加你的技術棧，調整標準以符合你的工作流
3. **同步** - `ai-cowork sync opencode` 生成工具專屬的配置
4. **開發** - 你的 AI 助手現在自動遵循你的標準

## 貢獻

歡迎貢獻！請參閱 [CONTRIBUTING.md](./CONTRIBUTING.md) 了解指南。

```bash
# Clone 專案
git clone https://github.com/AdemKao/ai-cowork.git
cd ai-cowork

# 安裝 CLI 依賴
cd cli && npm install

# 以開發模式執行
npm run dev -- --help
```

## 授權

[MIT](./LICENSE)

---

<p align="center">
  為使用 AI 編程的開發者用 ❤️ 製作
</p>