Skill: Engineering Principles (Digest)
One-page digest of the universal principles in
engineering-principles.md (the full
document ships at the base root). Load the full section only when the
decision at hand needs it.
The principles at a glance
| § |
Principle |
Core rule |
| §1 |
UX first |
The interface exists to reduce the user's cognitive effort; accessibility (§1.5) is baseline quality, not a feature |
| §2 |
Security by default |
Validate server-side, hash passwords with modern KDFs, parameterize queries, audit dependencies (§2.8 supply chain) |
| §3 |
Low coupling, high cohesion |
Dependencies point inward (api → service → domain ← data); business logic never in controllers or repositories |
| §4 |
Contracts and evolution |
Public APIs are versioned (§4.4); breaking changes get a new version, never a silent change |
| §5 |
Tests as specification |
Every behavior has a test; tests are deterministic; coverage targets agreed, not implied |
| §6 |
Performance is a feature |
Paginate collections, index queried columns, measure before optimizing |
| §7 |
Resilience |
Timeouts on every external call; failures are expected inputs, not exceptions |
| §8 |
Simplicity |
The simplest design that meets today's requirement; complexity must pay rent |
AI-assisted work appendices
| § |
Topic |
Core rule |
| §A |
Documentation protocol |
Docs are a product: HISTORY.md, structural-analysis.md, and lessons-learned.md stay ≤ 1 commit behind the code |
| §A.3 |
Session briefs |
Every session starts from recorded state, not from memory — see proc-session-continuity |
| §B |
Agent behavior |
Agents declare a verifiable goal, stay in scope, and delegate outside their role |
| §C |
Context as graph |
Load the narrowest layer that answers the question; depth-first by default — see proc-sdd |
How to use the hierarchy
When rules conflict, the most specific wins:
engineering-principles (universal)
→ AI context file (project)
→ agent (role)
→ skill (how-to)
→ spec/task (unit of work)
Always-on vs on-demand (the "rules" layer)
be keeps the always-loaded layer thin so context stays cheap:
- Always on (the rules): these universal principles, the project's
CLAUDE.md, and each agent's prompt-defense guardrail banner — paid on every
call, so keep them short (proc-context-budget).
- On demand: skills (only the description loads until one triggers) and
their resource files. Detailed "how" lives here, not in the always-on layer.
There is deliberately no separate rules/ directory — it would duplicate
this digest and CLAUDE.md. Put a durable, always-true rule in CLAUDE.md
(project-specific) or a skill (reusable how-to) — never both.
Related skills
Security: sec-secrets-management, be-jwt-auth-patterns · Quality:
proc-code-review, qa-test-data-builders · Delivery:
proc-release-checklist, infra-ci-cd · Operations: ops-observability.
1---2name: engineering-principles3description: Use when making a design decision and needing the project-independent ground rules — UX, security, coupling, testing, observability, resilience, and the AI-assisted documentation protocol. One-page digest with pointers into the full engineering-principles.md document.4---56# Skill: Engineering Principles (Digest)78One-page digest of the universal principles in9[engineering-principles.md](../../engineering-principles.md) (the full10document ships at the base root). Load the full section only when the11decision at hand needs it.1213## The principles at a glance1415| § | Principle | Core rule |16|---|-----------|-----------|17| §1 | UX first | The interface exists to reduce the user's cognitive effort; accessibility (§1.5) is baseline quality, not a feature |18| §2 | Security by default | Validate server-side, hash passwords with modern KDFs, parameterize queries, audit dependencies (§2.8 supply chain) |19| §3 | Low coupling, high cohesion | Dependencies point inward (api → service → domain ← data); business logic never in controllers or repositories |20| §4 | Contracts and evolution | Public APIs are versioned (§4.4); breaking changes get a new version, never a silent change |21| §5 | Tests as specification | Every behavior has a test; tests are deterministic; coverage targets agreed, not implied |22| §6 | Performance is a feature | Paginate collections, index queried columns, measure before optimizing |23| §7 | Resilience | Timeouts on every external call; failures are expected inputs, not exceptions |24| §8 | Simplicity | The simplest design that meets today's requirement; complexity must pay rent |2526## AI-assisted work appendices2728| § | Topic | Core rule |29|---|-------|-----------|30| §A | Documentation protocol | Docs are a product: HISTORY.md, structural-analysis.md, and lessons-learned.md stay ≤ 1 commit behind the code |31| §A.3 | Session briefs | Every session starts from recorded state, not from memory — see `proc-session-continuity` |32| §B | Agent behavior | Agents declare a verifiable goal, stay in scope, and delegate outside their role |33| §C | Context as graph | Load the narrowest layer that answers the question; depth-first by default — see `proc-sdd` |3435## How to use the hierarchy3637When rules conflict, **the most specific wins**:3839```40engineering-principles (universal)41 → AI context file (project)42 → agent (role)43 → skill (how-to)44 → spec/task (unit of work)45```4647## Always-on vs on-demand (the "rules" layer)4849`be` keeps the always-loaded layer thin so context stays cheap:5051- **Always on (the rules):** these universal principles, the project's52 `CLAUDE.md`, and each agent's prompt-defense guardrail banner — paid on every53 call, so keep them short (`proc-context-budget`).54- **On demand:** skills (only the description loads until one triggers) and55 their resource files. Detailed "how" lives here, not in the always-on layer.5657There is deliberately **no separate `rules/` directory** — it would duplicate58this digest and `CLAUDE.md`. Put a durable, always-true rule in `CLAUDE.md`59(project-specific) or a skill (reusable how-to) — never both.6061## Related skills6263Security: `sec-secrets-management`, `be-jwt-auth-patterns` · Quality:64`proc-code-review`, `qa-test-data-builders` · Delivery:65`proc-release-checklist`, `infra-ci-cd` · Operations: `ops-observability`.
barcelosvinicius