# Fict Best Practices

> Fict compiler and runtime engineering guide for correctness and reliability. Use when implementing or reviewing Fict compiler transforms, runtime reactivity behavior, SSR/resume flow, devtools/playground integration, or release CI gates in Fict repositories.

- Skill: `marmelab/fict-best-practices` (Agent Skill, multi-file: 19 files)
- Install (CLI): `npx skillmds@latest add marmelab/fict-best-practices`
- Raw SKILL.md: https://api.skillmd.com/api/skills/marmelab/fict-best-practices/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: marmelab (https://skillmd.com/u/marmelab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/marmelab/fict-best-practices

---


# Fict Compiler and Runtime Best Practices

Production-focused guidance for engineering tasks across Fict compiler, runtime,
SSR, devtools, and release workflows. Rules are optimized for AI agents doing
code changes and reviews under correctness and regression-risk constraints.

## Rule Categories by Priority

| Priority | Category                            | Impact   | Prefix        |
| -------- | ----------------------------------- | -------- | ------------- |
| 1        | Compiler Guarantees                 | CRITICAL | `compiler-`   |
| 2        | Reactivity Semantics                | CRITICAL | `reactivity-` |
| 3        | Runtime Safety and Performance      | HIGH     | `runtime-`    |
| 4        | SSR and Resume Stability            | HIGH     | `ssr-`        |
| 5        | Tooling and DX Boundaries           | MEDIUM   | `tooling-`    |
| 6        | Verification and Release Discipline | CRITICAL | `quality-`    |

## Quick Reference

### 1. Compiler Guarantees (CRITICAL)

- `compiler-strict-guarantee-ci` - Enforce fail-closed guarantee mode in CI
- `compiler-macro-placement-top-level` - Keep macros at top-level component or hook scope
- `compiler-fail-closed-diagnostics` - Treat fallback diagnostics as blockers

### 2. Reactivity Semantics (CRITICAL)

- `reactivity-derived-values` - Rely on compiler-derived memoization and avoid stale snapshots
- `reactivity-no-state-escape` - Prevent state lifetime escape outside owning scope
- `reactivity-props-shaping` - Keep props/reactive object shaping analyzable

### 3. Runtime Safety and Performance (HIGH)

- `runtime-shared-state-primitives` - Use `$store`/`createSignal` for shared state boundaries
- `runtime-effect-cleanup` - Always return cleanup for subscriptions and async side effects
- `runtime-no-side-effects-in-memo` - Keep memo bodies pure and move effects to `$effect`

### 4. SSR and Resume Stability (HIGH)

- `ssr-resource-keying` - Key resources and align Suspense boundaries with async ownership
- `ssr-resume-snapshot-contract` - Preserve snapshot schema and loader failure semantics

### 5. Tooling and DX Boundaries (MEDIUM)

- `tooling-devtools-dev-only` - Keep devtools instrumentation development-only
- `tooling-playground-runtime-isolation` - Isolate playground features from production runtime code paths

### 6. Verification and Release Discipline (CRITICAL)

- `quality-regression-tests-for-bugs` - Add minimal regression tests for every fixed defect
- `quality-release-gates` - Run compiler/runtime gates before merge or release

## How to Use

Read rule files in `rules/` for detailed explanations and bad/good examples.
Use `AGENTS.md` when you want a single compiled document with all rules.

## Full Compiled Document

`AGENTS.md`