A common failure mode I've observed in team-level AI assistant adoption is the assumption that a single, static set of custom instructions will suffice for all contexts. This leads to inconsistent output, ignored patterns, and ultimately, a degradation of trust in the tool—similar to the cost leakage we see from ungoverned Reserved Instance purchases. The key to enforcement, in both cases, is structured, granular, and context-aware governance.
Building an effective team 'style guide' is less about writing perfect prose and more about engineering a prompt-based configuration management system. The goal is to decouple core principles from context-specific rules, allowing the system to scale. I propose a three-layer model, analogous to infrastructure-as-code:
1. **Foundation Layer (Global `.gitconfig`):** Immutable team-wide rules placed directly in the assistant's primary custom instructions. This defines the irreducible core.
2. **Project/Service Layer (`Dockerfile`):** Dynamic context injected at the start of a conversation or via a pinned reference file. This defines *how* to execute within a specific codebase.
3. **Task Layer (Kubernetes Pod Spec):** Ephemeral, conversational instructions for the single unit of work. This defines the *what* for the current task.
Here is a concrete breakdown of each layer, with examples.
**Layer 1: Foundation Instructions**
These are the non-negotiables. They should be concise and focus on universal team norms.
```markdown
## Core Team Mandate
- **Output Format:** Always use the team's standard Jira ticket prefix (e.g., `[PROJ-123]`) in any proposed commit message.
- **Security Posture:** Never suggest code that hardcodes credentials, even as placeholders. Suggest environment variables or secret manager references exclusively.
- **Code Style:** Unless overridden by project context, follow the Google style guides for the relevant language.
- **Communication Protocol:** When uncertain, ask a single, concise clarifying question. Do not generate multiple hypothetical solutions.
```
**Layer 2: Project Context**
This is a JSON or YAML block that can be pasted into a new chat session or maintained in a project README for copying. It provides the environmental context.
```json
{
"project": {
"name": "billing-microservice",
"jira_prefix": "BILL",
"repository": "https://github.com/company/aws-billing-service",
"language": "Go",
"style_guide": "internal Go style guide v3.2 (see /docs/style.md)",
"aws_context": {
"primary_services": ["AWS Cost Explorer API", "AWS SDK for Go v2", "Amazon Aurora PostgreSQL"],
"cost_optimization_requirement": "All new Aurora queries must include a cost impact analysis in PR description."
},
"framework": "Chi (v1.5.4)"
}
}
```
**Layer 3: Task-Specific Guidance**
These are the instructions provided for the immediate task, which can now be much shorter because Layers 1 & 2 are already loaded.
```
"Refactor the function `calculateMonthlyCost` in `pkg/cost/processor.go` to use the AWS SDK for Go v2's pagination pattern. Include error handling for reservation API limits. Provide the changed code in a unified diff format."
```
The assistant, primed with Layers 1 and 2, will now:
* Generate a commit message prefixed with `[BILL-*]`.
* Follow the internal Go style guide.
* Use the correct AWS SDK version.
* Know to include a cost impact analysis for any new database query patterns.
* Produce a focused, diff-based output.
**Rollout & Measurement:**
Treat this like a CI/CD pipeline rollout. Create a versioned document for the Foundation Layer. For initial adoption, conduct a "cost audit" by having team members submit sample outputs from key tasks (e.g., "generate a CRUD endpoint") using the old method and the layered method. Compare the outputs for adherence to style, security, and utility. The measurable reduction in review cycles and stylistic corrections is your return on investment.
The critical success factor is making the context (Layer 2) easily accessible and updateable. It should be a living document owned by the tech lead, just like a `terraform.tfvars` file for your project's infrastructure. Without this, drift is inevitable.
-cc
every dollar counts