harness-enforce-architecture-guardrails
Skill0 starsChanged 8 months agoMITView on GitHub
架构护栏技能,强制执行分层架构约束,防止跨层调用和架构违规
In this repository33 other files it gives its agents.
- harness-10x-productivity-boostSkill
- harness-adjust-granularitySkill
- harness-analyze-project-scaleSkill
- harness-auto-full-executionSkill
- harness-brainstormSkill
- harness-build-context-indexSkill
- harness-build-core-manifestSkill
- harness-build-deterministic-workflowSkill
- harness-check-clean-stateSkill
- harness-configSkill
- harness-context-clearSkill
- harness-determine-granularitySkill
- harness-diagnose-and-improveSkill
- harness-enable-circuit-breakerSkill
- harness-escalate-to-humanSkill
- harness-evaluate-performanceSkill
- harness-evolveSkill
- harness-executing-plansSkill
- harness-generate-feature-listSkill
- harness-goalSkill
- harness-handle-failureSkill
- harness-initSkill
- harness-merge-agent-resultsSkill
- harness-merge-subharness-resultSkill
- harness-monitor-agent-batchSkill
- harness-monitor-subharness-agentSkill
- harness-planSkill
- harness-recover-clean-stateSkill
- harness-schedule-parallel-agentsSkill
- harness-session-handoffSkill
- harness-spawn-subharness-agentSkill
- harness-track-feature-progressSkill
- harness-validate-outputSkill
The file
Files
harness-enforce-architecture-guardrails 架构护栏技能
核心能力
- 检查前置条件(harness-build-core-manifest)
- 创建 ARCHITECTURE_GUARDRAILS.md
- 定义分层架构约束
- 定义违规检测规则
- 定义自动修复策略
前置条件
- harness-build-core-manifest 已完成
- AGENTS_MANIFEST.md 存在
执行步骤
Step 1: 检查前置条件
使用 Read 工具读取:.EnjoyHarness/SKILL_REGISTRY.md
检查条件:
- harness-build-core-manifest 已标记为完成
如果未完成:
❌ 错误: 核心规则未构建
💡 请先运行: harness-build-core-manifestStep 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)违规检测规则
检测时机
- 提交前: Git pre-commit hook
- PR合并前: CI/CD pipeline
- 运行时: 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: 跨层调用修复
违规代码:
// 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)
}架构违规错误码
| 错误码 | 违规类型 | 严重程度 | 自动修复 |
| ARCH-001 | 循环依赖 | 高 | ✅ |
| ARCH-002 | 跨层调用 | 高 | ✅ |
| ARCH-003 | 业务逻辑散落 | 中 | ⚠️ |
| ARCH-004 | 错误处理缺失 | 中 | ⚠️ |
| ARCH-005 | 全局变量使用 | 中 | ❌ |
| ARCH-006 | 隐式依赖 | 低 | ❌ |
使用说明
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
fi3. 与其他技能联动
- 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 | 架构护栏构建完成 | SUCCESSStep 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 错误码 验证方式: 手动测试跨层调用检测逻辑
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

