Skip to main content

AI Coding Guidelines

These are team-wide guidelines for using AI tools at Aliz. They apply regardless of which tool you're using.

Core Principles​

  • Treat output as a draft, not a deliverable. AI-generated code needs the same review as a PR from a new team member.
  • You own the code. If AI writes it and you accept it, it's yours — bugs, security holes, and all.
  • Context quality determines output quality. Vague prompts produce vague code. The more specific the input, the more useful the output.
  • Don't let AI bypass your process. AI-generated code still goes through code review, testing, and security considerations.

Context Management​

Give the AI what it needs to help you well:

  • Keep the relevant files open in the editor's context window.
  • Use workspace instruction files for persistent, repo-level context — see Prompt Engineering.
  • Break large tasks into focused sub-tasks — "refactor this one function" beats "rewrite the whole module."
  • Provide concrete inputs: types, interfaces, error messages, test cases — not vague descriptions.
tip

The more specific the context you give, the less the model has to guess, and the fewer hallucinations you'll get.

Reviewing AI Output​

  • Read every line. Skimming is how bugs get through.
  • Check specifically for: correctness, edge cases, error handling, security, and style consistency with the rest of the codebase.
  • Run the existing test suite after accepting changes.
  • For larger AI-driven changes, run git diff before staging to review the full set of changes.

Security Considerations​

Protecting Sensitive Information​

danger

Never paste secrets, API keys, credentials, or PII into any AI prompt — not even "just for context." This applies to all third-party AI tools, whether browser-based or in-editor.

Be cautious with NDA-bound client code and proprietary business logic. Check with your manager before using any AI tools on client projects or with proprietary code.

AI-Generated Code Security Risks​

AI models are trained on the entire internet, including insecure code. Common pitfalls to watch for:

  • SQL injection via string interpolation
  • Missing input validation and sanitization
  • Hardcoded credentials or tokens
  • Overly permissive CORS configuration

Watch for hallucinated package names — AI may suggest an npm install for a package that doesn't exist or, worse, is a typosquatted malicious package. Always verify package names on npmjs.com before installing.

caution

AI training data has a cutoff date. Code for rapidly-changing APIs (cloud SDKs, third-party integrations) may reference outdated patterns. Cross-check generated code against the official docs of whatever library or API is involved.

Content Exclusions​

GitHub Copilot supports content exclusions — organization-level rules that prevent certain files or repositories from being used as Copilot context. Excluded content won't appear in completions or chat responses.

This is configured by organization admins in GitHub.com → Organization Settings → Copilot → Content Exclusions, using patterns similar to .gitignore:

# Exclude sensitive directories
internal/secrets/**
config/production/**
**/credentials.*

Content exclusions operate at the GitHub organization level — individual developers don't need to configure anything locally. If you notice Copilot not suggesting completions for certain files, content exclusions may be the reason.

tip

If your project contains files that should never be sent to AI tools (credentials, proprietary algorithms, compliance-sensitive data), ask your org admin to add them to the content exclusion list rather than relying on individual developers to remember not to reference them.

Agent Security​

Agents add a risk that chat doesn't have: they act on what they read. Anything that ends up in the agent's context — a web page, an issue comment, a README in a dependency, an MCP tool result — can contain instructions, and the model may follow them.

Prompt Injection​

  • Treat fetched web content, issue/PR text, and MCP tool output as untrusted input, not instructions.
  • Be most careful when one session combines all three of: access to private data, exposure to untrusted content, and a way to send data out (web requests, pushing code, posting comments). Remove at least one of these for sensitive work.
  • If an agent suddenly proposes something unrelated to your task — reading ~/.ssh, posting to an unknown URL, editing CI config — stop and check what it just read.

Third-Party MCP Servers, Skills, and Agents​

MCP servers, skills, and agent definitions are code and prompts that run with your permissions.

  • Install them only from sources you trust, and read a skill's or agent file's content before adding it to a repo.
  • Pin MCP server packages to exact versions (no npx -y package without a version) — the same supply-chain rules as any other dependency.
  • Give each server the narrowest credentials that work: read-only tokens, single-repo scopes, no production databases.

Approval Modes​

Most agents can run without asking for approval ("auto-approve", "YOLO", "bypass permissions" modes).

  • Keep per-step approval on for anything that touches your real machine, credentials, or remote systems.
  • Auto-approve only inside a disposable environment — a dev container, a cloud agent sandbox, or a throwaway VM — with no access to secrets.
  • Prefer allowlisting specific safe commands (e.g. npm test, git status) over turning approvals off entirely.
caution

An agent with terminal access and auto-approve on can do anything you can do from that shell — including pushing to remote branches and deleting files. Scope its permissions before you start, not after something goes wrong.

When AI Helps Most​

  • Boilerplate and scaffolding — CRUD routes, form components, test stubs
  • Writing and expanding tests, especially generating edge-case inputs
  • Explaining unfamiliar code or third-party libraries
  • Writing and improving documentation and code comments
  • Refactoring well-understood, well-tested code
  • One-off scripts — data migrations, file processing, CI helpers

When to Be More Careful​

  • Complex domain logic with subtle business invariants
  • Security-sensitive code — auth, authorization, cryptography
  • Performance-critical paths where algorithmic choices matter
  • Anything that touches PII, payments, or compliance-regulated data