Best Practices

Get consistently great results from Codistry. This guide focuses on clear prompts, precise context, safe automation, and fast iteration.

Prompt Engineering

Be specific about the goal, scope, files, constraints, and success criteria. The clearer the request, the less the agent has to guess.

Blueprint for a High-Quality Prompt

Goal:What should be true when we're done?
Scope: Which files/components/services can change?
Constraints: Compatibility, performance, security, style rules.
Edge cases: Inputs, limits, failure modes.
Deliverable: Code + tests + docs? A plan first?

Copy & paste skeleton:

Goal: <what to achieve>
Scope: Only touch <paths>; do not modify <paths>.
Constraints: <perf budget>, <API stability>, <style rules>.
Edge cases: <cases>.
Deliverable: Full implementation + tests + docs. No placeholders.
Start with: A short plan (files to touch, steps), then implement.

Examples

✅ Effective

Scoped change: “Refactor AuthService to async/await. Only modify src/auth/*. Keep public API stable.”
Defined outcome: “List all TODO comments and produce docs/todo.md with file:line and one-line summaries.”
Typed change: “Add User.role enum {'admin','user','guest'}in Prisma schema; generate migration; update guards.”

❌ Vague

“Fix the code.”
“Make it better.”
“Debug this.”

Decompose Big Work

Ask for a plan, then implementation in steps.

Plan: files to touch + risks.
Implement the smallest vertical slice.
Test + verify.
Iterate.

Force Completeness

“Provide the complete implementation (imports, types, error handling). No placeholders.”
“If a function is edited, show the entire function body.”
“List all files changed and why.”

Context Management

Give the smallest context that can produce the correct result, and reset when the thread drifts.

Targeted Context

Reference files explicitly: “Look at src/components/UserProfile.tsx.”
Point to patterns: “Match error handling in OrderService.”
Share constraints once: “v1 API must remain backward compatible.”

When to Start Fresh

Switching to an unrelated task.
Conversation has conflicting goals/history.
After a major milestone to prevent stale context.

Use Project Memory (Optional)

Enable Project Memory to persist architecture notes and relationships.
Reduces re-explanation across sessions.
Disable for throwaway experiments or high-sensitivity work.

Code Quality

Prevent Truncation & Partial Edits

“Return the full file when feasible; otherwise include every changed function in full.”
“No ‘…’ or omitted code blocks.”
“Include import updates and type changes.”

Build Quality In

Before:“List edge cases and how they're handled.”
During:“Rate confidence (1–10) and cite risks.”
After:“Run through a quick checklist: types, errors, logging, tests, docs.”

Documentation Sync

Update README for changed commands or env vars.
Add JSDoc to new/modified exported functions.
Record migrations and breaking changes in CHANGELOG.md.

Workflow Optimization

Safe Auto-Approvals (Read-Only)

Speed up low-risk steps by auto-approving read-only tools.

{
  "adronite-agent.autoApproveTools": {
    "read_file": true,
    "find_files_by_name": true,
    "grep_file_contents": true,
    "list_symbols_in_file": true,
    "get_file_diagnostics": true,
    "get_git_status": true
  }
}

Keep edit_file manual unless you're in a disposable sandbox. Terminal commands are gated separately by autoApproveCommands / denyCommands (token-prefix patterns), while globalAutoApprove approves every tool at once.

Streaming & Iterations

Enable streaming to see thinking sooner (interruptible).
Adjust iterations upward for multi-file refactors; downward for quick reads.

{
  "adronite-agent.streamingEnabled": { "anthropic": true, "openai": true },
  "adronite-agent.maxIterations": 25
}

MCP Extensions

Attach database/API/file-system tools for domain-specific tasks.
Auto-approve only safe read APIs; keep writes/manual approvals.

See the MCP Extensions guide.

Security Best Practices

Review Before Execute

Read diffs for file writes.
Confirm terminal commands, especially destructive ops.
Allow-list safe commands with autoApproveCommands and block dangerous ones with denyCommands (deny always wins).

Environment Profiles

Development (more permissive)

{
  "adronite-agent.autoApproveTools": {
    "read_file": true,
    "find_files_by_name": true
  }
}

Production (restrictive)

{
  "adronite-agent.autoApproveTools": {}
}

Sensitive Codebases

Prefer local models; disable telemetry if required.

{
  "adronite-agent.modelProvider": "custom-openai",
  "adronite-agent.openaiApiUrl": "http://localhost:11434/v1",
  "adronite-agent.model": "qwen2.5-coder",
  "adronite-agent.telemetryEnabled": false
}

Playbooks

Debugging

Read diagnostics in src/api/users.ts.
Analyze stack trace and hypothesize root cause.
Propose 2 fixes; choose one with rationale.
Apply fix; show full diff; add a minimal test.

Refactoring

Identify smells in UserService.ts and map to refactors.
Plan small, reversible steps.
Refactor with full function bodies and updated imports.
Run quick checks: types, tests, lints.

Feature Work

Design approach and list affected files.
Implement smallest vertical slice + tests.
Expand iteratively; update docs and changelog.

Troubleshooting

Common Anti-Patterns & Fixes

Symptom: Hallucinated paths/functions. Fix: Name exact files and APIs; ask to verify existence first.
Symptom: Partial code / missing imports. Fix: Require full function/file returns and import updates.
Symptom: Scope creep. Fix: Declare forbidden paths and restate scope per step.
Symptom: Conflicting context. Fix: Start a fresh chat and restate constraints.

Summary

Key Takeaways

Be explicit: Goal, scope, constraints, deliverable.
Start with a plan: Then implement in safe, small steps.
Tight context: Name files; reset when drifting.
Build quality in: Edge cases, confidence, verification.
Automate safely: Read-only auto-approvals; manual for writes/commands.
Secure by default: Review diffs and commands; use local models when needed.

Previous← Skills Runtime NextGuides →

Search Documentation