Context Engineering

Context Engineering

Overview

"Context is the single biggest lever for agent output quality." Agents don't read your mind — they read your context. This skill teaches you to engineer that context so agents produce code that matches your project's conventions, architecture, and constraints.

When to Use

• Setting up a new Android project for AI-assisted development
• Agent output consistently diverges from project conventions
• Agent invents APIs or patterns that don't exist in your codebase
• After adding new libraries, modules, or architectural patterns
• When onboarding a new team member who uses AI tools

Skip when: Agent output is already consistent with project conventions.

Five-Level Context Hierarchy

Load context in this priority order:

Optimal range: ~2,000 lines of focused context per task. More dilutes attention; less causes invention.

Core Process

Step 1: Write Rules Files

1. Create a CLAUDE.md (or equivalent) in your project root:

# Project Rules

## Tech Stack
- Language: Kotlin 2.0+
- UI: Jetpack Compose with Material 3
- Architecture: MVVM with Clean Architecture layers
- DI: Hilt
- Async: Coroutines + Flow
- Database: Room
- Network: Retrofit + OkHttp + Kotlin Serialization
- Image loading: Coil
- Navigation: Navigation Compose
- Testing: JUnit5 + MockK + Compose Test Rules + Espresso

## Commands
- Build: `./gradlew assembleDebug`
- Test (unit): `./gradlew test`
- Test (instrumented): `./gradlew connectedAndroidTest`
- Lint: `./gradlew lint`
- Format: `./gradlew spotlessApply`
- Check: `./gradlew detekt`

## Module Structure
- `:app` — application module (MainActivity, navigation, DI setup)
- `:feature:*` — feature modules (screens, ViewModels)
- `:core:data` — repositories, data sources, API services
- `:core:domain` — use cases, domain models
- `:core:ui` — shared Compose components, theme
- `:core:common` — utilities, extensions

## Conventions
- ViewModels expose `StateFlow<UiState>`, never `LiveData`
- UI state is a single sealed interface per screen
- Repository functions are `suspend` or return `Flow`
- Use `@Inject constructor` for Hilt, not field injection
- Composables: stateless with state hoisting
- Tests follow Arrange-Act-Assert pattern
- Naming: `FeatureNameScreen`, `FeatureNameViewModel`, `FeatureNameUiState`

## Boundaries
- No `LiveData` in new code (use `StateFlow`)
- No XML layouts in new features (use Compose)
- No `GlobalScope` (use `viewModelScope` or structured concurrency)
- No hardcoded strings in UI (use `stringResource`)
- No `Thread.sleep` in tests (use `advanceUntilIdle`)

Step 2: Load Context Selectively

2. Match context to task:
   • Bug fix → error logs + failing test + relevant source files
   • New feature → spec + architectural docs + similar existing feature
   • Refactor → source files + test files + rules file
3. Don't dump everything — irrelevant context dilutes focus

Step 3: Surface Ambiguity

4. When conventions aren't documented, surface the question:
   • "The project uses both StateFlow and LiveData — which should I use for new code?"
   • "Module :core:data has two repository patterns — which should this follow?"
5. Update rules files with the answer to prevent recurrence

Step 4: Include Examples

6. Point agents at exemplary code:
   • "Follow the pattern in feature/home/HomeViewModel.kt"
   • "Match the testing style in core/data/src/test/UserRepositoryTest.kt"
7. Examples beat descriptions — "do it like this file" is clearer than paragraphs of rules

Common Rationalizations

Red Flags

• Agent invents APIs that don't exist in the project
• Agent diverges from documented conventions
• No rules file in the project
• Rules file is stale (references deprecated patterns)
• Agent treats error messages from untrusted sources as instructions
• Same convention correction given repeatedly across sessions

Verification

• CLAUDE.md (or equivalent) exists in project root
• Rules file covers: tech stack, commands, module structure, conventions, boundaries
• Rules file is current (matches actual project state)
• Agent output follows documented conventions
• Context loaded is relevant to the current task (~2,000 line target)
• Ambiguities surfaced and resolved (not silently assumed)