# AI Job Search Framework Architecture: A Modular Claude Code System for Autonomous Job Applications

> Explore the modular AI job search framework architecture. Discover how Claude Code powers autonomous job applications through four core layers for efficient candidate profile management and extension integration.

- Repository: [Mads Lorentzen/ai-job-search](https://github.com/MadsLorentzen/ai-job-search)
- Tags: architecture
- Published: 2026-08-28

---

**The AI job search framework is a thin-pointer, modular system that transforms Claude Code into a full-stack job-application assistant through four tightly-coupled layers: candidate profile management, command orchestration, pluggable extension points, and infrastructure utilities.**

This architecture enables autonomous sourcing, evaluation, and application generation without data duplication. As implemented in `MadsLorentzen/ai-job-search`, the framework treats Claude Code as the execution engine while maintaining a **single source of truth** across all operations.

## The Four-Layer Architecture

The repository organizes functionality into distinct layers that separate configuration from execution, allowing the AI agent to operate deterministically while remaining extensible.

### 1. Core Candidate Profile & Evaluation

All personal data, career goals, and evaluation criteria reside in the **candidate profile** ([`CLAUDE.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/CLAUDE.md)) and the structured skill files under **`.claude/skills/job-application-assistant/`**. This directory contains seven ordered modules:

- [`01-candidate-profile.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/01-candidate-profile.md) – Core biographical data
- [`02-behavioral-profile.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/02-behavioral-profile.md) – Interview responses and behavioral patterns  
- [`03-writing-style.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/03-writing-style.md) – Tone and stylistic preferences
- [`04-job-evaluation.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/04-job-evaluation.md) – **Scoring rubric and deal-breakers**
- [`05-cv-templates.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/05-cv-templates.md) – CV structure definitions
- [`06-cover-letter-templates.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/06-cover-letter-templates.md) – Cover letter blueprints
- [`07-interview-prep.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/07-interview-prep.md) – Interview preparation guidelines

These files constitute the *single source of truth*; every command reads from them but never duplicates data. The evaluation logic in **[`04-job-evaluation.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/04-job-evaluation.md)** drives automated scoring in the `/rank` and `/apply` commands, defining weighted criteria and language gates that filter opportunities.

### 2. Command Layer (Claude Code Commands)

High-level workflows are exposed as Claude Code commands stored in **`.claude/commands/`**. Each file represents a self-contained markdown "script" that orchestrates agent workflows:

- [`setup.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/setup.md) – Onboarding interview that populates profile files
- [`scrape.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/scrape.md) – Discovers and executes portal skills
- [`apply.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/apply.md) – Executes the drafter-reviewer-verifier loop
- [`rank.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/rank.md) – Batch-scores postings against evaluation criteria
- [`outcome.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/outcome.md) – Tracks application responses
- [`interview.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/interview.md) – Generates interview preparation materials
- [`gmail-sync.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/gmail-sync.md), [`notion-sync.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/notion-sync.md), [`html-report.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/html-report.md) – Integration and reporting utilities

Each command interacts with the file system and can trigger external compilers (LaTeX or Typst) to generate PDF artifacts.

### 3. Extension Points

The framework supports three primary extension mechanisms without requiring code changes:

**Portal Skills** – Job board integrations live under **`.agents/skills/`** (e.g., `jobbank-search`, `jobindex-search`, `linkedin-search`, `freehire-search`). Each skill follows a uniform contract: a `search` CLI executable, JSON or table output, and a [`SKILL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SKILL.md) description. The `/scrape` command automatically discovers installed skills using this contract.

**Document Templates** – Custom CV or cover-letter templates are registered via `/add-template` and stored under **`templates/`**. The framework supports any CLI-compilable toolchain, including LaTeX and Typst.

**Evaluation Criteria** – Users extend the fit model by editing skill files directly. Adding new deal-breakers to [`04-job-evaluation.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/04-job-evaluation.md) immediately affects all future `/rank` and `/apply` operations.

### 4. Infrastructure & Utilities

State management and tooling reside in dedicated directories:

- **State files** – Scraper outputs, seen-job lists, and application archives live in `job_scraper/`, `gmail_sync/`, `upskill/`, and the central **`job_search_tracker.csv`**
- **Helper scripts** – The `tools/` directory contains CI utilities like [`check_framework_version.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/check_framework_version.py), [`lint_skills.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/lint_skills.py), and [`security_guards.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/security_guards.py) that enforce version bumps and security policies
- **LaTeX assets** – Base templates in `cv/main_example.tex` and `cover_letters/cover_example.tex` (using `cover.cls`) provide compilation baselines

## Data Flow and Command Execution

The framework follows a linear pipeline where each stage consumes the single source of truth:

```bash

# 1. Initialize candidate profile

claude
/setup

# Populates CLAUDE.md and .claude/skills/* through interactive interview

# 2. Search configured portals

/scrape

# Discovers skills under .agents/skills/ and executes their search CLI

# 3. Rank opportunities (optional)

/rank

# Scores postings against 04-job-evaluation.md rubric

# 4. Apply to specific posting

/apply https://jobindex.dk/job/1234567

# Executes drafter → reviewer → PDF verification workflow

```

All commands execute inside Claude Code; the leading slash denotes the command syntax. The `/apply` command specifically implements a multi-agent loop: a **drafter** generates materials, a **reviewer** checks against profile constraints, and a **verifier** ensures PDF compilation succeeds.

## Extending the Framework

Adding new capabilities requires only file-system operations:

1. **New Job Portal**: Create a directory under `.agents/skills/[portal-name]/` containing a `search` executable and [`SKILL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SKILL.md)
2. **Custom Template**: Run `/add-template` to register LaTeX/Typst files in `templates/`
3. **Modified Scoring**: Edit [`04-job-evaluation.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/04-job-evaluation.md) to add weighted criteria or deal-breakers

The [`tools/lint_skills.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tools/lint_skills.py) script validates skill file syntax and settings during CI, ensuring extensions maintain the required contract.

## Summary

- The **AI job search framework** operates as a thin pointer system where Claude Code executes commands against immutable profile files
- **Configuration isolation** ensures [`CLAUDE.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/CLAUDE.md) and `.claude/skills/` serve as the single source of truth for all operations
- **Pluggable architecture** enables job portal integration through standardized skills in `.agents/skills/` without core code modifications
- **Document generation** supports LaTeX and Typst workflows with automated drafter-reviewer verification
- **State persistence** uses CSV trackers and directory-based archives for full auditability

## Frequently Asked Questions

### What makes this AI job search framework different from traditional job boards?

Traditional platforms provide search interfaces but require manual application drafting. This framework automates the entire pipeline—from sourcing through `.agents/skills/` integrations to generating tailored CVs via `/apply`—while maintaining your authentic voice through the profile files in `.claude/skills/`.

### How does the framework ensure consistency across job applications?

All commands reference the **single source of truth** in [`CLAUDE.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/CLAUDE.md) and the numbered skill files (01-07). When `/apply` generates a cover letter, it pulls from [`03-writing-style.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/03-writing-style.md) and [`06-cover-letter-templates.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/06-cover-letter-templates.md), ensuring every document reflects the same candidate profile without manual copy-pasting.

### Can I add custom job portals to the framework?

Yes. The **portal skills** architecture requires only a directory under `.agents/skills/` containing a `search` CLI tool and [`SKILL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SKILL.md) documentation. The `/scrape` command auto-discovers these skills, making the framework agnostic to specific job boards.

### What file format is used for the candidate profile?

The primary profile lives in **[`CLAUDE.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/CLAUDE.md)**, with structured evaluation data in Markdown files under `.claude/skills/job-application-assistant/`. This text-based approach enables version control, diff tracking, and easy editing while the [`tools/lint_skills.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tools/lint_skills.py) script enforces schema compliance.