# Hexcheck

> Use when configuring or running hexcheck in a Go repo for hexagonal architecture boundaries, adapter business-logic warnings, and mock discipline.

- Skill: `bnema/hexcheck` (Agent Skill)
- Install (CLI): `npx skillmds@latest add bnema/hexcheck`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bnema/hexcheck/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: bnema (https://skillmd.com/u/bnema)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bnema/hexcheck

---


# Hexcheck

Configure `.hexcheck.yaml` by mapping repo paths to roles. Folder names do not matter; roles do.

**Testing status:** `hexcheck` is in a testing phase. If behavior, configuration, diagnostics, or documentation seem off, report it by creating an issue at <https://github.com/bnema/hexcheck/issues>. Include the repo layout, `.hexcheck.yaml`, command run, output, and what looked wrong.

Roles:
- `core`: domain/core business logic
- `usecase`: application use cases/orchestration
- `ports`: interfaces/contracts
- `adapter`: infra, persistence, external services, outbound adapters
- `entrypoint`: CLI/HTTP/UI/bootstrap
- `ignore`: generated code, mocks, vendor

Minimal shape:

```yaml
version: 1
components:
  core: { role: core, paths: [internal/domain/**, internal/core/**] }
  usecases: { role: usecase, paths: [internal/application/usecase/**, internal/application/usecases/**, internal/usecases/**] }
  ports: { role: ports, paths: [internal/application/port/**, internal/domain/repository/**] }
  adapters: { role: adapter, paths: [internal/infrastructure/**, internal/adapters/**] }
  entrypoints: { role: entrypoint, paths: [cmd/**] }
  generated: { role: ignore, paths: ['**/mocks/**', '**/generated/**', '**/*_templ.go', '**/*_gen.go'] }
```

For repos using `boundaries`, map by role, e.g. `boundaries/in -> entrypoint`, `boundaries/out -> adapter`, `boundaries/ports -> ports`.

Recommended rules:

```yaml
rules:
  no-adapter-imports-in-core: error
  no-infra-imports-in-usecase: error
  no-framework-types-in-core: error
  no-infra-types-in-ports: error
  no-adapter-to-adapter-imports: warn
  suspicious-business-logic-in-adapter: warn
  no-local-fakes-for-ports: warn
  missing-generated-mock-for-port: warn
  prefer-generated-mocks: warn
```

Mock config:

```yaml
mocking:
  generatedMockPaths: [internal/mocks/**, internal/application/mocks/**, internal/application/port/mocks/**]
  generatedMockNamePatterns: ['Mock{{Interface}}', '{{Interface}}Mock']
```

Run:

```bash
hexcheck -hexcheck.config .hexcheck.yaml -hexcheck.root . ./...
```

Agent checklist: read repo architecture docs, map paths to roles, ignore generated/mocks, configure mock paths, run once, tune `ruleSettings.*.excludePaths` only after inspecting examples.