Maintaining Antigravity Quality in Long-Term Projects — 7 Principles for Session Design and Context Management

Antigravity works beautifully in the first few weeks of a project. Something shifts as development extends to three months, six months, a year.

"It was respecting our type definitions — now it's writing any everywhere." "It's ignoring the architecture we established." "It's reproducing bugs we already fixed."

This isn't Antigravity getting worse. It's context degradation. Antigravity reasons from what it can see. When what it sees is ambiguous, contradictory, or polluted with outdated patterns, the output follows.

Here are seven principles I've developed for maintaining quality in long-term projects.

Why Quality Degrades: 3 Root Causes

Before solutions, the causes.

Cause 1: Context Pollution

As a project evolves, you accumulate: rules from project inception, rules that were changed, experimental code that was never cleaned up, refactoring in mid-flight. Antigravity anchors to what it observes in current code. If the codebase reflects old patterns, those become "the project's standard."

Cause 2: agents.md Staleness

In most projects, agents.md (or AGENTS.md or .antigravity/rules) is written once and forgotten. Code evolves; documentation stays at the initial state. Antigravity encounters conflicting information and makes incorrect judgments about which to trust.

Cause 3: Technical Debt Accumulation

Type definitions spread across multiple locations. Slightly different implementations of the same logic. Commented-out code throughout. This "noise" degrades pattern recognition accuracy.

Principle 1: Treat agents.md as a Living Document

agents.md isn't the spec you write at kickoff. It's a document that must always reflect current reality.

The structure I use:

# PROJECT_NAME — Antigravity Context
 
## Current Architecture (keep this current)
Last updated: 2026-05-01
 
### Directory structure
src/
  features/      # feature-scoped modules
  shared/        # shared components
  infrastructure/# API clients, DB access
 
### Design decisions (ADR format)
- [2026-03-15] Data fetching: migrated SWR → TanStack Query
  Reason: Suspense mode support needed
  Impact: all src/features/*/hooks/*.ts
 
## Active dependencies and versions
(synced from package.json weekly)
 
## Naming conventions (currently active)
- Components: PascalCase
- Custom hooks: useCamelCase
- Constants: SCREAMING_SNAKE_CASE
- Note: camelCase deprecated April 2026, all-const going forward
 
## Negative Rules (what NOT to do)
- Never use `any` type (eslint-disable allowed only with explanatory comment)
- No console.log in production code
- No component files over 500 lines of logic

The Negative Rules section is the most impactful. "What not to do" constrains Antigravity more effectively than "what to do."

Principle 2: Split Sessions by Purpose

Long sessions are where context breaks down. Trying to design, implement, and debug in a single session produces confused output.

Separate by type: Design sessions — decide specifications, write no code. Implementation sessions — implement decided specs, add no new features. Refactor sessions — improve existing code, change no behavior. Debug sessions — diagnose and fix problems only.

Stopping "design and implement in the same session" alone produces a noticeable improvement in architectural consistency.

Principle 3: Inject Context at Session Start

Always open new sessions with this format:

## Today's work context

**Project**: [name]
**Current focus**: [specific feature or file]
**Progress so far**: 
- ✅ Auth flow complete
- ✅ Product listing API basic implementation
- 🔄 Cart feature in progress (CartContext created)
**Today's goal**: Add inventory check logic to CartContext
**Constraints to honor**:
- TypeScript types always explicit
- Inventory API calls only through src/infrastructure/inventory.ts
**Reference files**: src/features/cart/CartContext.tsx, src/infrastructure/inventory.ts

Skipping this and saying "add inventory check logic" causes Antigravity to write generic code without project context. With context injection, it works within your project's conventions and existing design.

Principle 4: Run Periodic Context Resets

Once a month, deliberately "reset" the context. Start a fresh chat. Paste only agents.md. Ask: "Read this document and ask me any questions about the project's current state." Antigravity will flag what's unclear or contradictory. Use those flags to update agents.md.

This tests whether agents.md alone provides sufficient context for someone (or something) with no prior exposure to the project. If it doesn't, the document has degraded.

Principle 5: Make Technical Debt Visible

Unresolved technical debt that Antigravity can't see causes unexpected behavior. Add a "Known Issues" section to agents.md to make intentional debt explicit:

## Known Issues (intentional technical debt)
 
### Priority: High
- [ ] src/features/auth/tokens.ts: JWT validation is simplified implementation
  Note: Signature verification omitted. Must fix before production launch.
 
### Priority: Medium  
- [ ] src/shared/hooks/useDebounce.ts: Timeout cleanup incomplete
  Note: Timer may persist after component unmount.
 
### Priority: Low (intentionally deferred)
- [ ] Hardcoded strings in some components (pre-i18n)

This tells Antigravity "this is intentional" — preventing it from attempting to fix known debt in ways that cause unexpected side effects.

Principle 6: Define Scope Explicitly for Refactor Sessions

Refactoring sessions are the most likely to introduce scope creep. "Improvement" and "feature change" are easy to conflate. Open every refactor session with this:

This session will perform refactoring only.
No feature additions, changes, or removals.
Target files: [file names]

Refactoring goal:
- [specific goal, e.g., improve type safety]

What must not change:
- Externally visible API behavior (inputs and outputs)
- File responsibilities

Please verify these rules are maintained throughout.

This explicit scope definition stops Antigravity from making changes it wasn't asked to make.

Principle 7: Build a Code Review Pattern

In long-term projects, it's easy to merge generated code without scrutiny. A consistent three-layer review catches quality degradation early:

Layer 1 — Type safety: No TypeScript errors, no any usage. Layer 2 — Naming conventions: Matches the rules in agents.md. Layer 3 — Architecture: Layer boundaries are respected (e.g., no direct API calls in components).

Automate this in CI:

# .github/workflows/quality-check.yml
- name: TypeScript strict check
  run: npx tsc --noEmit --strict
 
- name: ESLint (no-any)
  run: npx eslint src --rule '{"@typescript-eslint/no-explicit-any": "error"}'
 
- name: Import boundary check
  run: npx eslint src --rule '{"no-restricted-imports": ["error", {"patterns": ["../../"]}]}'

Looking back: Context Quality Determines Output Quality

Antigravity's output quality is the product of code quality and context quality. Clean code with a stale agents.md degrades output. A perfect agents.md with a debt-heavy codebase does the same. Maintaining both continuously is the substance of long-term project quality.

If you start with one thing from these seven principles: treat agents.md as a living document. Just that change alone substantially improves the consistency of Antigravity's work over the lifetime of a project.