Harness Enforce Architecture Guardrails

harness-enforce-architecture-guardrails 架构护栏技能

核心能力

1. 检查前置条件（harness-build-core-manifest）
2. 创建 ARCHITECTURE_GUARDRAILS.md
3. 定义分层架构约束
4. 定义违规检测规则
5. 定义自动修复策略

前置条件

• harness-build-core-manifest 已完成
• AGENTS_MANIFEST.md 存在

执行步骤

Step 1: 检查前置条件

使用 Read 工具读取：.EnjoyHarness/SKILL_REGISTRY.md

检查条件：

• harness-build-core-manifest 已标记为完成

如果未完成：

❌ 错误: 核心规则未构建
💡 请先运行: harness-build-core-manifest

Step 2: 创建架构护栏文件

使用 Write 工具创建文件：.EnjoyHarness/ARCHITECTURE_GUARDRAILS.md

内容：

---
version: v3.0.0
created_at: 2026-03-28T10:50:00+08:00
total_rules: 15
---

# EnjoyHarness 架构护栏规则

## 分层架构定义

Layer 1: Types（类型定义层）

• 数据模型（struct/interface）
• 常量定义
• 工具函数（纯函数）
• 依赖: 无

Layer 2: Config（配置层）

• 配置文件读取
• 环境变量管理
• 依赖: Types

Layer 3: Repo（数据访问层）

• 数据库操作
• 外部API调用
• 缓存管理
• 依赖: Types, Config

Layer 4: Service（业务逻辑层）

• 核心业务逻辑
• 数据处理
• 业务规则
• 依赖: Types, Config, Repo

Layer 5: Runtime（运行时层）

• 服务器启动
• 中间件配置
• 路由设置
• 依赖: Types, Config, Repo, Service

Layer 6: UI（展示层）

• HTTP handlers
• GraphQL resolvers
• 响应格式化
• 依赖: Types, Config, Service

## 架构约束规则（15条）

### 约束 1: 单向依赖原则
**规则**: 每层只能依赖直接下层，禁止向上依赖
**检测**: AST 分析 import 关系
**违规示例**:
```go
// ❌ 违规: Service 层直接导入 Runtime 层
import "myapp/runtime/server"

// ✅ 正确: Service 层仅依赖 Repo 层
import "myapp/repo/user"

约束 2: 跨层调用禁止

规则: 禁止跨层调用（跳过中间层） 检测: AST 分析调用链 违规示例:

// ❌ 违规: UI 层直接调用 Repo 层（跳过 Service）
user := repo.GetUser(id)

// ✅ 正确: UI 层调用 Service 层
user := service.GetUser(id)

约束 3: 公共接口必须在 Types 层

规则: 跨层使用的接口必须定义在 Types 层 检测: 接口位置检查 违规示例:

// ❌ 违规: Service 层定义公共接口
package service
type UserRepository interface { ... }

// ✅ 正确: Types 层定义接口
package types
type UserRepository interface { ... }

约束 4: 配置必须在 Config 层

规则: 所有配置读取必须通过 Config 层 检测: os.Getenv 调用位置 违规示例:

// ❌ 违规: Service 层直接读取环境变量
port := os.Getenv("PORT")

// ✅ 正确: 通过 Config 层读取
port := config.GetPort()

约束 5: 业务逻辑集中在 Service 层

规则: 业务逻辑不能散落在 UI 或 Runtime 层 检测: 函数复杂度和位置分析 违规示例:

// ❌ 违规: UI 层包含业务逻辑
func HandleCreateUser(w http.ResponseWriter, r *http.Request) {
    if user.Age < 18 {  // 业务逻辑
        return Error("年龄必须≥18岁")
    }
    ...
}

// ✅ 正确: 业务逻辑在 Service 层
func HandleCreateUser(w http.ResponseWriter, r *http.Request) {
    err := service.CreateUser(user)
    ...
}

约束 6: UI 层仅处理展示逻辑

规则: UI 层不能包含数据处理逻辑 检测: 函数职责分析 违规示例:

// ❌ 违规: UI 层处理数据转换
func HandleGetUser(w http.ResponseWriter, r *http.Request) {
    user := service.GetUser(id)
    response := map[string]interface{}{
        "name": user.FirstName + " " + user.LastName,  // 数据处理
    }
}

// ✅ 正确: UI 层仅格式化响应
func HandleGetUser(w http.ResponseWriter, r *http.Request) {
    user := service.GetUser(id)
    json.NewEncoder(w).Encode(user)
}

约束 7: 禁止循环依赖

规则: 包之间不能有循环导入 检测: import 图环检测 违规示例:

A imports B
B imports C
C imports A  // ❌ 循环依赖

约束 8: 错误处理必须返回 error

规则: 所有可能失败的函数必须返回 error 检测: 函数签名分析 违规示例:

// ❌ 违规: 可能失败但不返回 error
func GetUser(id int) *User {
    return db.Find(id)
}

// ✅ 正确: 返回 error
func GetUser(id int) (*User, error) {
    return db.Find(id)
}

约束 9: 禁止使用全局变量

规则: 禁止跨层共享可变全局变量 检测: 全局变量声明检查 违规示例:

// ❌ 违规: 全局变量
var DB *sql.DB

func GetUser() {
    DB.Query(...)  // 隐式依赖
}

约束 10: 依赖注入必须显式声明

规则: 所有依赖必须通过函数参数传递 检测: 参数分析 违规示例:

// ❌ 违规: 隐式依赖
func CreateUser() {
    db := GetDB()  // 隐式获取
}

// ✅ 正确: 显式依赖
func CreateUser(db *sql.DB) {
    ...
}

约束 11: 禁止在 Types 层导入其他层

规则: Types 层必须完全独立 检测: Types 层 import 检查 违规示例:

// ❌ 违规: Types 层导入 Service 层
package types
import "myapp/service"

约束 12: 测试必须在对应的 _test 包

规则: 单元测试必须与被测代码同层 检测: 测试文件位置检查 违规示例:

// ❌ 违规: Service 测试放在 UI 层
ui/user_handler_test.go  // 测试 service.CreateUser

约束 13: 禁止在 Repo 层处理业务逻辑

规则: Repo 层仅负责数据访问 检测: 函数职责分析 违规示例:

// ❌ 违规: Repo 层包含业务逻辑
func (r *UserRepo) Create(user *User) error {
    if user.Age < 18 {  // 业务逻辑
        return errors.New("年龄必须≥18岁")
    }
    return r.db.Create(user)
}

约束 14: 禁止在 UI 层访问数据库

规则: UI 层不能直接调用 Repo 层 检测: 调用链分析 违规示例:

// ❌ 违规: UI 层直接访问数据库
func HandleGetUser(w http.ResponseWriter, r *http.Request) {
    user := repo.GetUser(id)  // 跳过 Service 层
}

约束 15: 所有外部依赖必须在 Config 层配置

规则: 外部服务地址、密钥等必须在 Config 层 检测: 硬编码字符串检查 违规示例:

// ❌ 违规: 硬编码外部服务地址
client := http.Client{}
resp, _ := client.Get("https://api.example.com")

// ✅ 正确: 从 Config 读取
apiURL := config.GetAPIURL()
resp, _ := client.Get(apiURL)

违规检测规则

检测时机

1. 提交前: Git pre-commit hook
2. PR合并前: CI/CD pipeline
3. 运行时: harness-validate-output 技能

检测方式

# 检测跨层调用
grep -r "import.*service" ui/

# 检测全局变量
grep -r "^var.*=" --include="*.go" | grep -v "_test.go"

# 检测循环依赖
go list -f '{{.ImportPath}}: {{.Imports}}' ./... | detect_cycles.py

自动修复策略

修复优先级

1. 高优先级: 循环依赖、跨层调用 → 立即修复
2. 中优先级: 错误处理缺失 → 提示修复
3. 低优先级: 命名不规范 → 建议修复

修复示例

示例 1: 跨层调用修复

违规代码:

// ui/handler.go
func HandleGetUser(w http.ResponseWriter, r *http.Request) {
    user := repo.GetUser(id)  // ❌ 跳过 Service 层
    json.NewEncoder(w).Encode(user)
}

自动修复:

// ui/handler.go
func HandleGetUser(w http.ResponseWriter, r *http.Request) {
    user := service.GetUser(id)  // ✅ 通过 Service 层
    json.NewEncoder(w).Encode(user)
}

示例 2: 业务逻辑下沉

违规代码:

// ui/handler.go
func HandleCreateUser(w http.ResponseWriter, r *http.Request) {
    if user.Age < 18 {  // ❌ UI 层包含业务逻辑
        return Error("年龄必须≥18岁")
    }
    service.CreateUser(user)
}

自动修复:

// service/user.go
func CreateUser(user *User) error {
    if user.Age < 18 {  // ✅ 业务逻辑在 Service 层
        return errors.New("年龄必须≥18岁")
    }
    return repo.Create(user)
}

架构违规错误码

使用说明

1. 提交前检查

# 运行架构护栏检查
./scripts/check-architecture.sh

# 或使用 harness-enforce-architecture-guardrails 技能

2. CI/CD 集成

# .github/workflows/ci.yml
- name: Architecture Check
  run: |
    ./scripts/check-architecture.sh
    if [ $? -ne 0 ]; then
      echo "架构违规，请修复后再提交"
      exit 1
    fi

3. 与其他技能联动

• harness-validate-output: 在输出校验时触发架构检查
• harness-diagnose-and-improve: 诊断架构违规，自动修复
• harness-evolve: 根据架构违规记录，优化架构规则

### Step 3: 更新事件日志

使用 Edit 工具追加内容到：`.EnjoyHarness/EVENT_LOG.md`

追加内容：

```markdown
2026-03-28T10:50:00+08:00 | SKILL_START | harness-enforce-architecture-guardrails | 开始构建架构护栏 | SUCCESS
2026-03-28T10:50:00+08:00 | SKILL_COMPLETE | harness-enforce-architecture-guardrails | 架构护栏构建完成 | SUCCESS

Step 4: 更新事件计数

使用 Edit 工具更新：.EnjoyHarness/EVENT_LOG.md

old_string: total_events: 6 new_string: total_events: 8

Step 5: 更新技能注册表

使用 Edit 工具更新：.EnjoyHarness/SKILL_REGISTRY.md

old_string: - [ ] harness-enforce-architecture-guardrails - 架构护栏技能 new_string: - [x] harness-enforce-architecture-guardrails - 架构护栏技能 ✅

Step 6: 输出完成信息

使用 Bash 工具输出：

echo ""
echo "✅ harness-enforce-architecture-guardrails 完成!"
echo ""
echo "📋 架构护栏文件:"
echo "  - .EnjoyHarness/ARCHITECTURE_GUARDRAILS.md"
echo ""
echo "📊 规则统计:"
echo "  - 分层架构: 6层 (Types → Config → Repo → Service → Runtime → UI)"
echo "  - 约束规则: 15条"
echo "  - 错误码: 6个 (ARCH-001 到 ARCH-006)"
echo ""
echo "🔧 自动修复能力:"
echo "  - 循环依赖: ✅ 自动修复"
echo "  - 跨层调用: ✅ 自动修复"
echo "  - 业务逻辑散落: ⚠️ 提示修复"
echo "  - 错误处理缺失: ⚠️ 提示修复"
echo ""
echo "🎯 Phase 1 核心基础层已全部完成！"
echo ""

成功标准

• ARCHITECTURE_GUARDRAILS.md 文件存在
• 包含6层架构定义
• 包含15条约束规则
• 包含自动修复策略
• 技能注册表已更新

失败兜底

• harness-build-core-manifest 未完成 → 终止执行，提示运行前置技能
• 文件创建失败 → 记录错误到 EVENT_LOG.md，触发重试

联动关系

• 前置: harness-build-core-manifest
• 被触发: harness-validate-output（输出校验时使用）
• 被触发: harness-diagnose-and-improve（错误诊断时使用）

迭代计数

本技能执行预计迭代次数: 约 5 次（Write 1次 + Edit 3次 + Read 1次）

测试用例

测试 1: 前置条件检查

输入: 在核心规则未构建时运行 期望输出: 错误提示"核心规则未构建" 验证方式: 删除 AGENTS_MANIFEST.md 后运行

测试 2: 文件完整性

输入: 执行 harness-enforce-architecture-guardrails 期望输出: ARCHITECTURE_GUARDRAILS.md 包含15条约束规则 验证方式: grep -c "约束" .EnjoyHarness/ARCHITECTURE_GUARDRAILS.md

测试 3: 架构层级正确

输入: 读取 ARCHITECTURE_GUARDRAILS.md 期望输出: 包含6层架构（Types → Config → Repo → Service → Runtime → UI） 验证方式: grep -c "Layer" .EnjoyHarness/ARCHITECTURE_GUARDRAILS.md

测试 4: 技能注册表更新

输入: 读取 SKILL_REGISTRY.md 期望输出: harness-enforce-architecture-guardrails 标记为完成 验证方式: grep "harness-enforce-architecture-guardrails" .EnjoyHarness/SKILL_REGISTRY.md

测试 5: 事件日志记录

输入: 读取 EVENT_LOG.md 期望输出: 包含 harness-enforce-architecture-guardrails 启动和完成事件 验证方式: grep "harness-enforce-architecture-guardrails" .EnjoyHarness/EVENT_LOG.md

测试 6: 架构违规检测

输入: 创建一个跨层调用的代码示例 期望输出: 检测到 ARCH-002 错误码 验证方式: 手动测试跨层调用检测逻辑