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…
In this repository4 other files it gives its agents.
- example-portalSkill
- career-developmentSkill
- job-application-assistantSkill
- job-scraperSkill
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
- Distinctive: line 26
Read these in order when you need to understand the product:
- Very specific: line 30
Every requirement has a REQ-#### or NFR-#### ID.
- Very specific: line 46
Test strategy, test plans, test case catalog (TC-#### IDs tracing to REQ-####), CI gates, and QA checklists.
- Distinctive: line 84
i18n-ready from day one: All user-facing strings are externalized.
- Very specific: line 129
Read the task description from the plan (docs/plan/).
- Distinctive: line 131
Read the corresponding requirements and architecture docs.
- Very specific: line 132
Read the relevant implementation guide in docs/development/.
- Very specific: line 133
If helpful, check .reference/patterns/ for design pattern context.
- Distinctive: line 135
Verify acceptance criteria from the requirement.
- Very specific: line 136
Update docs/ if the implementation revealed a needed spec change.
- Distinctive: line 142
Keep commits atomic — one logical change per commit.
- Distinctive: line 151
Never commit API keys, personal data, or generated documents.
- Distinctive: line 155
Do not copy code from external repositories.
- Distinctive: line 156
Do not hardcode country-specific logic in core modules.
- Very specific: line 157
Do not add features not captured in /docs/requirements/.
- Distinctive: line 158
If a feature is needed, update the requirements first.
- Very specific: line 159
Do not skip tests. Every REQ- should have a TC-.
- Very specific: line 160
Do not commit .reference/, output/, or personal config.
- Distinctive: line 210
Before finishing any task that changed observable behavior, re-read the affected README sections and reconcile them with reality.
≈ “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.
Files
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:
- Requirements →
docs/requirements/00-index.mdThe complete functional and non-functional specification. Every requirement has aREQ-####orNFR-####ID. - Architecture →
docs/architecture/00-index.mdTechnology stack, component design, data model, API contracts, security model. Every element has anARCH-####ID and traces to the requirements it satisfies. - Plan →
docs/plan/00-index.mdMilestones, work breakdown, sequencing, and the task backlog. Each task referencesREQ-andARCH-IDs. - Development →
docs/development/00-index.mdCoding standards, project structure, local setup, contribution workflow, and implementation guides per component. - Testing →
docs/testing/00-index.mdTest strategy, test plans, test case catalog (TC-####IDs tracing toREQ-####), CI gates, and QA checklists. - Glossary →
docs/glossary.mdCanonical 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/docsas an original requirement or architecture decision. If it isn't, update/docsfirst, 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):
| Layer | Choice | Why |
| Runtime | Claude Code CLI | Prompt-as-code; workflow lives in Markdown, executed by the AI assistant. No compiled core. |
| Workflow definition | Markdown (.claude/commands/*.md, .claude/skills/*/*.md) | Human-readable, version-control friendly, modifiable without programming. |
| Document generation | LaTeX — 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. |
| Typography | Lato + Raleway (bundled) | Cover letter fonts |
| Utility scripts | Python 3.10+ (stdlib + optional openpyxl) | Salary lookup, Excel→JSON conversion |
| Job portal adapters | TypeScript + Bun, per-adapter package.json | Per-portal CLI scrapers, pluggable per ADR-0004 |
| Data storage | Markdown / JSON / CSV — file-as-DB | ADR-0001. Small data, human-readable, git-tracked. |
| Version control | Git | Distribution, 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
- Read the task description from the plan (
docs/plan/). - Identify the
REQ-andARCH-IDs the task references. - Read the corresponding requirements and architecture docs.
- Read the relevant implementation guide in
docs/development/. - If helpful, check
.reference/patterns/for design pattern context. - Implement from the docs. Write tests per
docs/testing/. - Verify acceptance criteria from the requirement.
- 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 indocs/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 aTC-. - 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 underdocs-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 indocs-site/components/demo/domain/*and thedemo-data.tsseed, so the live demo still matches the real dashboard. - Change to the
job_search_tracker.csvschema (any of the 14 columns, the status enum, or the state machine) → updatedocs-site/content/docs/your-data.mdx,docs-site/content/docs/dashboard/applications-table.mdx, and the copieddemo/domain/*. - New glossary term → add it to both
docs/glossary.mdanddocs-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.
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
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.

