200 lines
7.6 KiB
Markdown
200 lines
7.6 KiB
Markdown
# Project Context
|
|
|
|
## Purpose
|
|
|
|
I want to develop a framework that helps to write job applications. It should work similar to how OpenSpec works. Based on the on information about the job, a user provides, the framework will generate a CV, emails or a cover letter.
|
|
|
|
## Workflow
|
|
|
|
1 CHOOSE TEMPLATE LEVEL
|
|
|
|
- Quick: Email application, existing CV
|
|
- Standard: Your planned workflow
|
|
- Premium: + Research + CV customization
|
|
|
|
2 RESEARCH & CONTEXT
|
|
|
|
- Research job description + company
|
|
- Extract keywords/skills
|
|
- Analyze culture fit
|
|
|
|
3 PROPOSAL (= YOUR THOUGHTS)
|
|
|
|
- Why this position? (authentic!)
|
|
- What do you bring? (specific)
|
|
- How do you fit the company?
|
|
- Tone of Voice: formal/casual?
|
|
|
|
4 SPECIFICATION
|
|
|
|
- Define CV adjustments (which projects to emphasize?)
|
|
- Cover letter structure
|
|
- Format requirements (PDF/DOCX/Online)
|
|
- Key messages per paragraph
|
|
|
|
5 GENERATION
|
|
|
|
- Adapt CV
|
|
- Write cover letter
|
|
- Formulate subject line
|
|
- Write email body
|
|
|
|
6 QUALITY CHECK
|
|
|
|
- Fact check (company names, contact persons)
|
|
- Consistency (CV ↔ cover letter)
|
|
- Tone check (too stiff? too casual?)
|
|
- ATS optimization (if relevant)
|
|
|
|
7 FINALIZE
|
|
|
|
- Generate PDFs
|
|
- File names according to schema
|
|
- Send/Upload
|
|
|
|
8 TRACK & ARCHIVE
|
|
|
|
- Sent date, contact person
|
|
- Expected response deadline
|
|
- Follow-up reminder
|
|
- In case of rejection: Document learnings
|
|
|
|
## Tech Stack
|
|
|
|
- Claude Code as AI Agent.
|
|
- Markdown files to manage the specification
|
|
- Python for scripting.
|
|
|
|
## Project Conventions
|
|
|
|
### Code Style
|
|
- **Python Version**: 3.10+ (for modern type hints and match statements)
|
|
- **Formatting**: Use `black` for code formatting (88 character line length)
|
|
- **Linting**: Use `ruff` for fast linting and import sorting
|
|
- **Type Hints**: Mandatory for all function signatures; use `mypy` for static type checking
|
|
- **Naming Conventions**:
|
|
- Functions/variables: `snake_case`
|
|
- Classes: `PascalCase`
|
|
- Constants: `UPPER_SNAKE_CASE`
|
|
- Private methods: `_leading_underscore`
|
|
- **Docstrings**: Google-style docstrings for all public functions and classes
|
|
- **Import Organization**: Standard library, third-party, local (separated by blank lines)
|
|
|
|
### Architecture Patterns
|
|
- **Modular Design**: Separate modules for research, generation, formatting, and tracking
|
|
- **Template System**: Use Jinja2 for CV and cover letter templates
|
|
- **Pipeline Pattern**: Each workflow step is a distinct, testable function
|
|
- **Data Classes**: Use Python dataclasses for structured data (JobInfo, ApplicantProfile, GeneratedOutput)
|
|
- **Configuration**: YAML/TOML files for user profiles, templates, and settings
|
|
- **File Organization**:
|
|
```
|
|
src/
|
|
├── core/ # Core business logic
|
|
├── templates/ # Jinja2 templates for CVs, cover letters
|
|
├── research/ # Web scraping and analysis
|
|
├── generation/ # Content generation using Claude API
|
|
├── formatting/ # PDF/DOCX conversion
|
|
└── tracking/ # Application tracking and archiving
|
|
```
|
|
|
|
### Testing Strategy
|
|
- **Framework**: pytest for all testing
|
|
- **Coverage Target**: Aim for 80%+ coverage on core business logic
|
|
- **Test Types**:
|
|
- Unit tests for individual functions (research, generation logic)
|
|
- Integration tests for full workflow pipelines
|
|
- Snapshot/regression tests for generated content consistency
|
|
- **Fixtures**: Use pytest fixtures for sample job postings, user profiles
|
|
- **Mocking**: Mock external API calls (Claude API, web scraping) during tests
|
|
- **Test Data**: Store anonymized sample data in `tests/fixtures/`
|
|
|
|
### Git Workflow
|
|
- **Branching Strategy**: GitHub Flow (simplified)
|
|
- `main` branch is always deployable
|
|
- Feature branches: `feature/description` or `fix/description`
|
|
- Merge via pull requests (even for solo work, for documentation)
|
|
- **Commit Conventions**:
|
|
- Use conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`
|
|
- Keep commits atomic and focused
|
|
- Include OpenSpec references when implementing proposals
|
|
- **Versioning**: Semantic versioning (MAJOR.MINOR.PATCH)
|
|
- **Tags**: Tag releases with version numbers
|
|
|
|
## Domain Context
|
|
|
|
### Job Application Components
|
|
- **CV/Resume**: Structured document highlighting experience, skills, education
|
|
- Formats: PDF (standard), DOCX (editable), ATS-friendly plain text
|
|
- Sections: Summary, Experience, Education, Skills, Projects, Certifications
|
|
- **Cover Letter**: 1-page personalized motivation letter
|
|
- Structure: Opening, Why this role, What you bring, Cultural fit, Closing
|
|
- Tone variations: Formal (corporate), balanced (startups), casual (creative agencies)
|
|
- **Application Email**: Short intro email accompanying documents
|
|
- Subject line optimization
|
|
- Brief body (3-4 sentences max)
|
|
- Professional signature
|
|
|
|
### ATS (Applicant Tracking System) Optimization
|
|
- **Keyword Matching**: Extract keywords from job description and incorporate naturally
|
|
- **Formatting Rules**:
|
|
- Simple layouts (no tables, text boxes, headers/footers in CVs)
|
|
- Standard section headings
|
|
- Common fonts (Arial, Calibri, Times New Roman)
|
|
- **File Naming**: `FirstName_LastName_Position_Company.pdf`
|
|
|
|
### Cultural Considerations
|
|
- **German Market** (assumed based on "Bewerbungszauberer"):
|
|
- Photo on CV may be expected/common
|
|
- More formal tone than US applications
|
|
- Detailed work history with exact dates
|
|
- Certificates and credentials highly valued
|
|
- **Tone Analysis**: Detect company culture from job posting language and adapt
|
|
|
|
## Important Constraints
|
|
|
|
### Privacy & Data Protection
|
|
- **GDPR Compliance**: All personal data must be stored locally, never transmitted except to Claude API
|
|
- **No Cloud Storage**: Generated applications stored only on user's machine
|
|
- **API Key Security**: Claude API keys stored in environment variables or secure config, never in code
|
|
- **Data Retention**: User controls all archiving; no automatic telemetry or tracking
|
|
|
|
### Quality Standards
|
|
- **Factual Accuracy**: Never fabricate experience, skills, or achievements
|
|
- **Consistency**: All documents for one application must align (dates, job titles, responsibilities)
|
|
- **No Hallucinations**: Verify all company names, contact persons, and facts before generation
|
|
- **Human Review**: Generated content is a draft; user must review and approve
|
|
|
|
### Technical Limitations
|
|
- **API Rate Limits**: Respect Claude API rate limits; implement retry logic with exponential backoff
|
|
- **Cost Awareness**: Each application uses API tokens; provide cost estimates
|
|
- **Offline Capability**: Core template generation should work offline; only research requires internet
|
|
|
|
## External Dependencies
|
|
|
|
### AI Services
|
|
- **Anthropic Claude API**: Primary service for content generation, research analysis, and tone adaptation
|
|
- Models: Claude 3.5 Sonnet (primary), Claude 3 Haiku (quick operations)
|
|
- Usage: Cover letter writing, CV tailoring, keyword extraction, tone analysis
|
|
|
|
### Document Generation
|
|
- **ReportLab** or **WeasyPrint**: PDF generation from HTML/templates
|
|
- **python-docx**: DOCX file generation for editable documents
|
|
- **Jinja2**: Template engine for CV and cover letter structures
|
|
|
|
### Web Research (Optional)
|
|
- **BeautifulSoup4** + **requests**: Web scraping for company research
|
|
- **Playwright** or **Selenium**: For dynamic content if needed
|
|
- **Rate limiting**: Respect robots.txt and implement delays
|
|
|
|
### Data Management
|
|
- **PyYAML** or **tomli/tomllib**: Configuration file parsing
|
|
- **pydantic**: Data validation for user profiles and job information
|
|
- **SQLite**: Local database for tracking applications (lightweight, no server needed)
|
|
|
|
### Development Tools
|
|
- **black**: Code formatting
|
|
- **ruff**: Linting and import sorting
|
|
- **mypy**: Static type checking
|
|
- **pytest**: Testing framework
|
|
- **pytest-cov**: Coverage reporting
|