chore: bootstrap skills library — 19 skills + installer + CI auto-tag
Some checks failed
release / tag (push) Has been cancelled
Some checks failed
release / tag (push) Has been cancelled
Phase 1 of mathias/skills extraction (infra#62 Track D — homelab next-step plan addendum). Imports ~/dev/.skills/ verbatim (19 skill dirs + SKILLS_INDEX.md) and adds the installation surface: - Taskfile.yml — install / update / list / release / check targets - install.sh — bootstrap installer for hosts without Task. Idempotent symlink wirer; default checkout at ~/.local/share/skills/ on every host; SKILLS_REF env var pins a tag (default: main). - .gitea/workflows/release.yml — auto-tag every push to main by Bump-Type footer (major/minor/patch, default patch). Skipped when commit contains [skip-release]. - README — usage, versioning, contribution flow, secret-hygiene rule. Phase 1 wires Claude Code only (~/.claude/skills/<name> global + <repo>/.claude/skills/<name> per-repo). Phase 2 adds Crush, opencode, antigravity, and gitea-resident agents (cobalt-dingo, agentsquad) once their skill conventions are researched. Public repo, markdown-only — no secrets, no client names. Verified via pre-push grep before initial push. [skip-release]
This commit is contained in:
Mathias
282
clean-code/SKILL.md
Normal file
282
clean-code/SKILL.md
Normal file
@@ -0,0 +1,282 @@
|
||||
---
|
||||
name: clean-code
|
||||
description: Write code that humans can read, understand, and safely change. Apply SOLID, GRASP, and Clean Code principles during the REFACTOR phase of TDD.
|
||||
---
|
||||
|
||||
# Clean Code
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
Write code for humans first, computers second. Every piece of code you write will be read many more times than it is written. Optimize for clarity and simplicity above all else.
|
||||
|
||||
Code has three consumers:
|
||||
1. **Users** — get their needs met
|
||||
2. **Customers** — make or save money
|
||||
3. **Developers** — must maintain it
|
||||
|
||||
Developers read code 10x more than they write it. Design for them.
|
||||
|
||||
## When to Apply This Skill
|
||||
|
||||
- During the **REFACTOR phase** of TDD (after the test is green)
|
||||
- When reviewing code (load `code-review` skill too)
|
||||
- When designing new types or packages
|
||||
|
||||
**Do not apply during the GREEN phase.** Ugly code that passes is correct. Clean it after.
|
||||
|
||||
## Naming
|
||||
|
||||
Naming is the most important thing in code. In priority order:
|
||||
|
||||
1. **Consistency** — Same concept = same name everywhere. One name per concept.
|
||||
2. **Understandability** — Domain language, not technical jargon.
|
||||
3. **Specificity** — Precise, not vague. Avoid `data`, `info`, `manager`, `handler`, `processor`, `utils`.
|
||||
4. **Brevity** — Short but not cryptic.
|
||||
5. **Searchability** — Unique, greppable names.
|
||||
6. **Pronounceability** — You should be able to say it in conversation.
|
||||
|
||||
```go
|
||||
// Bad: inconsistent, vague, cryptic
|
||||
func getUsrById(id string) {}
|
||||
func fetchCustomerByID(id string) {}
|
||||
func retrieveClientById(id string) {}
|
||||
|
||||
// Good: consistent, specific
|
||||
func GetUser(ctx context.Context, id UserID) (User, error) {}
|
||||
func GetOrder(ctx context.Context, id OrderID) (Order, error) {}
|
||||
```
|
||||
|
||||
## Functions/Methods
|
||||
|
||||
- Do one thing, do it well, do it only
|
||||
- Operate at a single level of abstraction
|
||||
- Prefer fewer parameters — zero is ideal, one or two common, three should be rare
|
||||
- Avoid side effects — if a function has a side effect, name it accordingly
|
||||
- Prefer pure functions where possible
|
||||
|
||||
```go
|
||||
// Bad: does too much, mixed abstraction levels
|
||||
func processOrder(o *Order, db *sql.DB, mailer Mailer) error {
|
||||
if o.Items == nil || len(o.Items) == 0 {
|
||||
return errors.New("empty order")
|
||||
}
|
||||
total := 0.0
|
||||
for _, item := range o.Items {
|
||||
total += item.Price * float64(item.Qty)
|
||||
}
|
||||
if _, err := db.Exec("INSERT INTO orders ...", o.ID, total); err != nil {
|
||||
return fmt.Errorf("save order: %w", err)
|
||||
}
|
||||
if err := mailer.Send(o.Customer.Email, "confirmed"); err != nil {
|
||||
return fmt.Errorf("send confirmation: %w", err)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// Good: single level of abstraction, composed from focused functions
|
||||
func ProcessOrder(ctx context.Context, o *Order, repo OrderRepository, mailer Mailer) error {
|
||||
if err := validateOrder(o); err != nil {
|
||||
return fmt.Errorf("validate: %w", err)
|
||||
}
|
||||
total := calculateTotal(o.Items)
|
||||
if err := repo.Save(ctx, o, total); err != nil {
|
||||
return fmt.Errorf("save: %w", err)
|
||||
}
|
||||
if err := mailer.SendConfirmation(ctx, o.Customer.Email); err != nil {
|
||||
return fmt.Errorf("notify: %w", err)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling (Go-Specific)
|
||||
|
||||
In Go, error returns are a first-class feature, not a smell. Follow these rules:
|
||||
|
||||
```go
|
||||
// Always wrap with context
|
||||
if err != nil {
|
||||
return fmt.Errorf("parse config: %w", err)
|
||||
}
|
||||
|
||||
// Never: naked return without context
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
// Never: log and return (pick one)
|
||||
if err != nil {
|
||||
log.Error("failed", "err", err)
|
||||
return err // caller gets logged error AND returns it — double-counted
|
||||
}
|
||||
|
||||
// Never: swallow errors silently
|
||||
_ = doSomething()
|
||||
```
|
||||
|
||||
Error wrapping builds a call-chain narrative: `"http handler: parse request: validate email: invalid format"`. This is valuable, not verbose.
|
||||
|
||||
## Comments
|
||||
|
||||
**The best comment is code that doesn't need one.** Before writing a comment, ask whether you could make the code itself clearer.
|
||||
|
||||
When comments are necessary, explain **why**, not what. The code shows what happens; comments explain decisions and intent.
|
||||
|
||||
```go
|
||||
// Bad: explains what (redundant)
|
||||
// increment counter
|
||||
i++
|
||||
|
||||
// Good: explains why
|
||||
// Offset by 1 because the upstream API uses 1-based page numbering
|
||||
page := requestedPage + 1
|
||||
```
|
||||
|
||||
**Go adaptation:** `godoc` comments on exported identifiers ARE documentation, not a failure. The "comments are failure" rule applies to inline comments explaining bad code. Exported types and functions must have godoc comments.
|
||||
|
||||
```go
|
||||
// UserService handles user lifecycle operations.
|
||||
// It is safe for concurrent use.
|
||||
type UserService struct { ... }
|
||||
|
||||
// GetByEmail returns the user with the given email address.
|
||||
// Returns ErrNotFound if no user exists with that email.
|
||||
func (s *UserService) GetByEmail(ctx context.Context, email Email) (User, error) { ... }
|
||||
```
|
||||
|
||||
## SOLID Principles (Brief)
|
||||
|
||||
For full SOLID guidance with Go examples, load the `solid` skill.
|
||||
|
||||
| Principle | Quick test |
|
||||
|-----------|------------|
|
||||
| SRP | "Does this type have ONE reason to change?" |
|
||||
| OCP | "Can I add behavior by implementing an interface, not editing this code?" |
|
||||
| LSP | "Can callers substitute any implementation without knowing the difference?" |
|
||||
| ISP | "Is this interface the smallest it can be?" (`io.Reader` is a model) |
|
||||
| DIP | "Do I pass interfaces as parameters, not concrete types?" |
|
||||
|
||||
## GRASP Principles
|
||||
|
||||
**Information Expert:** Assign responsibility to the type that has the data needed to fulfil it.
|
||||
|
||||
**Low Coupling:** Minimize dependencies between packages. When one changes, few others should too.
|
||||
|
||||
**High Cohesion:** Keep related functionality together. Everything in a package should relate to its central purpose.
|
||||
|
||||
**Controller:** One type handles system events for a use case.
|
||||
|
||||
**Tell, Don't Ask:** Tell objects what to do rather than asking for their data and acting on it.
|
||||
|
||||
## Go-Specific Clean Code Rules
|
||||
|
||||
### Prefer interfaces over concrete types in function signatures
|
||||
|
||||
```go
|
||||
// Bad: tied to a concrete implementation
|
||||
func NewHandler(db *postgres.DB) *Handler { ... }
|
||||
|
||||
// Good: depends on the behavior needed
|
||||
func NewHandler(store UserStore) *Handler { ... }
|
||||
```
|
||||
|
||||
### Small, focused interfaces
|
||||
|
||||
```go
|
||||
// The io.Reader/io.Writer pattern is the Go ideal
|
||||
type Reader interface {
|
||||
Read(p []byte) (n int, err error)
|
||||
}
|
||||
|
||||
// If you need both, compose at the call site
|
||||
type ReadWriter interface {
|
||||
Reader
|
||||
Writer
|
||||
}
|
||||
```
|
||||
|
||||
### Embedding over inheritance
|
||||
|
||||
```go
|
||||
// Use embedding for composition, not to inherit behavior you'll override
|
||||
type LoggedHandler struct {
|
||||
Handler
|
||||
logger *slog.Logger
|
||||
}
|
||||
```
|
||||
|
||||
### Constructor injection for dependencies
|
||||
|
||||
```go
|
||||
type Service struct {
|
||||
repo Repository
|
||||
mailer Mailer
|
||||
logger *slog.Logger
|
||||
}
|
||||
|
||||
func NewService(repo Repository, mailer Mailer, logger *slog.Logger) *Service {
|
||||
return &Service{repo: repo, mailer: mailer, logger: logger}
|
||||
}
|
||||
```
|
||||
|
||||
### Avoid package-level state
|
||||
|
||||
Package-level variables are global state. They make tests unreliable and code hard to reason about.
|
||||
|
||||
```go
|
||||
// Bad
|
||||
var db *sql.DB
|
||||
|
||||
// Good: pass as dependency
|
||||
type Handler struct {
|
||||
db *sql.DB
|
||||
}
|
||||
```
|
||||
|
||||
## Code Smell Detection (Quick Reference)
|
||||
|
||||
During the REFACTOR phase, look for these smells and address them:
|
||||
|
||||
| Smell | Go Signal | Fix |
|
||||
|-------|-----------|-----|
|
||||
| Long function | > ~30 lines (Go can go longer, but be honest) | Extract function |
|
||||
| Too many parameters | > 3-4 parameters | Use a config struct or option pattern |
|
||||
| Divergent change | One type changes for multiple unrelated reasons | Split into focused types |
|
||||
| Feature envy | Method uses another type's data more than its own | Move method to that type |
|
||||
| Magic numbers | Bare literals | Named constants or typed config |
|
||||
| Deep nesting | > 3 levels of indentation | Early returns, extract helpers |
|
||||
|
||||
For comprehensive smell detection, load the `code-review` skill.
|
||||
|
||||
## Structural Principles
|
||||
|
||||
**Separation of concerns:** Business logic should know nothing of HTTP, SQL, or filesystems.
|
||||
|
||||
**Modularity:** Each package understandable in isolation.
|
||||
|
||||
**Command-Query Separation:** Functions either do something (command) or return something (query), not both.
|
||||
|
||||
**Principle of Least Surprise:** Code should behave the way readers expect.
|
||||
|
||||
**Boy Scout Rule:** Leave the code better than you found it.
|
||||
|
||||
## Pre-Refactor Checklist
|
||||
|
||||
Before cleaning up code:
|
||||
|
||||
- [ ] All tests pass
|
||||
- [ ] Race detector clean: `go test -race ./...`
|
||||
- [ ] I understand what the code does
|
||||
- [ ] I have a clear target design in mind
|
||||
|
||||
During refactoring:
|
||||
- [ ] Tests stay green after each change
|
||||
- [ ] Each change is small and focused
|
||||
- [ ] Commit after each meaningful improvement
|
||||
|
||||
## References
|
||||
|
||||
- `references/clean-code.md` — detailed naming rules, object calisthenics
|
||||
- `references/code-smells.md` — comprehensive smell catalog with examples
|
||||
- Load `solid` skill for SOLID principles with Go examples
|
||||
- Load `refactoring` skill for systematic refactoring techniques
|
||||
Reference in New Issue
Block a user