John Lancaster
96 lines
4.3 KiB
Markdown
96 lines
4.3 KiB
Markdown
---
|
|
name: vscode-configuration
|
|
description: 'Create and troubleshoot VS Code workspace configuration for Python projects, with focused patterns for launch.json debugpy/FastAPI debugging and tasks.json task automation.'
|
|
argument-hint: 'What do you need: debug setup, FastAPI debug run profile, tasks.json automation, or all of them?'
|
|
---
|
|
|
|
# VS Code Configuration
|
|
|
|
Use this skill to design or repair repeatable VS Code workspace configuration for local development workflows.
|
|
|
|
## When to Use
|
|
|
|
- You need to create or fix `.vscode/launch.json` debug profiles.
|
|
- You need robust Python debugging with `debugpy`.
|
|
- You need FastAPI-specific launch profiles (app module, host/port, reload options, env files).
|
|
- You need `.vscode/tasks.json` build/test/run tasks and optional debug pre-launch integration.
|
|
- You need consistent workspace onboarding where users can run and debug from VS Code with minimal manual setup.
|
|
|
|
## Progressive References
|
|
|
|
Load only the page that matches the current request:
|
|
|
|
- Launch profile mechanics and debugpy patterns: [debug launch configurations](./references/debug-launch-configurations.md)
|
|
- FastAPI-focused debug profiles using debugpy: [FastAPI + debugpy launch patterns](./references/fastapi-debugpy-launch.md)
|
|
- Task runner setup in VS Code: [tasks.json project tasks](./references/tasks-json-configuration.md)
|
|
|
|
## Procedure
|
|
|
|
### Step 1: Capture the Runtime Shape
|
|
|
|
Collect the minimum context before writing files:
|
|
|
|
1. Python entry shape: module path vs script path.
|
|
2. Framework runtime: plain script, FastAPI with uvicorn, or mixed services.
|
|
3. Required environment: env file, env vars, cwd, and PYTHONPATH needs.
|
|
4. Task expectations: run app, run tests, lint/format, one-off setup.
|
|
|
|
Completion check: you can state exactly what command should run for debug and for task execution.
|
|
|
|
### Step 2: Create launch.json Profiles
|
|
|
|
1. Add at least one stable baseline profile before specialized variants.
|
|
2. Prefer module-based launches where packaging/import paths matter.
|
|
3. Keep debugger options explicit (`justMyCode`, `console`, `cwd`, `envFile`).
|
|
4. Add purpose-built profiles instead of one overloaded profile.
|
|
|
|
For concrete patterns, open [debug launch configurations](./references/debug-launch-configurations.md).
|
|
|
|
Completion check: selecting each profile starts the intended process without manual edits.
|
|
|
|
### Step 3: Add FastAPI Profiles When Needed
|
|
|
|
1. Use a dedicated FastAPI profile that launches `uvicorn` via module mode.
|
|
2. Keep host/port/reload/log-level as explicit args.
|
|
3. Include `jinja` debugging only if templates are in scope.
|
|
4. Add an attach profile when launching via external `debugpy` listener.
|
|
|
|
For complete examples, open [FastAPI + debugpy launch patterns](./references/fastapi-debugpy-launch.md).
|
|
|
|
Completion check: breakpoints hit in app code and startup path, and profile behavior matches dev vs non-dev expectations.
|
|
|
|
### Step 4: Add tasks.json for Repeated Commands
|
|
|
|
1. Create named tasks for run, test, lint, and docs/build steps as needed.
|
|
2. For Python projects, keep commands consistent with the repo package manager.
|
|
3. Use `problemMatcher` where parsers exist and background flags for long-running tasks.
|
|
4. Link debug profiles to tasks with `preLaunchTask` only when startup sequencing is required.
|
|
|
|
For task schema and examples, open [tasks.json project tasks](./references/tasks-json-configuration.md).
|
|
|
|
Completion check: tasks run from Command Palette and can be reused by debug profiles.
|
|
|
|
### Step 5: Validate End-to-End
|
|
|
|
1. Run each launch profile once.
|
|
2. Run each task once.
|
|
3. Verify paths, env files, and interpreter assumptions on a clean workspace reload.
|
|
4. Record any project-specific defaults in comments or docs if non-obvious.
|
|
|
|
Completion check: a teammate can clone the repo, open VS Code, and run/debug with only documented prerequisites.
|
|
|
|
## Decision Points
|
|
|
|
- If the app is imported as a package, prefer module launches over direct script paths.
|
|
- If runtime is started outside VS Code, add attach profile instead of forcing launch mode.
|
|
- If there are long-running dev servers, pair with background tasks.
|
|
- If test command differs by repo convention, mirror that command in tasks exactly.
|
|
|
|
## Output Contract
|
|
|
|
Return:
|
|
|
|
1. Created or updated VS Code config files and profile/task names.
|
|
2. Any assumptions (module path, env file, command runner).
|
|
3. Validation results and any unresolved decisions.
|