agentleFS
suraj-davariyasuraj-davariya/ai-job-search/CLAUDE.md

ai-job-search

CLAUDE.md22 starsChanged 5 months agoMITView on GitHub

This is CareerForge (working directory: ai-job-search) — an open-source, AI-powered job application framework designed to work for job seekers anywhere in the world, regardless of country, language, or local job market. It is built with Claude Code. The product is positioned against MadsLorentzen/ai-job-search (MIT) — a mature, Denmark-focused predecessor with the same drafter-reviewer + LaTeX architecture. CareerForge's wedge is country-agnostic from the core, a first-class tracking dashboard, and a cost-aware (opt-out) reviewer. See .reference/competitive-analysis/madslorentzen-ai-job-search.md for the full study. Build from…

The file

Show its rules and text

We split this CLAUDE.md into the rules it gives an agent

19 rules. About 0 are common, 10 are distinctive, and 9 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈10

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 9

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    Read these in order when you need to understand the product:

    line 26
  2. Very specific:

    Every requirement has a REQ-#### or NFR-#### ID.

    line 30
  3. Very specific:

    Test strategy, test plans, test case catalog (TC-#### IDs tracing to REQ-####), CI gates, and QA checklists.

    line 46
  4. Distinctive:

    i18n-ready from day one: All user-facing strings are externalized.

    line 84
  5. Very specific:

    Read the task description from the plan (docs/plan/).

    line 129
  6. Distinctive:

    Read the corresponding requirements and architecture docs.

    line 131
  7. Very specific:

    Read the relevant implementation guide in docs/development/.

    line 132
  8. Very specific:

    If helpful, check .reference/patterns/ for design pattern context.

    line 133
  9. Distinctive:

    Verify acceptance criteria from the requirement.

    line 135
  10. Very specific:

    Update docs/ if the implementation revealed a needed spec change.

    line 136
  11. Distinctive:

    Keep commits atomic — one logical change per commit.

    line 142
  12. Distinctive:

    Never commit API keys, personal data, or generated documents.

    line 151
  13. Distinctive:

    Do not copy code from external repositories.

    line 155
  14. Distinctive:

    Do not hardcode country-specific logic in core modules.

    line 156
  15. Very specific:

    Do not add features not captured in /docs/requirements/.

    line 157
  16. Distinctive:

    If a feature is needed, update the requirements first.

    line 158
  17. Very specific:

    Do not skip tests. Every REQ- should have a TC-.

    line 159
  18. Very specific:

    Do not commit .reference/, output/, or personal config.

    line 160
  19. Distinctive:

    Before finishing any task that changed observable behavior, re-read the affected README sections and reconcile them with reality.

    line 210

≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md 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
CLAUDE.md

CLAUDE.md — Project Memory & Agent Instructions

Identity

This is CareerForge (working directory: ai-job-search) — an open-source, AI-powered job application framework designed to work for job seekers anywhere in the world, regardless of country, language, or local job market. It is built with Claude Code.

The product is positioned against MadsLorentzen/ai-job-search (MIT) — a mature, Denmark-focused predecessor with the same drafter-reviewer + LaTeX architecture. CareerForge's wedge is country-agnostic from the core, a first-class tracking dashboard, and a cost-aware (opt-out) reviewer. See .reference/competitive-analysis/madslorentzen-ai-job-search.md for the full study.

Prime Directive

Build from the docs, not from external code. The canonical source of truth for what this product does, how it is architected, and how to build it lives in /docs. Every implementation decision flows from those documents. You never copy or reproduce code from other projects.

Documentation Map

Read these in order when you need to understand the product:

  1. Requirements → docs/requirements/00-index.md The complete functional and non-functional specification. Every requirement has a REQ-#### or NFR-#### ID.
  2. Architecture → docs/architecture/00-index.md Technology stack, component design, data model, API contracts, security model. Every element has an ARCH-#### ID and traces to the requirements it satisfies.
  3. Plan → docs/plan/00-index.md Milestones, work breakdown, sequencing, and the task backlog. Each task references REQ- and ARCH- IDs.
  4. Development → docs/development/00-index.md Coding standards, project structure, local setup, contribution workflow, and implementation guides per component.
  5. Testing → docs/testing/00-index.md Test strategy, test plans, test case catalog (TC-#### IDs tracing to REQ-####), CI gates, and QA checklists.
  6. Glossary → docs/glossary.md Canonical terminology. Use these terms consistently.

Private Research Reference

The .reference/ folder (gitignored) contains competitive analysis and pattern research gathered from studying existing products. This is internal inspiration material.

How to use .reference/ when developing:

  • You may read .reference/ to understand patterns, UX ideas, and architectural approaches that informed the product design.
  • You must NEVER copy code, UI copy, brand elements, or proprietary implementation details from reference material.
  • Any insight from .reference/ that affects the product must already be captured in /docs as an original requirement or architecture decision. If it isn't, update /docs first, then implement from the doc — not from the reference.
  • The flow is always: reference → insight → docs update → implementation. Never: reference → implementation.

Core Design Principles

1. Country-Agnostic by Default

This product serves job seekers globally. Every feature must work without assuming a specific country, language, job portal, or locale.

  • Job source providers are pluggable. The system defines a generic provider interface. Each country/region/job-board is a separate provider module that implements this interface. Adding a new country means adding a new provider, not changing core logic.
  • No hardcoded locales. Currency, date formats, salary ranges, language, and regulatory assumptions (e.g., CV vs résumé conventions, photo inclusion norms, GDPR) are configurable per-region, never baked into core code.
  • i18n-ready from day one. All user-facing strings are externalized. Default language is English; the architecture supports adding translations without code changes.

2. AI-Native Workflow

Claude is not a bolt-on — it is the core engine for job evaluation, CV/cover-letter generation, interview preparation, and career guidance. Design every workflow assuming an AI agent is the primary operator, with the human reviewing and approving outputs.

3. Privacy-First

Job search data is deeply personal. The product operates locally by default. User profiles, application history, and generated documents stay on the user's machine unless they explicitly choose otherwise.

4. Extensible & Open

The architecture supports community-contributed provider modules, CV/cover-letter templates, evaluation criteria, and locale packs. Design for extension: clear interfaces, plugin boundaries, and documentation that makes contribution easy.

Technology Stack

Canonical source: docs/architecture/technology-stack.md. Summary (keep this in sync if the canonical doc changes):

LayerChoiceWhy
RuntimeClaude Code CLIPrompt-as-code; workflow lives in Markdown, executed by the AI assistant. No compiled core.
Workflow definitionMarkdown (.claude/commands/*.md, .claude/skills/*/*.md)Human-readable, version-control friendly, modifiable without programming.
Document generationLaTeX — lualatex for CV (moderncv banking), xelatex for cover letter (custom class + fontspec)Two compilers required: fontawesome5 needs lualatex; custom fonts need xelatex. See ADR-0003.
TypographyLato + Raleway (bundled)Cover letter fonts
Utility scriptsPython 3.10+ (stdlib + optional openpyxl)Salary lookup, Excel→JSON conversion
Job portal adaptersTypeScript + Bun, per-adapter package.jsonPer-portal CLI scrapers, pluggable per ADR-0004
Data storageMarkdown / JSON / CSV — file-as-DBADR-0001. Small data, human-readable, git-tracked.
Version controlGitDistribution, history, audit

Hard rules from architecture:

  • ARCH-0001 Prompt-as-code · ARCH-0002 Skill composition · ARCH-0003 Agent isolation (drafter/reviewer)
  • ARCH-0004 File-as-DB · ARCH-0005 Graceful degradation · ARCH-0006 Human-in-the-loop · ARCH-0007 No fabrication

No global build step. No monorepo tooling. Each component installs independently.

Agent Workflow — How to Pick Up a Task

  1. Read the task description from the plan (docs/plan/).
  2. Identify the REQ- and ARCH- IDs the task references.
  3. Read the corresponding requirements and architecture docs.
  4. Read the relevant implementation guide in docs/development/.
  5. If helpful, check .reference/patterns/ for design pattern context.
  6. Implement from the docs. Write tests per docs/testing/.
  7. Verify acceptance criteria from the requirement.
  8. Update docs/ if the implementation revealed a needed spec change.

Commit Conventions

  • Format: type(scope): description (Conventional Commits)
  • Types: feat, fix, docs, test, refactor, chore, ci
  • Keep commits atomic — one logical change per commit.
  • Reference task/issue IDs in commit messages.

File & Folder Hygiene

  • Source code lives in src/ (or as defined in docs/development/).
  • Tests mirror source structure in tests/ or colocated as *.test.ts.
  • Generated outputs (CVs, cover letters) go in a gitignored output/ dir.
  • User profile/config goes in a gitignored config/ or .profile/ dir.
  • Never commit API keys, personal data, or generated documents.

What NOT to Do

  • Do not copy code from external repositories.
  • Do not hardcode country-specific logic in core modules.
  • Do not add features not captured in /docs/requirements/. If a feature is needed, update the requirements first.
  • Do not skip tests. Every REQ- should have a TC-.
  • Do not commit .reference/, output/, or personal config.

Keeping the Docs Site in Sync

The docs-site/ documentation website is part of the product's contract with its users, not an afterthought. Any change that alters observable behavior must update docs-site/ in the same change — never as a "later" task. Specifically:

  • New or changed command (/setup, /search, /apply, or a new one) → update the matching page under docs-site/content/docs/commands/ and the Quick Start.
  • New or changed skill/agent → update the relevant command/feature page that describes what the user experiences.
  • New or changed dashboard KPI or chart → update docs-site/content/docs/dashboard/ and the copied demo logic in docs-site/components/demo/domain/* and the demo-data.ts seed, so the live demo still matches the real dashboard.
  • Change to the job_search_tracker.csv schema (any of the 14 columns, the status enum, or the state machine) → update docs-site/content/docs/your-data.mdx, docs-site/content/docs/dashboard/applications-table.mdx, and the copied demo/domain/*.
  • New glossary term → add it to both docs/glossary.md and docs-site/content/docs/glossary.mdx.

The flow is: change the behavior → update the docs page (and any copied demo logic) → run vitest run in docs-site/ (the parity test fails if the copied components/demo/domain/* drifted from dashboard/lib/domain/*). A PR that changes behavior without updating docs-site/ is incomplete and CI (.github/workflows/docs-site.yml) will block it. Keep the mentor voice; never add self-congratulatory copy.

Keeping READMEs Current

The READMEs are the first thing a user reads — treat them as part of every change, not a "later" task. Any change that alters what the project does or how it is run must update the relevant README in the same change.

  • Root README.md — the product overview. Update it when a command, the dashboard, the directory layout, prerequisites, the privacy model, or the roadmap/status changes. Keep the "Roadmap" status column and the "Directory structure" tree honest (don't list something as planned once it ships, and don't omit a top-level folder that exists).
  • dashboard/README.md — how to launch and the security/privacy model. Update it when the start command/flags, ports, prerequisites, or the loopback/no-network/no-secrets guarantees change.
  • dashboard/ARCHITECTURE.md — update layers, file contracts, the perf baseline, or the Deviations log when those change.

Before finishing any task that changed observable behavior, re-read the affected README sections and reconcile them with reality. A change that leaves a README describing the old behavior is incomplete.

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.