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:

Level	Source	What It Provides	Persistence
1	Rules files (CLAUDE.md, .cursorrules)	Tech stack, commands, conventions, boundaries	Permanent
2	Specs & architecture docs (SPEC.md, ADRs)	Design decisions, constraints, rationale	Per-project
3	Source code (read specific files)	Current implementation, patterns in use	Real-time
4	Error output & test results	What's broken, what's expected	Per-session
5	Conversation history	Current task context	Ephemeral

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`)