Layered Design and Maintenance of AI Coding Assistant Project Configuration

Why Configuration Gets Messy

Early on, many teams write a single project brief and start collaborating with an AI coding assistant. That works at small scale. As the codebase and headcount grow, the brief balloons, rules scatter, nobody remembers what automation does, and one change ripples elsewhere.

The root cause is usually missing structure, not a wrong rule. Unclassified information makes it hard to tell what is still valid, what is stale, and which operations are allowed. The first step is a clear layering, not endless append-only content.

Two Layers: Guidance vs. Control

Assistant configuration answers two kinds of questions.

Category	Question	Typical content	Nature
Guidance	What should the tool know?	Background, stack, directory conventions, style, collaboration	Mostly prose for the model
Control	What may the tool do?	Allowed/denied operations, auto-run scripts, project behavior	Structured config the tool enforces

Guidance only influences judgment; the model can still ignore or misread it. Control is a hard boundary—for example, blocking deletes of a given directory before execution. Put must-follow constraints in control; put context-heavy norms in guidance. Stabilize these two layers before adding more directories. Everything else supplements them.

A Team-Oriented Directory Layout

File names are illustrative; adapt to team habit.

project-root/
├── PROJECT.md              # Shared project instructions, versioned
├── PROJECT.local.md        # Personal overrides, not committed
└── .assistant/
    ├── config.json         # Control: permissions, hooks, behavior, versioned
    ├── config.local.json   # Personal control, not committed
    ├── rules/              # Modular rules
    ├── hooks/              # Automation scripts
    ├── commands/           # Reusable prompt workflows
    ├── skills/             # Packaged complex workflows, load on demand
    └── agents/             # Specialized sub-agent roles, load on demand

local files hold personal preferences (machine paths, editing habits, debug flags). Keep them out of version control so they do not affect others.

Responsibilities and How to Write Each Part

Main instructions and modular rules

The main instruction file should cover only what every member needs: goals, core directories, common build/test commands, and non-negotiable conventions. Aim for about one screen.

If a rule applies only to a module, split it into rules/ with topic names, e.g. rules/api-design.md, rules/database-migration.md. You can change one module without scanning the whole brief, and newcomers can search by topic.

Write verifiable requirements. Avoid “try to” or “appropriately.” “API responses must use the project error-code structure” is more enforceable than “pay attention to API conventions.”

Control-layer config

Declare permission boundaries. Field names depend on the tool:

{
  "permissions": {
    "allow": [
      "read:src/**",
      "run:unit-tests"
    ],
    "deny": [
      "write:migrations/applied/**",
      "run:deploy-*"
    ]
  }
}

Use least privilege. Default to read and local tests; approve writes, deploys, and deletes case by case. Explicitly deny high-risk targets such as applied migrations and production deploy entry points.

Hooks

Hooks run automatically around events (format on save, static analysis before commit). They cut repetition but hide side effects. Conventions:

• Prefer read-only checks (lint, types); mutate files only when necessary.
• Keep scripts idempotent.
• Do not read or print secrets, and do not hit the network unless required and reviewed.
• Document trigger and purpose in one line next to each hook.

Example check-only script:

#!/usr/bin/env bash
# Check only; do not modify files
set -euo pipefail
npm run lint --silent

Command templates

Store repeated workflows such as “generate API docs” or “review current branch.” Each file should state goal, inputs, steps, and output format.

# Review current changes
Goal: Check uncommitted changes against conventions in rules/.
Steps:
1. List files changed in this work.
2. For each file, check naming, error handling, and test coverage.
3. Report findings as severe / suggestion / note, with file and line numbers.

Commands are valuable because they standardize work; maintain them with the rest of the spec. Delete unused commands instead of keeping them “just in case.”

Skills

Skills wrap multi-step flows that need several sources (e.g. a schema change following a fixed process). Load them only when needed so they do not consume everyday context.

Create a skill only after the same flow has been repeated and the steps have stabilized. Early packaging raises maintenance cost and drifts from practice when the process changes.

Sub-agent roles

Sub-agents are single-responsibility roles (reviewer, test author, docs editor). Clear boundaries avoid one role juggling many jobs.

Define scope, permissions, and output requirements. Read-only roles (reviewers) must not have write access; encode that in the control layer as well.

Add Layers by Stage

Do not finish configuration in one pass. Add a layer only after the previous one is stable:

1. Main instructions and basic permissions. Overview, directory conventions, build commands; allow read and local tests; deny writes to critical directories.
2. Rule split and personal overrides. When the main file exceeds one screen or module rules conflict, move them to rules/ and add local override files.
3. Hooks and command templates. When checks are routinely skipped or a workflow repeats, add hooks and commands.
4. Skills and sub-agents. When complexity justifies packaging, or review/test roles need a stable split, introduce skills and sub-agents.

At the end of each stage, verify the previous layer still holds. Deleting stale rules keeps config clearer than stacking new ones.

Security and Maintenance

Treat config as an asset:

• Least privilege. Grant only what the task needs; high-risk operations are denied by default.
• No secrets in repo. Keys, tokens, and internal addresses come from env vars or a secret manager, not guidance or control files.
• Review changes. Config changes go through merge requests like code.
• Periodic cleanup. Quarterly, drop unused or outdated rules, commands, and hooks.
• Owners. Each directory has a responsible person so issues can be traced.

Common Mistakes

Building every directory at once. Premature structure forces people to learn unused pieces and lowers adoption. Follow the staged path above.

Mixing guidance and control. Hard bans in prose only may be ignored. Put hard boundaries in the control layer.

Contradictory rules. Conflicting requirements in main instructions, module rules, and local overrides make behavior unpredictable. One authoritative source per topic; others should reference it.

Opaque hook side effects. Unexplained auto-edits confuse people. Document hooks and prefer checks over mutation.

Committing personal settings. Local paths and debug flags in the repo affect everyone. Ignore personal files and document their purpose.

The goal is stable collaboration, not a complete tree. With clear layers, explicit boundaries, and regular maintenance, configuration stays readable and controllable as the project grows.