AI Coding Assistant Profile Switching and Prompt Management: A Practical Guide
This guide explains how to use a command-line AI coding assistant in a team workflow. It covers runtime checks and installation, editor integration, organizing endpoints and keys into profiles, safe profile switching and rollback, layered prompt templates for global/project/task constraints, secret protection and key rotation, and a pre-launch checklist.
AI Coding Assistant Profile Switching and Prompt Management: A Practical Guide
Large language model tools are now part of daily development workflows. Command-line AI coding tools can read code, run commands, and generate change suggestions, but teams often run into three problems: different projects need different endpoints and keys, prompt constraints are hard to standardize, and switching profiles can accidentally use a test key in a production project. This article uses a hypothetical command-line tool named aicli to describe a complete approach covering installation, profile switching, prompt layering, and security controls. In real use, replace the command name with the official name of your tool and follow its official documentation.
1. Preparation Before Installation
Terminals and permission models vary across operating systems. Before installation, confirm the following:
| System | Recommended installation method | Notes |
|---|---|---|
| macOS | Homebrew | Confirm that Xcode Command Line Tools are installed |
| Linux | System package manager or official installation script | Install under the user directory; avoid using sudo to modify global paths |
| Windows | npm bundled with Node.js, or the official installer | Run in PowerShell and confirm that PATH includes the npm global directory |
Tools often depend on a specific runtime version. For Node.js, check the version first:
node -vnpm -v
Then install the tool and confirm the version:
# macOSbrew install aicli# Linux or Windows, using global npm installationnpm install -g aicliaicli --version
The first login usually opens a browser for OAuth authorization, and credentials are stored in the user directory. After login, run a status check:
aicli status
This command should output the current profile name, endpoint, and authentication status. If the output says you are not logged in, run aicli login again.
There are three common installation problems. First, command not found usually means the global installation directory is not in PATH. Add the npm global directory to PATH and reopen the terminal. Second, permission errors during installation should be fixed by correcting the permissions of the npm global directory, not by relying on sudo long term. Third, login timeouts are often caused by proxy configuration. Check whether the HTTPS_PROXY environment variable points to a working proxy.
2. Integration with Code Editors
Mainstream editors support embedded terminals and task configuration. Once the tool is connected to the editor, it can read the current workspace file structure directly, so you do not need to copy code snippets manually. Suggested changes can be reviewed in a diff view before you decide whether to apply them.
For VS Code, you can add a task to the project’s .vscode/tasks.json to start the assistant with one command:
{"version": "2.0.0","tasks": [{"label": "Start AI assistant","type": "shell","command": "aicli","problemMatcher": []}]}
Then bind the task to a common key in the keyboard shortcut settings. Keep a separate .vscode directory for each project to avoid workspace settings from different projects affecting one another.
3. Managing Multiple Environments with Profiles
3.1 Directory Structure
Multiple configurations are best kept in a unified directory and named by environment and project. A recommended structure is:
~/.aicli/├── profiles/│ ├── prod-projectA/│ │ ├── config.yaml│ │ └── prompts -> ../../shared/prompts/projectA│ └── dev-personal/│ ├── config.yaml│ └── prompts -> ../../shared/prompts/personal├── shared/│ ├── prompts/│ └── skills/├── active -> profiles/dev-personal└── previous
shared/skills stores skill definitions centrally, and each profile references them through symbolic links. Update a skill once and all profiles take effect without editing each profile individually.
3.2 Example Configuration Fields
Each profile’s config.yaml should contain at least the following fields:
endpoint: https://api.example.com/v1key_ref: env:AICLI_KEY_PROD_Atimeout_seconds: 30retry: 2prompt_path: ./prompts/system.mdskills_dir: ../../shared/skillsexternal_services:- name: docscommand: docs-server --readonly
The key field contains only a reference, not plaintext. env:AICLI_KEY_PROD_A means the key is read from an environment variable at runtime. The following table explains the four configuration categories:
| Configuration category | Example fields | Purpose |
|---|---|---|
| Service access | endpoint, key_ref, timeout_seconds |
Determines where requests are sent and which key is used |
| External services | external_services |
Capability services connected through standard protocols, plus startup parameters |
| Prompts | prompt_path |
Project-level or global system prompt file |
| Skill extensions | skills_dir |
Link to the shared skills directory |
3.3 Switching Script
Manually changing the active link is error-prone. You can write a small script to handle switching consistently and record the previous profile name for rollback:
#!/usr/bin/env bashset -euo pipefailname="${1:?Usage: aicli-switch <profile-name>}"root="$HOME/.aicli"target="$root/profiles/$name"if [[ ! -d "$target" ]]; thenecho "Profile does not exist: $name" >&2exit 1fiprev="$(readlink "$root/active" 2>/dev/null || true)"printf '%s\n' "$prev" > "$root/previous"ln -sfn "$target" "$root/active"echo "Switched to: $name"
Save it as aicli-switch, put it in PATH, and it is ready to use.
3.4 Switching Workflow and Rollback
Before switching, end any assistant sessions still running in the terminal. Processes that have already started keep the old configuration; only new sessions read the new profile. The recommended order is:
# 1. Back up all profilescp -a ~/.aicli/profiles ~/backup/aicli-profiles-$(date +%F)# 2. Switch to the target profileaicli-switch prod-projectA# 3. Health check: confirm the profile name and endpointaicli status
The output of step 3 must match expectations. If the profile name or endpoint is wrong, roll back immediately:
prev="$(cat ~/.aicli/previous)"ln -sfn "$prev" ~/.aicli/activeaicli status
Before switching to a production profile, confirm that the endpoint in aicli status is the production endpoint to avoid using a test environment key by mistake.
4. Layered Prompt Templates
Prompts determine the quality of assistant output. Organizing them in layers reduces repeated constraints and lets constraints load automatically with the profile.
4.1 Global Layer
The global layer should contain only personal preferences, such as comment language, naming style, and commit message format:
# Global preferences- Use Chinese for comments and English camelCase for variable names.- Follow the Conventional Commits format for commit messages.- Do not introduce new third-party dependencies without discussion.
4.2 Project Layer
The project layer contains architecture conventions, technology stack, and prohibitions for that project:
# Project conventions: projectA- Technology stack: Node.js 20, TypeScript 5, Express.- Do not use eval or synchronous file read/write APIs when handling requests.- The test framework is Jest. New functions must cover both normal and error paths.
4.3 Task Layer
The task layer describes the goal of a single session. Write it in three parts: goal, constraints, and acceptance criteria. Each item should be verifiable:
Goal: Add threshold discount rules to the calcDiscount function in the order module.Constraints: Do not change the function signature; limit changes to the src/order/ directory.Acceptance criteria: All existing unit tests pass; add two new cases covering boundary amounts at the discount threshold.
4.4 Common Anti-Patterns
| Anti-pattern | Problem | Fix |
|---|---|---|
| Putting all constraints in the global prompt | Content unrelated to the current project consumes context window space | Place constraints at the layer closest to where they apply |
| Writing “write high-quality code” in the task layer | Completion cannot be judged | Rewrite as executable acceptance criteria, such as test cases and file scope |
| Keeping project rules only in personal notes | Team members use inconsistent baselines | Put project-layer prompts under version control |
5. Security and Misuse Protection
Keys are the highest-risk part of this approach. Control them across storage, injection, and auditing.
First, keys must not enter version control or prompt files. key_ref stores only a reference, and the real key is injected into environment variables by a secrets management service. Second, each team member should use independent credentials so that abnormal calls can be traced to an individual and revoked separately. Third, after switching profiles, run aicli status to verify the endpoint and profile name, and roll back if they do not match.
Key rotation steps:
- Generate a new key in the secrets management service and update the corresponding environment variable.
- End all running assistant sessions and reopen the terminal to load the new variable.
- Run
aicli statusand confirm that the status is normal. - Make a read-only test request to confirm that the new key works.
- Revoke the old key in the provider’s console.
Code generated by the AI assistant also requires review. All generated content must pass human review and automated tests before it is merged. In CI pipelines, add static scanning and dependency checks, especially for third-party dependencies added by the assistant.
6. Pre-Launch Checklist
- The runtime version meets the tool requirements, and
aicli --versionoutputs correctly - Login is complete, and
aicli statusshows normal authentication - Each profile’s
key_refpoints to an environment variable, and no plaintext key exists in the file - The switching script is in PATH, and the rollback command has been tested
- The
profilesdirectory has been backed up before switching - Project-layer prompts are under version control
- Static scanning and dependency checks are configured in CI
- Key rotation steps are documented in the team’s operations documentation
Checking each item against this list helps keep multi-environment switching, multi-key isolation, and prompt template management stable, so the team can develop on the same baseline.
