universal-dev-standards 3.5.1-beta.1 → 3.5.1-beta.11

package/bundled/locales/zh-TW/ai/options/git-workflow/merge-commit.ai.yaml

@@ -0,0 +1,88 @@
+# 合併提交 - AI 優化選項
+# 父項: git-workflow
+
+id: merge-commit
+meta:
+  parent: git-workflow
+  version: "1.0.0"
+  description: 使用合併提交保留完整分支歷史
+  language: zh-TW
+
+best_for:
+  - 保留完整歷史
+  - 長期功能分支
+  - GitFlow 工作流程
+  - 稽核要求
+
+characteristics:
+  history: 非線性（有合併點）
+  commit_count: 保留所有提交
+  reversibility: 可還原整個合併
+  bisect_friendly: 非常友好
+
+rules:
+  - id: no-fast-forward
+    trigger: 合併分支時
+    instruction: 使用 --no-ff 建立合併提交
+    priority: required
+
+  - id: meaningful-merge-message
+    trigger: 建立合併提交時
+    instruction: 撰寫描述性的合併訊息
+    priority: recommended
+
+  - id: clean-branch-history
+    trigger: 合併前
+    instruction: 確保分支有乾淨、有意義的提交
+    priority: recommended
+
+workflow:
+  - step: 建立功能分支
+    commands:
+      - git checkout main
+      - git checkout -b feature/{功能名稱}
+
+  - step: 進行多次有意義的提交
+    commands:
+      - git commit -m "feat: add user model"
+      - git commit -m "feat: add user service"
+      - git commit -m "test: add user tests"
+
+  - step: 使用合併提交合併
+    commands:
+      - git checkout main
+      - git merge --no-ff feature/{功能名稱} -m "Merge feature/{功能名稱}"
+
+example:
+  result: |
+    *   merge123 Merge branch 'feature/oauth'
+    |\
+    | * abc1234 test: add OAuth tests
+    | * def5678 feat: add OAuth service
+    | * ghi9012 feat: add OAuth model
+    |/
+    * xyz7890 previous commit on main
+
+pros:
+  - 保留完整開發歷史
+  - 清楚的功能邊界
+  - 適合 git bisect 偵錯
+  - 簡單還原整個功能
+
+cons:
+  - 歷史可能變得複雜
+  - 較難閱讀線性流程
+  - 更多合併衝突可能性
+
+commands:
+  merge_no_ff: git merge --no-ff {branch}
+  revert_merge: git revert -m 1 {merge-commit}
+  view_history: git log --oneline --graph
+
+quick_reference:
+  options:
+    columns: [選項, 說明]
+    rows:
+      - ["--no-ff", 即使可快進也建立合併提交]
+      - ["-m", 指定合併訊息]
+      - ["--log", 在合併訊息中包含提交日誌]

package/bundled/locales/zh-TW/ai/options/git-workflow/rebase-ff.ai.yaml

@@ -0,0 +1,113 @@
+# 變基快進 - AI 優化選項
+# 父項: git-workflow
+
+id: rebase-ff
+meta:
+  parent: git-workflow
+  version: "1.0.0"
+  description: 變基然後快進合併以獲得線性歷史
+  language: zh-TW
+
+best_for:
+  - 完美線性歷史
+  - 主幹開發
+  - 短期功能分支
+  - 資深 Git 使用者
+
+characteristics:
+  history: 完全線性
+  commit_count: 保留所有提交（重寫）
+  reversibility: 需要還原每個提交
+  bisect_friendly: 優秀
+
+rules:
+  - id: never-rebase-shared
+    trigger: 變基時
+    instruction: 永不變基已推送/共享的分支
+    priority: required
+
+  - id: rebase-before-merge
+    trigger: 合併前
+    instruction: 總是在合併前變基到最新 main
+    priority: required
+
+  - id: clean-commits
+    trigger: 變基前
+    instruction: 確保提交是原子性且有意義的
+    priority: recommended
+
+  - id: interactive-rebase
+    trigger: 清理歷史時
+    instruction: 使用互動式變基壓縮 WIP 提交
+    priority: recommended
+
+workflow:
+  - step: 建立功能分支
+    commands:
+      - git checkout main
+      - git checkout -b feature/{功能名稱}
+
+  - step: 進行提交
+    commands:
+      - git commit -m "feat: implement feature part 1"
+      - git commit -m "feat: implement feature part 2"
+
+  - step: 變基到最新 main
+    commands:
+      - git fetch origin
+      - git rebase origin/main
+
+  - step: 快進合併
+    commands:
+      - git checkout main
+      - git merge --ff-only feature/{功能名稱}
+
+  - step: 推送並刪除分支
+    commands:
+      - git push origin main
+      - git branch -d feature/{功能名稱}
+
+interactive_rebase:
+  description: 清理提交歷史
+  commands:
+    - git rebase -i HEAD~3
+  actions:
+    - pick: 保留提交原樣
+    - reword: 變更提交訊息
+    - squash: 與前一個合併
+    - fixup: 與前一個合併（丟棄訊息）
+    - drop: 移除提交
+
+example:
+  before: |
+    main: A---B---C
+                   \
+    feature:        D---E---F
+  after_rebase: |
+    main: A---B---C
+                   \
+    feature:        D'---E'---F'
+  after_ff: |
+    main: A---B---C---D'---E'---F'
+
+pros:
+  - 完美線性歷史
+  - 每個提交都有意義
+  - 優秀的 bisect 支援
+  - 乾淨的 git log
+
+cons:
+  - 重寫歷史風險
+  - 需要更多 Git 知識
+  - 不適合共享分支
+  - 合併衝突需解決多次
+
+quick_reference:
+  commands:
+    columns: [操作, 指令]
+    rows:
+      - [變基到 main, "git rebase origin/main"]
+      - [互動式變基, "git rebase -i HEAD~n"]
+      - [快進合併, "git merge --ff-only branch"]
+      - [中止變基, "git rebase --abort"]
+      - [繼續變基, "git rebase --continue"]

package/bundled/locales/zh-TW/ai/options/git-workflow/squash-merge.ai.yaml

@@ -0,0 +1,85 @@
+# 壓縮合併 - AI 優化選項
+# 父項: git-workflow
+
+id: squash-merge
+meta:
+  parent: git-workflow
+  version: "1.0.0"
+  description: 將所有分支提交壓縮為單一提交
+  language: zh-TW
+
+best_for:
+  - 乾淨線性歷史
+  - 功能分支工作流程
+  - 每 PR 一個提交的偏好
+
+characteristics:
+  history: 線性
+  commit_count: 每 PR 一個提交
+  reversibility: 簡單還原
+  bisect_friendly: 中等
+
+rules:
+  - id: meaningful-squash-message
+    trigger: 壓縮合併時
+    instruction: 撰寫完整的提交訊息總結所有變更
+    priority: required
+
+  - id: pr-title-as-commit
+    trigger: 合併 PR 時
+    instruction: 使用 PR 標題作為壓縮提交的主旨
+    priority: recommended
+
+  - id: include-pr-reference
+    trigger: 撰寫壓縮訊息時
+    instruction: 在提交訊息中包含 PR 編號
+    priority: recommended
+
+workflow:
+  - step: 建立功能分支
+    commands:
+      - git checkout main
+      - git checkout -b feature/{功能名稱}
+
+  - step: 進行多次提交
+    commands:
+      - git commit -m "wip: initial implementation"
+      - git commit -m "wip: add tests"
+      - git commit -m "wip: fix lint errors"
+
+  - step: 壓縮合併（通過 GitHub/GitLab）
+    commands:
+      - "# 在 GitHub/GitLab 中合併時選擇 'Squash and merge'"
+      - "# 結果：所有提交壓縮為一個"
+
+  - step: 或使用命令列
+    commands:
+      - git checkout main
+      - git merge --squash feature/{功能名稱}
+      - git commit -m "feat(scope): 總結訊息 (#PR號)"
+
+example:
+  before: |
+    * abc1234 wip: fix lint
+    * def5678 wip: add tests
+    * ghi9012 wip: initial
+  after: |
+    * xyz7890 feat(auth): implement OAuth login (#123)
+
+pros:
+  - 乾淨、可讀的歷史
+  - 簡單還原功能
+  - 每個功能一個提交
+
+cons:
+  - 失去詳細提交歷史
+  - 較難追蹤個別變更
+  - 在 bisect 偵錯時可能較困難
+
+quick_reference:
+  commands:
+    columns: [操作, 指令]
+    rows:
+      - [壓縮合併, "git merge --squash branch"]
+      - [還原壓縮提交, "git revert <commit>"]
+      - [查看線性歷史, "git log --oneline"]

package/bundled/locales/zh-TW/ai/options/git-workflow/trunk-based.ai.yaml

@@ -0,0 +1,117 @@
+# 主幹開發 - AI 優化選項
+# 父項: git-workflow
+
+id: trunk-based
+meta:
+  parent: git-workflow
+  version: "1.0.0"
+  description: 直接提交到主幹的持續整合工作流程
+  language: zh-TW
+
+best_for:
+  - 持續部署（每天多次）
+  - 成熟的 CI/CD 管線
+  - 資深開發團隊
+  - 微服務架構
+
+branches:
+  - name: main (trunk)
+    purpose: 永遠可部署的單一真相來源
+    lifetime: 永久
+
+  - name: feature/*
+    purpose: 非常短期的功能分支（選用）
+    lifetime: 最多 1-2 天
+    note: 許多團隊直接提交到 trunk
+
+rules:
+  - id: small-frequent-commits
+    trigger: 提交程式碼時
+    instruction: 小而頻繁的提交（每天多次）
+    priority: required
+
+  - id: feature-flags
+    trigger: 開發新功能時
+    instruction: 使用功能旗標隱藏未完成功能
+    priority: required
+
+  - id: trunk-always-green
+    trigger: 合併到 trunk 時
+    instruction: 所有測試必須通過；trunk 永遠可部署
+    priority: required
+
+  - id: no-long-lived-branches
+    trigger: 建立分支時
+    instruction: 分支存活不超過 2 天
+    priority: required
+
+  - id: ci-required
+    trigger: 推送變更時
+    instruction: 每次推送都必須觸發 CI 管線
+    priority: required
+
+workflow:
+  direct_commit:
+    - step: 從最新 trunk 開始
+      commands:
+        - git checkout main
+        - git pull origin main
+
+    - step: 進行小變更
+      commands:
+        - "# 進行小而聚焦的變更"
+        - git add .
+        - git commit -m "feat: {描述}"
+
+    - step: 推送到 trunk
+      commands:
+        - git pull --rebase origin main
+        - git push origin main
+
+  short_branch:
+    - step: 建立短期分支
+      commands:
+        - git checkout main
+        - git pull origin main
+        - git checkout -b feature/{小功能}
+
+    - step: 快速開發（最多 2 天）
+      commands:
+        - "# 進行變更..."
+        - git add .
+        - git commit -m "feat: {描述}"
+
+    - step: 快速合併
+      commands:
+        - git checkout main
+        - git pull origin main
+        - git merge --ff-only feature/{小功能}
+        - git push origin main
+
+feature_flags:
+  description: 使用功能旗標允許不完整程式碼進入 trunk
+  example: |
+    if (featureFlags.isEnabled('new-checkout')) {
+      return <NewCheckout />;
+    }
+    return <OldCheckout />;
+
+practices:
+  - name: 結對程式設計
+    benefit: 即時程式碼審查
+  - name: 測試驅動開發
+    benefit: 高信心的頻繁合併
+  - name: 功能旗標
+    benefit: 不完整功能的安全部署
+  - name: 監控
+    benefit: 快速偵測問題
+
+quick_reference:
+  principles:
+    columns: [原則, 說明]
+    rows:
+      - [小提交, 每次變更少於 200 行]
+      - [頻繁整合, 每天多次合併到 trunk]
+      - [功能旗標, 隱藏進行中功能]
+      - [永遠綠燈, Trunk 永遠可部署]
+      - [快速回饋, CI 在數分鐘內完成]

package/bundled/locales/zh-TW/ai/options/project-structure/dotnet.ai.yaml

@@ -0,0 +1,108 @@
+# .NET 專案結構 - AI 優化選項
+# 父項: project-structure
+
+id: dotnet
+meta:
+  parent: project-structure
+  version: "1.0.0"
+  description: .NET/C# 專案的標準目錄結構
+  language: zh-TW
+
+structure:
+  template: |
+    SolutionName/
+    ├── src/
+    │   ├── SolutionName.Api/           # Web API 專案
+    │   │   ├── Controllers/
+    │   │   ├── Middleware/
+    │   │   ├── Program.cs
+    │   │   └── appsettings.json
+    │   ├── SolutionName.Core/          # 核心業務邏輯
+    │   │   ├── Entities/
+    │   │   ├── Interfaces/
+    │   │   └── Services/
+    │   ├── SolutionName.Infrastructure/ # 外部服務實作
+    │   │   ├── Data/
+    │   │   ├── Repositories/
+    │   │   └── ExternalServices/
+    │   └── SolutionName.Shared/        # 共用程式碼
+    │       ├── DTOs/
+    │       ├── Extensions/
+    │       └── Utils/
+    ├── tests/
+    │   ├── SolutionName.UnitTests/
+    │   ├── SolutionName.IntegrationTests/
+    │   └── SolutionName.FunctionalTests/
+    ├── docs/
+    ├── scripts/
+    ├── SolutionName.sln
+    ├── .editorconfig
+    ├── Directory.Build.props
+    └── README.md
+
+layers:
+  - name: Api
+    responsibility: HTTP 端點、中介軟體、DI 設定
+    depends_on: [Core, Infrastructure]
+
+  - name: Core
+    responsibility: 業務邏輯、實體、介面
+    depends_on: []
+
+  - name: Infrastructure
+    responsibility: 資料存取、外部服務
+    depends_on: [Core]
+
+  - name: Shared
+    responsibility: 共用 DTO、擴充方法
+    depends_on: []
+
+conventions:
+  naming:
+    files: PascalCase.cs
+    directories: PascalCase
+    classes: PascalCase
+    interfaces: IPascalCase
+    methods: PascalCase
+    private_fields: _camelCase
+    constants: PascalCase
+
+rules:
+  - id: clean-architecture
+    trigger: 組織專案時
+    instruction: 遵循 Clean Architecture 原則（相依性向內）
+    priority: required
+
+  - id: interface-segregation
+    trigger: 定義介面時
+    instruction: 在 Core 定義介面，在 Infrastructure 實作
+    priority: required
+
+  - id: project-references
+    trigger: 加入參考時
+    instruction: Api → Infrastructure → Core，Shared 可被任何專案參考
+    priority: required
+
+project_files:
+  directory_build_props: |
+    <Project>
+      <PropertyGroup>
+        <TargetFramework>net8.0</TargetFramework>
+        <ImplicitUsings>enable</ImplicitUsings>
+        <Nullable>enable</Nullable>
+        <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+      </PropertyGroup>
+    </Project>
+
+tools:
+  build: dotnet CLI, MSBuild
+  testing:
+    - xUnit（推薦）
+    - NUnit
+    - MSTest
+  mocking:
+    - Moq
+    - NSubstitute
+  orm:
+    - Entity Framework Core
+    - Dapper

package/bundled/locales/zh-TW/ai/options/project-structure/go.ai.yaml

@@ -0,0 +1,115 @@
+# Go 專案結構 - AI 優化選項
+# 父項: project-structure
+
+id: go
+meta:
+  parent: project-structure
+  version: "1.0.0"
+  description: Go 專案的標準目錄結構
+  language: zh-TW
+
+structure:
+  template: |
+    project-root/
+    ├── cmd/                        # 主要應用程式
+    │   ├── api/
+    │   │   └── main.go             # API 伺服器進入點
+    │   └── worker/
+    │       └── main.go             # 背景 worker 進入點
+    ├── internal/                   # 私有應用程式程式碼
+    │   ├── config/                 # 設定
+    │   │   └── config.go
+    │   ├── handlers/               # HTTP 處理器
+    │   │   └── user_handler.go
+    │   ├── services/               # 業務邏輯
+    │   │   └── user_service.go
+    │   ├── repositories/           # 資料存取
+    │   │   └── user_repository.go
+    │   ├── models/                 # 資料模型
+    │   │   └── user.go
+    │   └── middleware/             # HTTP 中介軟體
+    ├── pkg/                        # 公開函式庫程式碼
+    │   └── utils/
+    ├── api/                        # API 定義
+    │   └── openapi.yaml
+    ├── scripts/                    # 建置/部署腳本
+    ├── docs/                       # 文件
+    ├── go.mod
+    ├── go.sum
+    ├── Makefile
+    └── README.md
+
+directories:
+  - name: cmd/
+    purpose: 應用程式進入點
+    note: 每個子目錄是一個可執行檔
+
+  - name: internal/
+    purpose: 私有程式碼（Go 強制）
+    note: 無法被外部套件導入
+
+  - name: pkg/
+    purpose: 可被外部使用的函式庫程式碼
+    note: 小心使用，僅用於真正可重用的程式碼
+
+conventions:
+  naming:
+    files: snake_case.go
+    packages: 簡短、小寫、單一單字
+    interfaces: 動詞 + "er"（Reader, Writer）
+    structs: 名詞（User, Config）
+    functions: camelCase（exported 用 PascalCase）
+
+  file_organization:
+    - 一個檔案一個主要類型
+    - 測試檔案命名為 *_test.go
+    - 測試與原始碼放一起
+
+rules:
+  - id: flat-structure
+    trigger: 組織套件時
+    instruction: 優先扁平結構，避免過深巢狀
+    priority: recommended
+
+  - id: internal-private
+    trigger: 放置私有程式碼時
+    instruction: 使用 internal/ 保護應用程式程式碼
+    priority: required
+
+  - id: interface-consumers
+    trigger: 定義介面時
+    instruction: 在消費者套件定義介面，而非提供者
+    priority: recommended
+
+  - id: small-interfaces
+    trigger: 設計介面時
+    instruction: 優先使用小介面（1-3 個方法）
+    priority: recommended
+
+makefile:
+  example: |
+    .PHONY: build test run lint
+
+    build:
+    	go build -o bin/api ./cmd/api
+
+    test:
+    	go test ./...
+
+    run:
+    	go run ./cmd/api
+
+    lint:
+    	golangci-lint run
+
+tools:
+  build: go build, Makefile
+  testing:
+    - go test
+    - testify
+  linting:
+    - golangci-lint
+    - staticcheck
+  mocking:
+    - mockgen
+    - mockery