Fine-Tuning Your Repo for AI Agents

WHY

Gives the agent a "brain" for your repo, reducing guesswork and errors. It's the highest-leverage asset you can create.

HOW

# AGENT.md / CLAUDE.md
## Mandatory Workflow
1. Before editing: `just analyze`
2. After editing: `just format`
3. Before merging: `just check`

## Architecture
- Be explicit about the project structure and data flow.
- If this is Flutter, note BLoC as one implementation detail — not the whole thesis.
- Never call the API directly from UI.

WHY

Tools tell the agent how to work. Repo memory tells it what the product means, what trade-offs matter, and which words are canonical.

HOW

# CONTEXT.md
## Product Principles
- Fast feedback beats perfect planning.
- Protect user trust over short-term growth.

## Domain Language
- Workout Plan: scheduled training intent.
- Session: one completed workout occurrence.

## Definition of Done
- Code, tests, docs, and acceptance criteria pass.

## Rule Changes
- Version conventions with ADRs or dated notes.

WHY

Creates simple, memorable aliases for complex or hard-to-remember commands. It becomes the agent's universal entry point, and recipes can compose other recipes for multi-step workflows.

HOW

# justfile

fmt:
    dart format .

analyze:
    flutter analyze

test:
    flutter test

check: fmt analyze test
    @echo "All checks passed"

new-feature name:
    just scaffold {{name}}

WHY

Automates creating boilerplate for features, components, or logic patterns. This ensures speed and architectural consistency.

HOW

Expose generators via your task runner. Instead of a multi-step prompt, the agent runs a single command.

$ just new:bloc user_profile
> Creates view, cubit, state, and test files.

WHY

Enforces code quality and a consistent style automatically. The agent learns your coding style by conforming to the linter.

HOW

# .analysis_options.yaml (Flutter)
include: package:very_good_analysis/analysis_options.yaml
linter:
  rules:
    - prefer_const_constructors
    - avoid_dynamic_calls

WHY

Makes quality gates mandatory. The agent (and you) *cannot* commit broken, unformatted, or non-compliant code.

HOW

Mirror CI locally so the agent fails before it can create a bad commit. Hooks should call the same task runner entry points used elsewhere.

# .pre-commit-config.yaml
-   repo: local
    hooks:
    -   id: repo-check
        name: Repo Check
        entry: just check
        language: system

WHY

Agents improve fastest when feedback is stable, local, and repeatable. Flaky tests teach the wrong lesson; deterministic checks make regressions obvious.

HOW

# Testing contract
- Unit tests for business rules
- Golden/snapshot tests for UI and outputs
- Fixture-based integration tests
- Frozen clocks, seeded randomness, no live APIs

# Agent Definition of Done
1. Add/update tests for the behavior changed
2. Run `just check`
3. Include validation notes in the MR

WHY

Faster, more targeted file search and code analysis than `find` or `grep`. Less noise for the agent means better results.

Prefer non-interactive, composable commands the agent can chain and reason about.

HOW

Use modern CLI tools. An agent proficient with these is more effective.

# Ripgrep for code search (fast, respects .gitignore)
$ rg "MyFunction"

# fd for file finding (fast, intuitive)
$ fd ".dart" -x flutter analyze

WHY

A standard process for branches and commits makes the agent's behavior predictable and the git history clean and useful.

HOW

Pick and document one branching strategy. Trunk-based is usually the default. Use feature, release, or hotfix branches only when they belong to a documented flow.

# Branching strategy
Primary: trunk-based development

# Branch Naming
feature/<issue>-<slug>
release/<version>
hotfix/<issue>-<slug>

# Workflow options
- GitHub Flow / GitLab Flow for review-driven changes
- Git Flow only if you truly need release branching

# Commit Messages
feat(auth): add google sign-in

WHY

Structures user requests and merge requests to provide summary, steps to reproduce, expected behavior, acceptance criteria, and constraints upfront. It's the agent's "briefing document."

HOW

Create templates in your git provider.

# .gitlab/issue_templates/bug.md
### Summary
(A clear and concise summary of the bug)

### Steps to reproduce
1. Go to '...'
2. Click on '....'

### Expected behavior
(...)

### Acceptance criteria
- [ ] ...
- [ ] ...

# .gitlab/merge_request_templates/default.md
### Summary of changes
(...)

### Validation
- [ ] ...
- [ ] ...

### Notes for reviewer
(...)

WHY

A predictable structure makes it easy for the agent to locate relevant files, understand data flow, and know where a change belongs. Consistency is key.

Document modules, boundaries, and ownership. If you're in Flutter, mention BLoC as one implementation detail — not the whole architecture story.

HOW

Choose an architecture (Layered, Feature-based, Clean, etc.) and stick to it. Document the main principles in `AGENT.md`.

WHY

Leverages the ecosystem's built-in power tools for analysis, code generation, and dependency management.

HOW

Ensure the agent knows and uses the canonical tools for your stack.

# Flutter
flutter analyze
flutter pub add <package>

# Laravel
php artisan make:model Product

# Next.js
npx next lint

WHY

Use a four-step loop for every meaningful change: explore the problem, define the spec, develop against it, then review as a quality gate. It's a lightweight double-diamond for agent work.

HOW

Explore → Define → Develop → Review

- Explore: gather facts, constraints, and examples
- Define: write the plan/spec and success criteria
- Develop: implement in small, testable steps
- Review: test, inspect the diff, and decide

Use fresh context and a handover for each phase.

WHY

Don't try to build a whole MVP in one prompt. Mature the repo in layers, and only move to the next layer when the review gate is reliable.

HOW

1. Stabilize: Get the agent working reliably on small, guarded tasks (fixing lint, running tests, using scaffolds).
2. Implement: Use it to build out full features within the established guardrails.
3. Orchestrate: Use sub-agents for complex workflows (e.g., a dedicated `l10n-agent`).

WHY

The "IDE and Shell" for the agent. It provides the tools (`read`, `edit`, `bash`) and context injection that make it effective in *your* environment.

HOW

A harness like `pi` provides the core capabilities. Extensions and custom tools add project-specific abilities. Try different models to learn which ones are best for reasoning, codegen, or cleanup.

Close the loop with an AI postmortem: what worked, what failed, what assumptions were wrong, and what the spec should change next time. Keep a few golden tasks so you can spot regressions over time.