制定一部有原則、限制和標準的憲法

  • 10 分鐘

該架構是以 GitHub Spec Kit 為基礎的規範驅動開發。 本單元探討如何為企業發展情境制定有效的章程。

複習憲法基礎

章程檔案載錄了不可妥協的原則、限制和標準，用來指引和管理您的專案。 它同時也是人工智慧輔助開發的護欄。 當代理人產生規格、計畫、任務或程式碼時，會參考章程以驗證提案是否符合您的標準。

明確憲法的主要好處包括：

  • 一致性強制執行：確保長期專案及多位開發商的架構決策與一致性。
  • 合規文件：使法規要求與安全政策明確且可稽核。
  • 機構知識擷取：以指導 AI 程式碼生成的形式保存來之不易的教訓。
  • 降低認知負荷：在開發過程中自動執行組織政策。

憲法的目的

明確憲法的好處在實務上透過自動執行變得強大。 如果憲法規定「所有資料必須在靜態時加密」，AI 代理並不建議以明文儲存檔案——它會自動將加密納入設計中。 當你產生檔案上傳的規格時，計畫中包含了 Azure Storage 加密設定。 當你產生程式碼時，你的實作會使用加密的儲存服務。

請考慮每種效益在實際開發情境中的表現：

  • 一致性強制執行：跨越數月或涉及多位開發者的專案，可能偏離架構決策。 沒有章程，一位開發者可能會使用本地檔案儲存，而另一位則使用 Azure Blob Storage 來提供類似功能。 憲法透過編碼標準防止這種偏移，AI 助理始終參考，確保所有功能在技術選擇上保持一致。

  • 合規文件：必須遵守法規要求、安全政策及內部治理規則。 憲法明確規定了要求，建立可稽核的合規執行紀錄。 當稽核員問「你如何確保個人資料不會被記錄？」時，你要指出憲法要求，並證明所有產生的程式碼都遵守這個限制。

  • 機構知識擷取：經驗豐富的架構師與資安團隊根據辛苦得來的經驗做出決策——例如發現某些 API 模式會造成效能問題，或特定認證流程會造成安全漏洞。 章程以指導 AI 程式碼生成的形式保留了這些智慧，防止新團隊成員反覆發現相同的限制。

  • 降低認知負擔：開發者在提示 AI 時不必記住所有組織標準。 憲法自動化執行政策，例如「使用 Azure Key Vault 管理秘密」或「透過 Microsoft Entra ID 進行認證」。AI 不再手動檢查每個產生的計畫是否符合需求清單，而是自動整合這些需求。

在企業開發環境中，章程通常會編碼：

  • 這是企業政策所要求的安全要求。
  • 企業工作負載的效能與可擴展性目標。
  • 技術選擇與 Azure 服務及內部工具相符。
  • 來自工程最佳實務的編碼標準與架構模式。
  • 合規義務，如無障礙標準、個人資料保護及稽核要求。

有效憲法的結構

結構良好的憲法會將原則組織成 AI 助理能輕易查閱的類別。

常見的章節包括：

  • 技術標準。
  • 安全需求。
  • 效能與可擴展性。
  • 程式碼標準。
  • 合規與治理。

以下章節將說明如何有效定義每個類別。

技術標準

技術標準用於規範經核准的技術、平台與框架。

例如，以下章節要求 Azure 服務與 .NET 用於後端開發：

## Technology Standards

- All cloud resources must be hosted on Microsoft Azure.
- Back-end services use .NET 8 or later.
- Front-end applications use React or Blazor.
- Database: Azure SQL Database or Cosmos DB (no on-premises SQL Server).
- Secret management exclusively via Azure Key Vault.

這些限制防止 AI 提出不相容的技術。 如果章程強制要求 Azure，GitHub Copilot 就不會提出 Amazon Web Services 的 Lambda 功能。

安全性需求

安全需求可以用來定義像是驗證、授權、加密和資料保護規則等事項。

例如，以下章節將建立內部應用的安全原則：

## Security Requirements

- Authenticate all API requests using Microsoft Entra ID tokens.
- Encrypt all data at rest using AES-256 encryption.
- Encrypt data in transit using TLS 1.2 or higher.
- Never log personally identifiable information (PII).
- Store no secrets in source code or configuration files.
- Implement role-based access control (RBAC) for all features.

安全原則對企業發展至關重要。 明確要求確保產生的程式碼從一開始就包含安全性。

效能和可擴縮性

效能與可擴展性需求用於設定系統在負載下行為的預期。

例如，以下章節定義了 API 的效能目標：

## Performance and Scalability

- APIs must respond within 200ms for 95th percentile requests.
- System must handle 10,000 concurrent users.
- Use asynchronous processing for operations exceeding 5 seconds.
- Implement caching for frequently accessed data.
- Design for horizontal scalability using Azure App Service or Container Apps.

效能需求指導架構決策。 若章程要求非同步處理大型檔案上傳，計畫則包含背景處理。

法規標準與指引

標準與指引提供有助於確保法規品質的要求。

例如，以下章節概述了 .NET 專案的編碼慣例：

## Coding Standards

- Follow Microsoft C# Coding Conventions.
- Maintain minimum 80% unit test coverage.
- All public APIs documented with XML comments.
- Use dependency injection for service dependencies.
- Implement structured logging using ILogger interface.

編碼標準確保整個程式碼庫的一致性。 當章程引用團隊慣例時，AI 生成的程式碼會與隊伍慣例保持一致。

合規性和治理

合規與治理要求用於記錄法規及內部政策要求。

例如，以下章節說明資料處理的合規原則：

## Compliance and Governance

- Comply with local and international standards that protect personal information for all user data processing.
- Implement audit logging for all data modifications.
- Support accessibility standards (WCAG 2.1 Level AA).
- Enable monitoring and alerting via Azure Application Insights.
- Retain logs for minimum 90 days for compliance audits.

合規原則保護您的組織免於法規違規。 憲法確保這些原則在開發過程中不會被遺忘。

使用 GitHub Spec Kit 建立章程

GitHub Spec Kit /speckit.constitution 的指令可用來建立或更新憲法檔案。

現有專案

當你在處理已包含憲法檔案的現有專案時，可以用指令 /speckit.constitution 更新憲法檔案。 GitHub Copilot 會檢視現有的章程，並根據你的程式碼庫提出更新建議。 GitHub Spec Kit 本身的更新也可反映在建議的變更中。

當你要將 GitHub Spec Kit 加入尚未有章程的現有專案時，你可以在 GitHub Copilot Chat 裡 /speckit.constitution 用指令產生一個。 GitHub Copilot 會審查現有的程式碼庫，並推斷專案原則與限制，建立初始 constitution.md 檔案。 如有需要，您可以精煉產生的架構，確保其準確反映專案需求。

新專案

當你使用 GitHub Spec Kit 啟動新專案時，可以用 GitHub Copilot Chat 的指令從零 /speckit.constitution 開始產生架構。

為新計畫制定章程：

  1. 在 Visual Studio Code 中開啟你的專案，並確保 GitHub Spec Kit 已經初始化。

  2. 打開 GitHub Copilot Chat，然後用自然語言描述你的專案原則和限制執行指令 /speckit.constitution 。

    例如，你可以提供以下提示：

    /speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements. Include governance for how these principles should guide technical decisions and implementation choices.

    GitHub Copilot 會產生一個結構化 constitution.md 檔案，並依類別組織多個區段。

精煉生成的憲法

GitHub Copilot 產生初始架構後，請審查並編輯以確保準確性。

請考慮下列步驟：

  • 新增缺少的原則：如果 GitHub Copilot 遺漏了重要需求，請手動補充。 例如，如果您的組織需要特定的日誌格式，就加入該限制。

  • 移除不必要的內容：GitHub Copilot 可能會產生模板化或過於通用的原則。 刪除任何沒有具體指引的內容。

  • 使原則具體且可檢驗：用可衡量的標準取代模糊的陳述。 將「系統應該很快」改為「95% 請求的 API 回應在 200 毫秒內完成」。

  • 與內部標準保持一致：盡可能參考現有文件。 例如：「遵循 Engineering Excellence 指引 v2.3 進行 API 設計。」

  • 與利害關係人核實：將章程分享給資安、合規及架構團隊，確認其涵蓋所有必要需求。

憲法是一份活文件，但變動不頻繁。 一旦建立起來，它就能在功能開發過程中提供穩定的指引。

規格驅動開發工作流程中的憲法

建立章程後，GitHub Spec Kit 會在後續工作流程階段自動引用：

  • 規格階段：當你執行 /speckit.specify 建立功能規格時，GitHub Copilot 會檢查章程，確保需求不違反既定原則。 如果規範建議將檔案儲存在本地，GitHub Copilot 會標記此衝突與憲法中 Azure Blob Storage 的規定有關。

  • 規劃階段：/speckit.plan 命令生成技術計畫，明確驗證符合法規要求。 計畫包含多個章節，展示設計如何滿足各相關原則。

  • 分析階段：進行 /speckit.analyze 會將你的規格、計畫和任務與內部規範進行比較，找出不一致之處。 例如，若任務包含實作使用者名稱/密碼驗證，但章程要求 Microsoft Entra ID，分析可捕捉此偏差。

  • 實作階段：當你用 生成程式碼 /speckit.implement時，GitHub Copilot 會產生符合憲法約束的實作。 若憲法規定，程式碼自動包含 Microsoft Entra ID 認證。

這種整合正是憲法強大的原因——只要制定一次原則，AI 就會自動在整個開發過程中強制執行。

企業專屬制度考量

在為企業內部專案制定章程時，請納入以下共同要求：

  • Azure 優先架構：強制使用 Azure 服務用於主機、儲存、資料庫及支援基礎設施。 這項需求與企業雲端策略及現有工具相符。

  • 企業認證：要求使用 Microsoft Entra ID 進行認證，並以 RBAC 進行授權。 大多數企業內部應用程式都與企業身份系統整合。

  • 安全性與合規性：參考企業安全政策、TrustWorthy Computing 原則及適用的合規架構。

  • 監控與可觀察性：強制使用 Azure Application Insights 或同等的監控解決方案。 企業應用需要完整的遙測支援以支援生產環境。

  • 開發者工具標準：指定核准的框架、函式庫及開發實務。 例如，要求使用來自內部來源並經過核准的 NuGet 套件。

  • 無障礙性：納入 WCAG 2.1 AA 級合規要求。 企業內部工具必須對身心障礙員工開放。

企業內部章程範例摘要：

# Employee Portal Constitution

## Azure Platform Standards
- Host all services on Azure App Service or Azure Container Apps.
- Use Azure Blob Storage for document storage.
- Database: Azure SQL Database or Cosmos DB.
- Secrets stored exclusively in Azure Key Vault.
- Use Azure Front Door for global distribution.

## Identity Integration
- Authenticate via Microsoft Entra ID using OAuth 2.0 / OpenID Connect.
- Implement role-based access control using Microsoft Entra ID groups.
- Support multi-factor authentication (MFA).
- No custom authentication or local user databases.

## Corporate Compliance
- Follow enterprise Security Development Lifecycle (SDL) practices.
- Scan all dependencies for known vulnerabilities.
- Implement audit logging per enterprise retention policies.
- Support data residency requirements for EU users.
- Accessibility: WCAG 2.1 Level AA minimum.

## Development Standards
- Back end: .NET 10 following coding conventions adopted by the organization.
- Use approved packages from internal NuGet feed.
- Minimum 80% code coverage with unit tests.
- All APIs documented with OpenAPI/Swagger.
- Structured logging using ILogger interface.

透過在章程中事先確立這些原則，你確保為員工入口網站打造的每一項功能都能自動符合企業工程標準、安全需求及架構模式。 憲法將組織知識轉化為可執行的限制，指導 AI 輔助開發。

總結

規範檔案是在使用 GitHub Spec Kit 進行規範導向開發時的關鍵產物。 它捕捉了不可改變的專案原則、限制條件與標準，這些規範了開發的每個階段。 事先定義這些需求，即可讓 GitHub Copilot 在規格、規劃、分析與實施過程中自動執行合規。