最佳實踐與社群經驗#

# 1. 在專案目錄開啟 Kiro
cd my-awesome-project
kiro .

# 2. 自動生成基礎 Steering 檔案
開啟 Kiro 面板 → 選擇 "Generate Steering Docs"
# 會自動生成 product.md、tech.md、structure.md

# 3. 新增專案特有的配置
cat > .kiro/steering/conventions.md << 'EOF'
# 開發規範

## 提交資訊規範
- feat: 新功能
- fix: Bug 修復
- docs: 文件變更
- style: 程式碼格式調整
- refactor: 重構
- test: 測試相關
- chore: 其他雜項

## 分支策略
- main: 生產環境
- develop: 開發環境
- feature/*: 新功能開發
- hotfix/*: 緊急修復

## 程式碼審查標準
- 測試透過
- 覆蓋率 80% 以上
- 無 ESLint 錯誤
- 文件已更新
EOF

# 4. 設定必備 Hooks
# 儲存時自動格式化
Hooks → + → 選擇 "儲存檔案時自動執行 ESLint 和 Prettier"

# 提交前安全掃描
Hooks → + → 選擇 "git commit 前掃描敏感資訊"

# 5. 配置 MCP 伺服器
cat > .kiro/settings/mcp.json << 'EOF'
{
  "mcpServers": {
    "web-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-bravesearch"],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    }
  }
}
EOF

# 6. 設定團隊共享的 .gitignore
cat >> .gitignore << 'EOF'
# Kiro 配置檔案
.kiro/settings.json
.kiro/cache/
.kiro/logs/

# 但以下內容需要共享
!.kiro/steering/
!.kiro/hooks/
!.kiro/specs/
EOF

# 第一步：安裝（5分鐘）
從 https://kiro.dev 下載並安裝

# 第二步：開啟第一個專案（10分鐘）
開啟現有專案，生成 Steering 檔案

# 第三步：與 AI 對話（無限可能）
"幫我提出改進這個專案的建議"

使用中文回覆，使用中文編寫程式碼註釋

# No Assumptions Policy - MANDATORY

## NEVER MAKE ASSUMPTIONS - STATE FACTS AND ASK

**This rule enforces the product constraint: "Avoid LLM hallucinations or assumptions"**

### REQUIRED BEHAVIOR:

When encountering missing dependencies, tools, or configuration:

❌ **DON'T DO:**

- Assume user preferences ("you might not want X because...")
- Dismiss issues as "expected"
- Make judgments about what user needs
- Skip mentioning installation options

✅ **DO THIS:**

- State the objective fact: "X is not installed"
- Provide the exact command: "Run: `command here`"
- Ask directly: "Would you like me to install X?"
- Let user decide

### EXAMPLES:

❌ **Bad (assumption):**
"Microsoft Edge isn't installed, but that's expected since it's similar to Chrome"

✅ **Good (facts + ask):**
"Microsoft Edge is not installed. To install it, run: `npx playwright install msedge`. Would you like me to install it?"

### WHY THIS MATTERS:

- Respects user autonomy
- Prevents missed opportunities
- Maintains transparency
- Follows product constraints
- Avoids LLM hallucinations

### CONTEXT FRAMEWORK - ALWAYS APPLY:

Before responding to ANY technical issue, ask yourself:

1. **What are we working on?** (Project/task context)
2. **Why does this issue matter?** (Impact on the goal)
3. **What can't be done without fixing it?** (Consequences)
4. **What's the solution?** (Clear action needed)

### RESPONSE TEMPLATE:

"For [PROJECT/TASK], [ISSUE] is preventing [SPECIFIC IMPACT]. To fix this, run: `command`. Would you like me to [ACTION]?"

## ADDITIONAL SCENARIOS - MANDATORY

### 1. MISSING FILE OR PATH ERRORS:

❌ **Bad (assumption):**
"config.json might not be necessary depending on your setup..."

✅ **Good (facts + ask):**
"config.json was not found in the working directory. To generate it, run: `npx create-config`. Should I create it for you?"

### 2. UNKNOWN USER INTENTS OR TOOLS:

❌ **Bad (assumption):**
"I'll assume you're using React since it's common..."

✅ **Good (clarify first):**
"You mentioned a UI component, but the framework isn't specified. Are you using React, Vue, or something else?"

### 3. AMBIGUITY HANDLING:

**RULE:** If project/task context is ambiguous, always ask for clarification before continuing with code or instructions.

### 4. NO SILENT FALLBACKS:

**RULE:** Never fallback silently. If using a default, state it clearly and ask if acceptable.

✅ **Better approach (ask before acting):**
"No color palette was provided. I can use 'default.dark' or wait for your input. Should I proceed with 'default.dark'?"

## USER AUTONOMY PRINCIPLE

**Core Philosophy:**

- Always ask before taking action on behalf of the user
- Never mask decisions behind automation or assumptions
- Build trust by exposing defaults, limits, and fallback logic
- Give users choice and control at every decision point

**REMEMBER: Always connect technical issues to project context and user goals.**

# CRITICAL DEV SERVER PROTOCOL - MANDATORY

## ABSOLUTE RULE: KILL BEFORE START

**NEVER START A DEV SERVER WITHOUT KILLING EXISTING ONES FIRST**

### Required Steps (NO EXCEPTIONS):

1. **ALWAYS check for existing processes:**

   ```bash
   ps aux | grep vite
   ```

2. **ALWAYS check for background jobs:**

   ```bash
   jobs
   ```

3. **ALWAYS check what's using the port:**

   ```bash
   lsof -i :5173
   ```

4. **KILL ALL processes found:**

   ```bash
   kill -9 [PID1] [PID2] [PID3]
   ```

5. **KILL ALL background jobs:**

   ```bash
   kill %1 %2 %3
   ```

6. **VERIFY port is free:**

   ```bash
   lsof -i :5173
   ```

   (Should return nothing)

7. **ONLY THEN start dev server:**
   ```bash
   npm run dev &
   ```

## WHY THIS MATTERS:

- Prevents port conflicts
- Keeps localhost:5173 consistent
- Prevents hanging processes
- Avoids user frustration
- Essential for development workflow

## FAILURE TO FOLLOW = USER FRUSTRATION

**I MUST NEVER START A DEV SERVER WITHOUT COMPLETING ALL KILL STEPS FIRST**

{
  // An extensive list of common CLI tools to pre-authorize.
  "kiroAgent.trustedCommands": [
    // --- General Shell & System ---
    "ls *",
    "dir *",
    "cd *",
    "mkdir *",
    "rm *",
    "rmdir *",
    "cp *",
    "copy *",
    "mv *",
    "move *",
    "echo *",
    "clear",
    "cls",
    "grep *",
    "find *",
    "ssh *",
    "\"C:\\Program *", // Trusts executables in Program Files paths

    // --- Git & Version Control ---
    "git *",

    // --- Package Managers ---
    "choco *",
    "scoop *",
    "winget *",
    "brew *",
    "apt *",
    "yum *",
    "pacman *",

    // --- DevOps, Containers & Cloud ---
    "docker *",
    "docker-compose *",
    "kubectl *",
    "helm *",
    "terraform *",
    "ansible *",
    "vagrant *",
    "aws *",
    "az *",
    "gcloud *",

    // --- Node.js / JavaScript / TypeScript Ecosystem ---
    "node *",
    "npm *",
    "npx *",
    "yarn *",
    "pnpm *",
    "bun *",
    "tsc *",
    "vite *",
    "webpack *",
    "next *",
    "eslint *",
    "prettier *",
    "jest *",
    "ng *",
    "vue *",
    "astro *",
    "svelte-kit *",
    "cypress *",

    // --- Python Ecosystem ---
    "python *",
    "python.exe *",
    "python3 *",
    "py *",
    "pip *",
    "pip3 *",
    "pipenv *",
    "poetry *",
    "uv *",
    "pytest *",
    "black *",
    "ruff *",
    "flask *",
    "django-admin *",
    "alembic *",
    "uvicorn *",

    // --- Database Clients ---
    "psql *",
    "mysql *",
    "sqlite3 *",

    // --- Go (Golang) ---
    "go *",

    // --- Rust ---
    "cargo *",
    "rustc *",

    // --- Java Ecosystem ---
    "java *",
    "javac *",
    "mvn *",
    "gradle *",

    // --- C / C++ / .NET Ecosystem ---
    "cl *",
    "gcc *",
    "g++ *",
    "make *",
    "cmake *",
    "msbuild *",
    "dotnet *",
    "nuget *",

    // --- PHP Ecosystem ---
    "php *",
    "composer *",
    "laravel *",
    "pest *",
    "phpcs *",

    // --- Ruby Ecosystem ---
    "ruby *",
    "bundle *",
    "rake *",
    "rails *"
  ]
}