# Harness Enforce Architecture Guardrails

> 架构护栏技能，强制执行分层架构约束，防止跨层调用和架构违规

- Skill: `konglong87/harness-enforce-architecture-guardrails` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add konglong87/harness-enforce-architecture-guardrails`
- Raw SKILL.md: https://api.skillmd.com/api/skills/konglong87/harness-enforce-architecture-guardrails/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: konglong87 (https://skillmd.com/u/konglong87)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/konglong87/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`

内容：

```markdown
---
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 分析调用链
**违规示例**:
```go
// ❌ 违规: UI 层直接调用 Repo 层（跳过 Service）
user := repo.GetUser(id)

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

### 约束 3: 公共接口必须在 Types 层
**规则**: 跨层使用的接口必须定义在 Types 层
**检测**: 接口位置检查
**违规示例**:
```go
// ❌ 违规: Service 层定义公共接口
package service
type UserRepository interface { ... }

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

### 约束 4: 配置必须在 Config 层
**规则**: 所有配置读取必须通过 Config 层
**检测**: os.Getenv 调用位置
**违规示例**:
```go
// ❌ 违规: Service 层直接读取环境变量
port := os.Getenv("PORT")

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

### 约束 5: 业务逻辑集中在 Service 层
**规则**: 业务逻辑不能散落在 UI 或 Runtime 层
**检测**: 函数复杂度和位置分析
**违规示例**:
```go
// ❌ 违规: 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 层不能包含数据处理逻辑
**检测**: 函数职责分析
**违规示例**:
```go
// ❌ 违规: 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
**检测**: 函数签名分析
**违规示例**:
```go
// ❌ 违规: 可能失败但不返回 error
func GetUser(id int) *User {
    return db.Find(id)
}

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

### 约束 9: 禁止使用全局变量
**规则**: 禁止跨层共享可变全局变量
**检测**: 全局变量声明检查
**违规示例**:
```go
// ❌ 违规: 全局变量
var DB *sql.DB

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

### 约束 10: 依赖注入必须显式声明
**规则**: 所有依赖必须通过函数参数传递
**检测**: 参数分析
**违规示例**:
```go
// ❌ 违规: 隐式依赖
func CreateUser() {
    db := GetDB()  // 隐式获取
}

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

### 约束 11: 禁止在 Types 层导入其他层
**规则**: Types 层必须完全独立
**检测**: Types 层 import 检查
**违规示例**:
```go
// ❌ 违规: Types 层导入 Service 层
package types
import "myapp/service"
```

### 约束 12: 测试必须在对应的 _test 包
**规则**: 单元测试必须与被测代码同层
**检测**: 测试文件位置检查
**违规示例**:
```
// ❌ 违规: Service 测试放在 UI 层
ui/user_handler_test.go  // 测试 service.CreateUser
```

### 约束 13: 禁止在 Repo 层处理业务逻辑
**规则**: Repo 层仅负责数据访问
**检测**: 函数职责分析
**违规示例**:
```go
// ❌ 违规: 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 层
**检测**: 调用链分析
**违规示例**:
```go
// ❌ 违规: UI 层直接访问数据库
func HandleGetUser(w http.ResponseWriter, r *http.Request) {
    user := repo.GetUser(id)  // 跳过 Service 层
}
```

### 约束 15: 所有外部依赖必须在 Config 层配置
**规则**: 外部服务地址、密钥等必须在 Config 层
**检测**: 硬编码字符串检查
**违规示例**:
```go
// ❌ 违规: 硬编码外部服务地址
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 技能

### 检测方式
```bash
# 检测跨层调用
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: 跨层调用修复
**违规代码**:
```go
// ui/handler.go
func HandleGetUser(w http.ResponseWriter, r *http.Request) {
    user := repo.GetUser(id)  // ❌ 跳过 Service 层
    json.NewEncoder(w).Encode(user)
}
```

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

#### 示例 2: 业务逻辑下沉
**违规代码**:
```go
// ui/handler.go
func HandleCreateUser(w http.ResponseWriter, r *http.Request) {
    if user.Age < 18 {  // ❌ UI 层包含业务逻辑
        return Error("年龄必须≥18岁")
    }
    service.CreateUser(user)
}
```

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

## 架构违规错误码

| 错误码 | 违规类型 | 严重程度 | 自动修复 |
|--------|---------|---------|---------|
| ARCH-001 | 循环依赖 | 高 | ✅ |
| ARCH-002 | 跨层调用 | 高 | ✅ |
| ARCH-003 | 业务逻辑散落 | 中 | ⚠️ |
| ARCH-004 | 错误处理缺失 | 中 | ⚠️ |
| ARCH-005 | 全局变量使用 | 中 | ❌ |
| ARCH-006 | 隐式依赖 | 低 | ❌ |

## 使用说明

### 1. 提交前检查
```bash
# 运行架构护栏检查
./scripts/check-architecture.sh

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

### 2. CI/CD 集成
```yaml
# .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 工具输出：

```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 错误码
**验证方式**: 手动测试跨层调用检测逻辑