Thin-Pointer Design in AI-Job-Search: How to Eliminate Agent Configuration Drift

The thin-pointer design is a single-source-of-truth architecture that keeps all canonical data in one location and has every AI agent runtime environment point to that location instead of copying data locally.

In the MadsLorentzen/ai-job-search repository, developers face a common challenge: supporting multiple AI agent frameworks—Claude Code, Google Antigravity, Codex, Cursor, Gemini CLI—without duplicating configuration across each environment. The thin-pointer design solves this by centralizing all authoritative data and using lightweight references that always resolve to the current version.

What Is the Thin-Pointer Design?

The thin-pointer design is explicitly documented in AGENTS.md【AGENTS.md#L9-L19】 as the architectural foundation for multi-agent compatibility. Rather than embedding candidate profiles, workflow definitions, and portal configurations directly into each agent's runtime, the repository stores one authoritative copy and instructs every framework to reference it.

This pattern eliminates three common failure modes:

• Configuration drift – Local copies diverge over time
• Version mismatches – Agents run outdated instructions
• Maintenance overhead – Changes require edits in multiple places

The "thin" in thin-pointer refers to the minimal footprint at each agent's access point: a file path, URI, or symbolic reference rather than a full data payload.

Core Components of the Thin-Pointer Architecture

Personal Candidate Profile (CLAUDE.md)

All candidate information—résumé, contact details, education, target job title, location preferences—lives in CLAUDE.md. This file serves as the single source of truth for every agent that needs to act on behalf of the job seeker.

Skill-specific methods that extend this profile are stored under .claude/skills/job-application-assistant/. Any agent loading candidate data resolves to these same files regardless of framework.

import yaml
from pathlib import Path

# Load the central candidate profile (single source of truth)

profile_path = Path(__file__).parent.parent / "CLAUDE.md"
with profile_path.open() as f:
    profile = yaml.safe_load(f)          # assumes the file is YAML front‑matter

print(f"Applying for {profile['target_job_title']} in {profile['location']}")

Canonical Workflow Specifications (.claude/)

The step-by-step instructions for every pipeline stage—setup, scrape, rank, apply, upskill, interview—are stored as markdown files under .claude/skills/ and .claude/commands/. These specifications are framework-agnostic: they describe what to do, not which agent executes them.

# Example Bash command used by any agent framework

# The workflow spec lives under .claude/skills/job-scraper/

workflow_spec=".claude/skills/job-scraper/01-scrape.md"

# The agent runtime reads the spec and executes the defined steps

agent --run "$workflow_spec"

Portal Search Skills (.agents/skills/)

Each job portal CLI is defined once in .agents/skills/ using the portable Agent Skills format. The scraper workflow in .claude/skills/job-scraper/ discovers and invokes these skills dynamically.

// JavaScript snippet used by the Codex agent
import { runSkill } from '@agents/skills';

// The skill file is a thin pointer; the same file is used by all agents
const linkedinSkill = '.agents/skills/linkedin/skill.md';
runSkill(linkedinSkill, { query: "software engineer", location: "Berlin" });

Thin-Pointer Design Benefits for AI Agent Development

• Atomic updates – Change CLAUDE.md once, all agents see the new target location immediately
• Framework independence – New agent frameworks integrate by resolving the same pointers, not reimplementing logic
• Auditability – All configuration changes are version-controlled in one place
• Testing consistency – Staging and production environments use identical workflow specifications

File Structure Reference

File / Directory	Role
AGENTS.md	Describes the thin-pointer design and overall architecture
CLAUDE.md	Central candidate profile (personal data, preferences)
.claude/skills/	Canonical workflow specifications for pipeline stages
.claude/commands/	Reusable command definitions
.agents/skills/	Portable skill definitions for each job portal

Summary

• The thin-pointer design centralizes all configuration in CLAUDE.md and .claude/ to prevent duplication across agent frameworks
• Agent runtimes use file path references rather than embedded data, ensuring they always execute current specifications
• All workflow logic, portal skills, and candidate profiles follow the single source of truth principle
• This architecture is explicitly defined in AGENTS.md【AGENTS.md#L9-L19】 and implemented throughout the MadsLorentzen/ai-job-search repository

Frequently Asked Questions

What problem does the thin-pointer design solve?

The thin-pointer design eliminates configuration drift when running the same job-search workflows across multiple AI agent frameworks. Without it, each framework would require its own copy of candidate profiles and workflow definitions, leading to inconsistent behavior and maintenance burden.

Where is the thin-pointer design documented in the repository?

The design pattern is documented in AGENTS.md at lines 9-19, where it establishes the architectural principle of treating .claude/ and CLAUDE.md as the authoritative source that all agent frameworks reference.

Can I add a new agent framework without modifying existing files?

Yes. A new framework integrates by resolving the same thin pointers already established in .claude/skills/ and .agents/skills/. No changes to canonical files are required unless the framework needs custom capabilities not covered by existing specifications.

How do I update my candidate profile for all agents simultaneously?

Edit CLAUDE.md directly. Because every agent framework loads this file through a thin pointer, the update propagates immediately to Claude Code, Codex, Cursor, and any other configured runtimes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}