L-X-T/ng-agentic

ng-agentic 是做什麼的？

一個實用的 Angular 工作區起手包，內建現代最佳實踐、AI 就緒工具鏈，以及可擴展的專案設定指南。

簡介

ng-agentic 幫助開發者快速初始化一個 Angular 工作區，遵循官方及社群推薦的現代架構。它支援 Angular 17+ 的獨立元件（Standalone Components）、功能模組（Feature Modules）、以及可選的 Nx 整合，並內建 ESLint、Prettier、Husky 等品質工具。無論你是要開始一個全新的專案，還是為現有專案注入結構化標準，這個技能都能提供指引。

先決條件

• Node.js 18 或更新版本
• Angular CLI 17 或更新版本（可透過 npm install -g @angular/cli 安裝）
• Git

安裝與使用

建立新工作區

執行以下指令來建立一個新的 Angular 工作區，並套用本專案的結構：

ng new my-workspace --create-application=false
cd my-workspace
ng generate @angular/core:standalone

或使用我們提供的腳本快速初始化：

bash <(curl -fsSL https://raw.githubusercontent.com/L-X-T/ng-agentic/main/scripts/init.sh)

專案結構

my-workspace/
├── apps/                # 應用程式專案（如 app1, app2）
│   └── app1/
│       ├── src/
│       │   ├── app/
│       │   │   ├── features/    # 功能模組（懶載入）
│       │   │   ├── shared/      # 共享元件、管線、服務
│       │   │   ├── core/        # 核心服務（單例）
│       │   │   └── app.config.ts
│       │   ├── assets/
│       │   └── index.html
│       └── tsconfig.app.json
├── libs/                # 可重複使用的函式庫
├── tools/               # 建置腳本與工具
├── .eslintrc.json
├── .prettierrc
├── angular.json
├── nx.json              # 若使用 Nx
├── package.json
└── tsconfig.base.json

常用指令

用途	指令
開發伺服器	ng serve app1
建置專案	ng build app1
執行測試	ng test app1
執行端對端測試	ng e2e app1
檢查 lint	ng lint
格式化程式碼	npx prettier --write .

生成元件

使用 Angular CLI 生成元件時，請遵循以下慣例：

# 在特定功能模組中生成元件
ng g c features/products/product-list --standalone --skip-tests=false

# 生成服務
ng g s core/services/local-storage

最佳實踐

TypeScript 嚴格模式

啟用 tsconfig.json 中的 strict: true，並確保程式碼通過型別檢查：

{
  "compilerOptions": {
    "strict": true,
    "noImplicitOverride": true,
    "noPropertyAccessFromIndexSignature": true,
    "noUncheckedIndexedAccess": true
  }
}

獨立元件優先

優先使用 Angular 的獨立元件（Standalone Components），除非有明確的 NgModule 需求。獨立元件的宣告方式如下：

import { Component } from '@angular/core';
import { CommonModule } from '@angular/common';

@Component({
  selector: 'app-hello',
  standalone: true,
  imports: [CommonModule],
  template: `<h1>Hello, {{ name }}!</h1>`
})
export class HelloComponent {
  name = 'World';
}

記憶體管理與訂閱清理

所有 Observable 訂閱都應在第 ngOnDestroy 回呼中取消，使用 takeUntil 或 async pipe：

import { Subject, takeUntil } from 'rxjs';

@Component({...})
export class MyComponent implements OnDestroy {
  private destroy$ = new Subject<void>();

  ngOnInit() {
    this.myService.getData()
      .pipe(takeUntil(this.destroy$))
      .subscribe(data => this.data = data);
  }

  ngOnDestroy() {
    this.destroy$.next();
    this.destroy$.complete();
  }
}

AI 工具整合

本專案已預先設定好與 AI 輔助開發工具的相容性，例如：

• Claude Code: 透過 .claude 設定檔，可讓 Claude 理解專案結構並提供精確建議。
• Cursor: 支援 .cursorrules 與專案層級的規則套用。
• Codex: 可透過 ai-summary.md 檔案提供全域上下文。

請參考 AI 設定文件 獲取更多細節。

貢獻指南

我們歡迎任何貢獻！請先閱讀 CONTRIBUTING.md 了解開發流程與程式碼規範。

授權條款

此專案採用 MIT 授權條款。詳見 LICENSE 檔案。