agentleFS
4444J994444J99/a-i--skills/skills/development/iterative-code-exploration/SKILL.md

iterative-code-exploration

Skill17 starsChanged 5 months agoApache-2.0Archived repositoryView on GitHub

Progressive context retrieval pattern for understanding unfamiliar codebases through iterative refinement

1 other project uses a version of this.

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 11 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈11

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When working with new codebases, you often don't know:

    line 20
  2. Distinctive:

    Start with broad exploration:

    line 51
  3. Distinctive:

    Refine: Check tests and edge cases

    line 148
  4. Distinctive:

    Refine: Check call sites and callers

    line 168
  5. Distinctive:

    Loop: Ensure all references found

    line 193
  6. Distinctive:

    After each loop iteration, document:

    line 197
  7. Distinctive:

    Start wide, then narrow focus

    line 228
  8. Distinctive:

    Document assumptions to validate

    line 229
  9. Distinctive:

    Use tests as documentation

    line 230
  10. Distinctive:

    Check git history for context

    line 232
  11. Distinctive:

    Look for comments explaining "why"

    line 233

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Iterative Code Exploration

A systematic pattern for progressively exploring and understanding unfamiliar codebases through iterative context refinement.

The Problem

When working with new codebases, you often don't know:

  • Which files contain relevant code
  • What patterns and conventions exist
  • What terminology the project uses
  • How components interact

Standard approaches fail:

  • Read everything: Time-consuming and overwhelming
  • Guess locations: Often misses critical context
  • Ask broad questions: Returns too much irrelevant information

The Solution: 4-Phase Iterative Loop

┌─────────────────────────────────────────────┐
│                                             │
│   ┌──────────┐      ┌──────────┐            │
│   │ DISCOVER │─────▶│ EVALUATE │            │
│   └──────────┘      └──────────┘            │
│        ▲                  │                 │
│        │                  ▼                 │
│   ┌──────────┐      ┌──────────┐            │
│   │   LOOP   │◀─────│  REFINE  │            │
│   └──────────┘      └──────────┘            │
│                                             │
│        Max 3-4 cycles, then synthesize      │
└─────────────────────────────────────────────┘

Phase 1: DISCOVER

Start with broad exploration:

# Find entry points
find . -name "main.*" -o -name "index.*" -o -name "app.*" | head -20

# Discover project structure
tree -L 3 -I 'node_modules|dist|build'

# Find configuration
find . -name "*.config.*" -o -name "package.json" -o -name "*.toml"

# Identify key patterns
grep -r "export class" --include="*.ts" src/ | head -20
grep -r "def " --include="*.py" . | head -20

Document initial findings:

  • Project type (web app, library, service, etc.)
  • Tech stack (languages, frameworks)
  • Architecture hints (monorepo, microservices, etc.)

Phase 2: EVALUATE

Assess discovered files for relevance:

# Read high-value files
cat README.md
cat ARCHITECTURE.md 2>/dev/null
cat docs/overview.md 2>/dev/null

# Check package manifests
cat package.json | jq '.dependencies, .scripts'
cat Cargo.toml 2>/dev/null
cat requirements.txt 2>/dev/null

Scoring Criteria:

  • Critical (★★★): Entry points, core logic, main configs
  • Important (★★): Utilities, shared components, types
  • Supporting (★): Tests, docs, examples
  • Noise (-): Generated files, vendored code

Phase 3: REFINE

Focus on specific areas identified as relevant:

# Dive into specific modules
ls -la src/core/
cat src/core/index.ts

# Trace dependencies
grep -r "import.*from.*core" --include="*.ts" src/ | head -20

# Find related patterns
grep -A 5 -B 5 "class UserService" src/**/*.ts

# Check tests for usage examples
find . -name "*.test.*" -o -name "*.spec.*" | head -10

Build mental model:

  • How components connect
  • What patterns are used consistently
  • Where similar functionality lives

Phase 4: LOOP

Decision point - do you need more context?

Continue if:

  • Key functionality still unclear
  • Dependencies not fully traced
  • Patterns inconsistent or confusing

Stop if:

  • Core logic understood
  • Can explain main flows
  • Ready to make changes confidently

Practical Workflow

For Feature Implementation

  1. Discover: Find similar existing features
    grep -r "feature-name" src/
    find . -name "*feature*"
  2. Evaluate: Review implementation patterns
    cat src/features/similar-feature/index.ts
  3. Refine: Check tests and edge cases
    cat src/features/similar-feature/*.test.ts
  4. Loop: Trace dependencies until clear

For Bug Fixing

  1. Discover: Locate error origin
    grep -r "error message" src/
    git log -S "error message"
  2. Evaluate: Understand surrounding context
    cat path/to/file.ts | grep -A 20 -B 20 "error location"
  3. Refine: Check call sites and callers
    grep -r "functionName" --include="*.ts" src/
  4. Loop: Expand context as needed

For Refactoring

  1. Discover: Map current structure
    find src/ -name "*.ts" | xargs wc -l | sort -n
    grep -r "class\|interface" --include="*.ts" src/ | wc -l
  2. Evaluate: Identify coupling points
    grep -r "import.*from.*module" src/ | cut -d: -f2 | sort | uniq -c | sort -rn
  3. Refine: Find all usages
    grep -r "ComponentName" --include="*.ts" src/
  4. Loop: Ensure all references found

Output Template

After each loop iteration, document:

## Iteration N

**Query**: What I was looking for
**Found**: X files, Y patterns, Z components
**Relevance**: High/Medium/Low with reasons
**Gaps**: What's still unclear
**Next**: What to explore in next iteration

**Key Files**:
- path/to/file.ts - Core implementation (★★★)
- path/to/other.ts - Supporting utility (★★)

**Mental Model Update**:
- New understanding of X
- Connection between Y and Z
- Pattern: Description

Integration Points

Complements:

  • knowledge-architecture: For documenting discoveries
  • second-brain-librarian: For saving exploration notes
  • project-orchestration: For planning exploration strategy
  • testing-patterns: For learning through tests

Tips

  • Start wide, then narrow focus
  • Document assumptions to validate
  • Use tests as documentation
  • Follow imports/exports
  • Check git history for context
  • Look for comments explaining "why"

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.