Marcos Paulo
79920c9e6c
Three strands of work on the chapter surface, all reading from the same constraint: this site ships no runtime dependencies, so every effect below is native CSS or an .astro component. Motion (src/styles/motion.css, DrawRule.astro). A scroll-driven layer of reveals, hero parallax, section depth, and a hairline that paints itself along its path, scrubbed by `animation-timeline: view()` — 0KB against lottie-web's ~60KB gzipped on the main thread. Every scrubbed rule sits inside `prefers-reduced-motion: no-preference` and `@supports`, so a Firefox reader or an opted-out one gets the complete static page rather than one with holes in it. Ranges key to `cover 40%`-`cover 75%` where the motion is meant to be watched: `view()` ranges key to first visibility, which on a 2600px page is long before anyone is reading the section. `.agents/skills/motion/references/scroll-driven.md` records the technique and the two ways `pathLength` normalisation was broken while building it. Diagrams (StepFlow.astro, WorktreeMap.astro). The `.steps` stack on /skills/, /models/, and /agents/ becomes a numbered flow with connectors, and /agents/ grows the worktree map it was describing in prose — reusing the `trees` collection rather than a second set of strings. The map's static variant is gated one class deeper than full-guide's page styles, so the interactive copy renders byte-identical. Connectors are pseudo-elements, not SVG: a stretched path desynchronises its own dash pattern, and a straight line does not need one. Mermaid was considered and rejected at ~1MB of runtime. Retrieval practice (/rules/, /skills/). A "check yourself" section of native `<details>` question/answer pairs plus a citation row, both bilingual through the existing `data-copy` toggle, and both JavaScript-free. Two audit blind spots surfaced and are closed rather than worked around: `build.inlineStylesheets: 'never'`, because Astro inlined sheets under ~4kB and audit-ui.mjs reads its colour and size baseline from dist/_astro/*.css; and `--columns` declared in the grid components, because an element-level custom property is not a declaration the audit can resolve. legacy/styles/skills.css is renamed and imported for its side effect. Inside a *page*, `?url` resolves to that page's own CSS chunk whatever file it names, so the link pointed at the wrong asset and the sheet was emitted but never loaded — the package preview had been rendering unstyled and overflowing since the Astro cutover. verify.mjs gains 5 assertions for the recall sections and their Portuguese copy: 89 now, against the 84 baseline. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
136 lines
3.3 KiB
Plaintext
136 lines
3.3 KiB
Plaintext
Rules That Survive the Prompt — AI For Dummies
|
|
A
|
|
field guide
|
|
Pipeline
|
|
Skills
|
|
Examples
|
|
Recall
|
|
EN
|
|
/
|
|
PT
|
|
A real repository case study
|
|
Rules that
|
|
survive the
|
|
prompt.
|
|
Prompts ask for behavior. Repositories preserve it. The interview project combines written context, reusable skills, executable checks, commit hooks, and independent review so the rule is still present when the conversation is gone.
|
|
CASE / NETCRACKER
|
|
interview
|
|
8 skills · 3 agents · 4 enforcement layers
|
|
THE SHORT VERSION
|
|
A prompt is advice for one run. A repository rule is reusable context plus an executable boundary.
|
|
Enforcement pipeline
|
|
select a checkpoint
|
|
From intent to evidence
|
|
Five places
|
|
a rule can
|
|
hold.
|
|
Not every rule belongs in a hook. Put guidance where an agent can discover it, deterministic policy in a command, cheap checks at commit time, and independent judgment at review.
|
|
01
|
|
CONTEXT
|
|
AGENTS.md
|
|
→
|
|
02
|
|
SKILLS
|
|
.agents/skills
|
|
→
|
|
03
|
|
CLI
|
|
check:ui
|
|
→
|
|
04
|
|
COMMIT
|
|
Husky
|
|
→
|
|
05
|
|
REVIEW
|
|
pragent
|
|
Project-local skills
|
|
procedures born from repeated friction
|
|
Small instruction packages
|
|
Teach the trap.
|
|
Name the
|
|
trigger.
|
|
These skills are not downloaded magic. They are repository-specific procedures under
|
|
.agents/skills/
|
|
, distilled from mistakes, commands, and architectural decisions that kept recurring.
|
|
gate-discipline
|
|
prove green is real
|
|
parallel-agents
|
|
worktree per task
|
|
repo-db
|
|
query before crawling
|
|
tech-debt
|
|
separate line of work
|
|
skill-writer
|
|
repeat twice, encode once
|
|
frontend / go-api
|
|
stack-specific traps
|
|
Concrete examples
|
|
open the source, then adapt
|
|
CLI RATCHET
|
|
Debt may go down.
|
|
Never silently up.
|
|
pnpm check:ui
|
|
# raw buttons
|
|
# swallowed catches
|
|
# pages without h1
|
|
# hardcoded colours
|
|
Read the checker →
|
|
HUSKY / PRE-COMMIT
|
|
Fast checks before history.
|
|
pnpm exec lint-staged
|
|
node scripts/check-ui-contract.mjs
|
|
Read the hook →
|
|
COMMIT MESSAGE
|
|
Intent has a grammar.
|
|
pnpm exec commitlint --edit $1
|
|
feat: add interview timer
|
|
fix(api): scope session query
|
|
Read commitlint config →
|
|
INDEPENDENT REVIEW
|
|
A second reader checks intent.
|
|
.pr-review.json
|
|
├── focus
|
|
├── exclude_paths
|
|
├── languages
|
|
└── instructions
|
|
Read review policy →
|
|
Retrieval practice
|
|
answer before you open
|
|
Desirable difficulty
|
|
Close the
|
|
page.
|
|
Recall.
|
|
Retrieval practice — recalling an answer from memory before re-reading — is what builds long-term retention. Answer each question from memory first, then open it to check.
|
|
Where does a rule belong: context, skill, CLI check, or hook?
|
|
+
|
|
Guidance the agent must discover goes in AGENTS.md or a skill. Deterministic policy becomes a CLI command, cheap gates run at commit time, and judgment calls go to review.
|
|
Why does a skill need a trigger, not just a workflow?
|
|
+
|
|
The trigger says when to load it. Without one the skill either never fires or loads every time — and a skill that always loads is just a slower prompt.
|
|
What separates a repository rule from a prompt?
|
|
+
|
|
The prompt is advice for one run. The rule is reusable context plus an executable boundary — still present when the conversation is gone.
|
|
COPY / ADAPT
|
|
Ask your agent to map the enforcement stack.
|
|
Use this in the interview repository or adapt the path names to another project.
|
|
COPY PROMPT
|
|
↗
|
|
GO DEEPER
|
|
Read the implementation, not just this summary.
|
|
01
|
|
Repository context
|
|
AGENTS.md
|
|
02
|
|
Skill catalog
|
|
.agents/skills/
|
|
03
|
|
Design skills
|
|
skills/
|
|
03
|
|
Specialist agents
|
|
.claude/agents/
|
|
04
|
|
Staged-file policy
|
|
.lintstagedrc.cjs
|