Skip to content

GuillemRoca/agent-skills-android / skills/context-engineering

context-engineering

Verified

Use when setting up a project for AI-assisted development or when agent output quality is poor. Guides writing rules files, structuring context, and managing the information agents need to produce accurate work.

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:

LevelSourceWhat It ProvidesPersistence
1Rules files (CLAUDE.md, .cursorrules)Tech stack, commands, conventions, boundariesPermanent
2Specs & architecture docs (SPEC.md, ADRs)Design decisions, constraints, rationalePer-project
3Source code (read specific files)Current implementation, patterns in useReal-time
4Error output & test resultsWhat's broken, what's expectedPer-session
5Conversation historyCurrent task contextEphemeral

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

  1. 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
  2. Don't dump everything — irrelevant context dilutes focus

Step 3: Surface Ambiguity

  1. 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?"
  2. Update rules files with the answer to prevent recurrence

Step 4: Include Examples

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

Step 5: Manage the Context Budget

The context window is a working desk, not a filing cabinet. Failed attempts, verbose tool output, and replaced drafts accumulate and fragment attention long before the window is full.

  1. Start trimming at ~75% capacity, not 100% — leave room to compress gracefully instead of cutting mid-task.
  2. Cut first: failed attempts and their error output (keep the conclusion), verbose tool output once you've extracted what you needed (full ./gradlew logs, adb logcat dumps, file listings), back-and-forth once the decision is made, and code drafts that were replaced.
  3. Protect until the end: the task definition and constraints, the error or failing test you're actively debugging, the current version of the file being edited, and any hard rules the agent must enforce.
  4. Compress before dropping. Reduce a long exploration to one sentence that keeps the decision:
    Before: [8 messages chasing a Hilt "MissingBinding" error — attempts, logs, dead ends]
    After:  "MissingBinding traced to TaskRepository bound in :feature:tasks only —
             moved the @Binds into :core:data's DataModule."
    
  5. Order for recency. Keep stable rules and specs at the start; put the active error, file, and task last, closest to where the model generates. Content in the middle of a long window is recalled least reliably.

Step 6: Hand Off at Task Boundaries

A fresh session is safe at a completed task boundary, not at an arbitrary token count.

  1. Before leaving a session, persist to the spec, plan, or task list: accepted scope and decisions; current task status and the next pending task; files changed and working-tree state; the exact verification commands and their outcomes; open questions, risks, and pending approvals. Commit only when the user or repo workflow authorizes it — otherwise record that changes are uncommitted.
  2. In the fresh session, read before acting: rules file, spec, plan, task status, and the actual git status. Re-run verification when its recorded baseline is missing, the code has moved, or the next task depends on it. Don't infer approval from a previous conversation unless a durable artifact records it.
  3. External restart loops (a harness that exits and resumes between tasks) must treat those artifacts and the repo state as the source of truth, keep human approval gates, and never read a process exit as "task passed."

Common Rationalizations

ShortcutWhy It Fails
"The agent should figure it out from the code"Agents sample context — they may read the wrong file and infer the wrong pattern.
"Rules files are overhead"30 minutes writing rules saves hours of correcting agent output.
"I'll fix agent mistakes manually"You'll fix the same mistakes every session. Rules fix them permanently.
"More context is better"Past ~2,000 lines, agents lose focus. Curate, don't dump.
"I'll clean up context when it's full"By then attention is already fragmented and quality drops abruptly. Trim at ~75%; compress rather than cut.
"The new session will remember what we agreed"It won't. Approvals, decisions, and verification state that aren't in a file don't exist for the next session.

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
  • Quality degrades mid-task as the session grows — failed attempts, replaced drafts, and verbose output never trimmed
  • New session acts on approvals or "tests pass" claims it can't find in any artifact

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)
  • In long sessions, failed attempts and replaced drafts are trimmed; the live error and task definition are protected and placed last
  • Session handoffs happen at task boundaries, with scope, task status, working-tree state, and verification results persisted in files
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall