Imported from xhuandy666/career-copilot (
AGENTS.md). Install upstream withnpx skills add xhuandy666/career-copilot. Copyright stays with the author.
AGENTS.md
This file is for Codex, AI coding agents, and human collaborators working in this repository.
Scope: these instructions apply to the entire repository unless a more specific AGENTS.md is added in a subdirectory.
Start Here
Before making code changes, read:
README.mddocs/index.mddocs/vision.mddocs/roadmap.mddocs/architecture.mddocs/engineering-plan.mddocs/contributing.mddocs/testing-strategy.mddocs/risks-and-tech-debt.mddocs/adr/
When working on Web/API/product UI, also read:
PRODUCT.mdDESIGN.mddocs/v0.2-frontend-architecture-and-design.md
After reading, briefly summarize:
- current project direction
- key engineering rules
- modules affected by the task
- verification plan
Do this before modifying code, unless the task is a tiny documentation-only change.
Project Direction
Career Copilot Agent is a long-term job-search agent/workbench for AI, Agent, LLM application, RAG, and engineering-oriented algorithm internship candidates.
Current MVP:
- CLI commands:
career-agent project,profile,interview,all - LangGraph Studio graphs:
project_research_graph,profile_targeting_graph,interview_prep_graph - Core modules: project research, resume/profile targeting, interview preparation
- LLM providers: OpenAI, Anthropic, DeepSeek, Qwen, Kimi, OpenRouter, Ollama, LMStudio, custom OpenAI-compatible
Accepted direction:
- V0.2 Web workbench will use Next.js + FastAPI.
- Keep the Python
career_agentpackage as the reusable business/agent core. - Continue the rule: no configured LLM means no generated report.
- Storage is not finalized yet. Prefer SQLite-first, PostgreSQL-ready unless a design/ADR says otherwise.
Non-Negotiable Rules
- Do not hardcode user-specific target role, time budget, taste, run depth, company scope, model, or provider.
- Do not generate fake/template/offline heuristic reports when no LLM is configured.
- Do not claim real-time job openings, hiring probabilities, or guaranteed outcomes.
- Treat resumes, JDs, user profiles, interview feedback, and application records as sensitive data.
- Do not commit API keys, secrets, real resumes, private JDs, or personal user data.
- Do not revert unrelated user changes in the working tree.
Ask Before These Changes
Pause and ask for confirmation before:
- large refactors
- deleting files or removing legacy modules
- adding major dependencies
- changing database schema or persistence strategy
- changing core LangGraph graph architecture
- changing CLI argument names or report file formats
- changing the "LLM required" product decision
Low-risk documentation, tests, small bug fixes, and local consistency improvements can proceed directly.
Architecture Rules
- Keep entrypoints thin: CLI, Studio, and future FastAPI routes should call shared business services.
- Keep defaults in
career_agent.defaults, not scattered through prompts or handlers. - Keep LLM provider logic in
career_agent.llm. - Keep structured task prompting and schema expectations in
career_agent.llm_tasks. - Validate LLM outputs before writing reports or returning API responses.
- For judgment-heavy Agent behavior, do not let keyword-only heuristics stand in for semantic understanding. Use deterministic rules for evidence collection, guardrails, and validation; use LLM-backed structured tasks for user-fit reasoning, project understanding, ranking rationale, and modification planning.
- For project discovery, GitHub/search modules should produce real evidence and objective health signals. LLM modules may plan searches, profile repositories, evaluate fit, and explain rankings, but must not invent repositories, URLs, or unverified evidence.
- New modules must define inputs, outputs, configuration, failure modes, privacy impact, and tests.
Testing And Verification
Before claiming completion, run the relevant checks:
.venv/bin/python -m pytest -q
.venv/bin/ruff check src/career_agent tests
.venv/bin/langgraph validate
For documentation-only changes, at least inspect the changed Markdown and state that code tests were not necessary.
For LLM-related changes:
- use mock LLM tests in CI/local unit tests
- verify missing-provider behavior
- verify JSON parsing or schema validation
- verify exact question counts for interview generation
For future Web/API changes:
- add backend tests for FastAPI routes
- add contract tests for request/response payloads
- verify file upload, report generation, error states, and data deletion behavior
Collaboration Style
Prefer small, reviewable changes. Explain why a change is needed, what tradeoff it makes, and how it was verified.
PRs or handoff summaries should include:
- what changed
- why it changed
- files touched
- tests/checks run
- remaining risks
- decisions needed from the project owner
