Firebase Firestore skill for Codex

Done well means: each screen loads with a small, predictable number of document reads; security rules deny by default and are covered by emulator tests for every allowed and denied case; composite indexes live in version control; and no single document or index range takes more writes than Firestore can sustain.

Inspect first

1. Read AGENTS.md; open firebase.json, .firebaserc, firestore.rules and firestore.indexes.json.
2. Identify SDKs: Web modular SDK (firebase/firestore), Admin SDK (firebase-admin), mobile SDKs. The Admin SDK bypasses security rules entirely.
3. Find listeners (onSnapshot) and queries per screen; they drive cost.
4. Confirm the Emulator Suite runs locally (firebase emulators:start --only firestore); it needs Java and the Firebase CLI.

Model from screens

Write the screen/query table first:

Screen	Query	Docs read per load	Live?
Project list	orgs/{orgId}/projects where archived == false orderBy updatedAt desc limit 20	20	yes
Project page	orgs/{orgId}/projects/{id} + .../tasks limit 50	51	yes
My tasks across projects	collection group tasks where assigneeId == uid	<= 50	no

Rules:

• A document is the unit of read billing, security and contention. Group fields read together into one document; split fields with different access rules into different documents (for example users/{uid} public profile vs users/{uid}/private/settings).
• Subcollections for unbounded children (tasks of a project). Arrays only for small, bounded lists (tags, up to a few dozen).
• Documents max 1 MiB; keep them small since every read downloads the whole document.
• Denormalize what list screens display (projectName on a task) and decide how copies are updated (Cloud Function trigger or batched write at edit time).
• Collection group queries (collectionGroup(db, "tasks")) query every tasks subcollection; they need a collection-group index and rules written for the {path=**}/tasks/{taskId} form.
• Store ids of related documents, not references to fetch one by one; batch with in queries (up to 30 values) or restructure.

Queries and indexes

import { collection, query, where, orderBy, limit, startAfter, getDocs, getCountFromServer } from "firebase/firestore";

const q = query(
  collection(db, "orgs", orgId, "projects"),
  where("archived", "==", false),
  orderBy("updatedAt", "desc"),
  limit(20),
);
const page = await getDocs(q);
const next = query(q, startAfter(page.docs[page.docs.length - 1]));
const total = await getCountFromServer(q);   // aggregation: billed per batch of index entries, not per doc

• Single-field indexes are automatic. Equality plus orderBy on another field, or range filters with sorting, need a composite index. The error message contains a console link; instead of clicking it, add the index to firestore.indexes.json and deploy, so it is versioned:

{
  "indexes": [
    { "collectionGroup": "projects", "queryScope": "COLLECTION",
      "fields": [ { "fieldPath": "archived", "order": "ASCENDING" },
                  { "fieldPath": "updatedAt", "order": "DESCENDING" } ] },
    { "collectionGroup": "tasks", "queryScope": "COLLECTION_GROUP",
      "fields": [ { "fieldPath": "assigneeId", "order": "ASCENDING" },
                  { "fieldPath": "dueAt", "order": "ASCENDING" } ] }
  ],
  "fieldOverrides": [
    { "collectionGroup": "events", "fieldPath": "payload",
      "indexes": [] }
  ]
}

• firebase firestore:indexes prints the deployed index config, to reconcile with the file.
• Exempt large maps, long strings and fields never queried (fieldOverrides with empty indexes) to cut storage and write cost.
• Paginate with cursors (startAfter), never offset: skipped documents are still billed.
• in, not-in and array-contains-any accept up to 30 values; or queries are limited by the number of disjunctions they expand into.

Writes, transactions, hotspots

// Admin SDK: atomic multi-document write
const batch = adminDb.batch();
batch.update(projectRef, { taskCount: FieldValue.increment(1), updatedAt: FieldValue.serverTimestamp() });
batch.set(taskRef, task);
await batch.commit();

• Use FieldValue.increment for counters instead of read-then-write.
• Transactions read before they write and retry on contention; keep them small. Client SDK transactions fail offline.
• A single document sustains roughly one write per second. High-rate counters need a distributed counter (N shard documents summed on read) or aggregation queries.
• Sequential values in an indexed field (timestamps, incrementing ids) concentrate writes in one index range. For high write rates, exempt the field from indexing or add a random prefix/shard field. Ramp new collections gradually (start near 500 ops/s and grow about 50% every 5 minutes).
• Bulk deletes or backfills from scripts use BulkWriter in the Admin SDK; run against production only with explicit user confirmation, after testing on the emulator.

Security rules

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    function signedIn() { return request.auth != null; }
    function isMember(orgId) {
      return signedIn() && exists(/databases/$(database)/documents/orgs/$(orgId)/members/$(request.auth.uid));
    }

    match /orgs/{orgId}/projects/{projectId} {
      allow read: if isMember(orgId);
      allow create: if isMember(orgId)
        && request.resource.data.keys().hasOnly(['name', 'archived', 'ownerId', 'updatedAt'])
        && request.resource.data.ownerId == request.auth.uid
        && request.resource.data.name is string && request.resource.data.name.size() <= 120;
      allow update: if isMember(orgId)
        && request.resource.data.diff(resource.data).affectedKeys().hasOnly(['name', 'archived', 'updatedAt']);
      allow delete: if false;
    }
  }
}

• Rules are not filters: a query is allowed only if the rules can prove every possible result is readable. Queries must include the constraints the rules check (for example where("ownerId", "==", uid)).
• Validate shape on create and restrict changed keys on update; otherwise clients can write any field, including roles.
• get()/exists() calls count as billed reads and are capped per request (10 for single document requests, 20 for multi-document reads, transactions and batches).
• Store roles in documents the client cannot write, or in custom claims set by the Admin SDK.
• Deny by default: no allow read, write: if true, and no test-mode rules with expiry dates left in production.

For a catalog of rule patterns (role checks, owner-only fields, immutable fields, rate-limiting hints, collection group rules) and a full emulator test harness, read references/security-rules-patterns.md when writing or reviewing rules.

Cost control

• Every document returned is a read, including each document delivered to a listener when it changes and the initial snapshot. Listeners on large collections are the usual bill spike.
• Limit listeners to what is on screen; detach them on unmount.
• Offline persistence serves repeat loads from cache; resumed listeners within 30 minutes are billed only for changed documents.
• Use aggregation queries (count, sum, average) instead of downloading documents to count.
• Check usage in the console (Usage tab, Key Visualizer for hotspots) and set a budget alert.

Deploy

firebase emulators:exec --only firestore "npm test"     # rules + integration tests
firebase deploy --only firestore:rules,firestore:indexes  # confirm with the user first

Deploying rules takes effect within about a minute for new queries and can lock out clients; deploy only after emulator tests pass, and with user confirmation. Deploying needs network and Firebase credentials.

Verification

• Emulator rules tests cover allowed and denied cases for each collection (signed out, other user, member, owner, bad shape, forbidden field change).
• Each screen’s read count matches the query table (Emulator UI request log, or console usage).
• No query in the code requires an index missing from firestore.indexes.json.

Output

**Collections:** <path: fields, who writes, who reads>
**Queries:** <screen -> query -> index -> reads per load>
**Rules:** <summary per collection>, tests: <n allowed / n denied cases>
**Indexes:** firestore.indexes.json changes, exemptions
**Cost/hotspot notes:** <listeners, counters, sharding>