Shared, curated instructions for teams: the next step in AI adoption

The adoption of AI tools in software development has followed a predictable pattern: first, individual developers experiment with ad hoc prompts; then, some discover particularly effective techniques; finally, the inevitable question arises: how do we share what works?

The answer lies in shared, curated instructions for software teams — a practice that turns scattered knowledge about how to interact with AI into an organizational asset that is managed and continuously improved.

Why individual prompting doesn't scale

When every team member builds their own prompts, several problems emerge:

Inconsistent results. One developer gets well-structured code while another struggles with low-quality output, simply because of differences in how they phrase their requests.

Duplicated effort. Multiple people solve the same problem of communicating with the AI, each spending time that could have been saved.

Lost knowledge. When someone discovers a particularly effective prompt for reviewing pull requests or generating tests, that knowledge stays isolated on their local machine.

A repeated learning curve. Every new team member has to figure out for themselves what works and what doesn't.

The result: 80% of teams use AI individually. Only 20% have systematized the collective knowledge of how to use it effectively.

The solution: instructions as code

The most direct way to implement shared instructions is to treat them the way we treat any other engineering artifact: versioning them in the project repository.

AGENTS.md: the emerging standard

The AGENTS.md file has become a convention adopted by multiple AI-coding tools. Placed at the root of the project, this file contains instructions that AI tools read automatically to contextualize their behavior.

An effective AGENTS.md typically includes:

# Project Context

This is a payments service written in Python 3.11 using FastAPI.
We follow a hexagonal architecture with ports and adapters.

## Code conventions

- We use type hints on all public functions
- Tests follow the Arrange-Act-Assert pattern
- We prefer composition over inheritance

## Specific patterns

When generating endpoints:
- Always include validation with Pydantic
- Handle errors with HTTPException
- Document with OpenAPI-compatible docstrings

## What to avoid

- Don't use ORMs; we prefer explicit SQL queries
- Don't create singleton classes
- Avoid circular imports by separating interfaces
          

Support in modern tools

The leading AI-coding tools have adopted mechanisms for shared instructions:

Cursor lets you define rules in .cursorrules files and create custom slash commands the team can invoke consistently.

Windsurf supports configuration files that establish the project context and the style guides the AI respects in its suggestions.

Claude Code automatically reads files such as CLAUDE.md or AGENTS.md and lets you configure project-level instructions that persist across sessions.

Key insight: It doesn't matter which tool you use. What matters is that the knowledge of how to use it is versioned, shared and continuously improving.

Beyond code: instructions for the whole delivery

The value of curated instructions extends to every software delivery activity:

Code review. Standardized prompts for the AI to review PRs focusing on the team's specific criteria: security, performance, adherence to architectural patterns.

Documentation. Instructions that ensure the generated documentation follows the format, tone and level of detail the project requires.

Testing. Prompts to generate test cases that cover the edge scenarios that have historically caused bugs in the project.

Requirements analysis. Instructions to extract user stories or acceptance criteria from conversations with stakeholders.

Organizational prompt libraries

For tasks that aren't tied to a specific repository, organizations can maintain centralized libraries of proven prompts:

• Internal wikis with prompts categorized by use case
• Shared snippets in tools like Notion or Confluence
• Dedicated prompt repositories with examples and expected results

The continuous improvement cycle

The real advantage of shared instructions emerges when you establish a refinement process:

1. Contribution. Any team member can propose new instructions or improvements to existing ones.
2. Review. Proposals go through the same review process as code, assessing clarity, effectiveness and alignment with team standards.
3. Validation. Instructions are tested in real scenarios before being added to the main set.
4. Immediate distribution. Once merged, the whole team has instant access to the improvements.
5. Feedback. Feedback is gathered on how effective the instructions are in use.

The result: A system that gets smarter with every iteration. One developer's discovery automatically benefits the entire team.

Practical implementation: 4 weeks

For teams ready to get started, this is the incremental approach we recommend:

Weeks 1-2: Collection

Ask each team member to share the 3-5 prompts they use most and that give them the best results. Don't judge, just gather.

Week 3: Consolidation

Group the prompts by category, identify common patterns and remove redundancies. Look for the prompts several developers use in a similar way.

Week 4: Initial documentation

Create the first AGENTS.md (or CLAUDE.md, depending on your tool) with the most universally useful instructions.

Month 2+: Iteration

Set up a channel (Slack, Teams) where the team shares discoveries and proposes improvements. Review and update the instructions every 2 weeks.

The impact on team productivity

Teams that adopt shared instructions report tangible benefits:

• Reduced onboarding time for new members who inherit months of collective learning
• Greater consistency in the generated code, reducing friction in reviews
• Democratized knowledge — the junior with the best debugging prompt now benefits the whole team
• Cumulative improvement where every refinement raises the baseline for everyone

Recommended structure for your AGENTS.md

Based on our experience implementing this in teams, this is the structure that works best:

# AGENTS.md

## Project context
[Brief description: what it does, stack, architecture]

## Code conventions
[Rules the AI must ALWAYS follow]

## Specific patterns
[How to generate endpoints, components, tests, etc.]

## What to avoid
[Antipatterns, forbidden dependencies, etc.]

## Examples
[Reference code so the AI understands the style]

## Frequent prompts
[Templates for common project tasks]
          

Conclusion: from individual skill to organizational capability

Shared, curated instructions represent the natural maturation of AI use in software teams. Just as years ago we learned to version configurations, pipelines and infrastructure scripts, we now bring AI instructions in as one more artifact of the project.

The result is a productivity multiplier that grows with every improvement any team member contributes — turning prompting from an individual skill into an organizational capability.

The question isn't whether your team will use AI. It's whether the knowledge of how to use it will stay in individual silos or become a collective asset that keeps improving.

Written by

Jordi García

Tech Lead at onext

Jordi García is Tech Lead at onext. He works on bringing AI into governed production across development and product teams —with Spec-Driven Development, context engineering and human verification at every step— and authors onext's technical insights on the method, quality and cost of applied AI.

LinkedIn →