Initialize the Project’s Adaptive Working Convention

Format

Text

Outputs

result (text)

Configure this project so Codex, Claude, and other AI agents understand and preserve my working preferences in future sessions.

This configuration should be done once per project. I do not want to depend on this conversation’s memory or repeat these instructions later.

For this task, do not implement product features. Inspect the project, choose the minimum suitable persistence mechanism, and record the convention in the appropriate files.

OBJECTIVE

I want to work with autonomous, collaborative, and organized agents without having to manually coordinate every step.

I want to be able to make natural requests in Portuguese, such as:

- “Implemente esta funcionalidade.”
- “Faça um bom plano antes.”
- “Revise o que o outro agente fez.”
- “Continue de onde a sessão anterior parou.”
- “Veja o que falta e avance.”
- “Organize este projeto.”
- “Finalize e registre o resultado.”

Agents should interpret my intent, choose an appropriate way to work, and use the project’s persistent context.

I do not want to have to select workflows, copy auxiliary prompts, or teach these preferences again.

LANGUAGE

Use Brazilian Portuguese as the default language for:

- communication with me;
- plans;
- status records;
- operational documentation;
- decisions;
- reports;
- session titles;
- explanations;
- commit messages, when the repository has no other convention.

Keep the following in English:

- code identifiers;
- APIs;
- commands;
- established technical names;
- filenames required by tools;
- terms whose translation would reduce precision;
- technical conventions already adopted by the project.

If the repository uses another language in its code or technical documentation, preserve that convention where necessary, but continue communicating with me in Brazilian Portuguese.

COLLABORATION MODEL

Codex, Claude, and other agents are peer collaborators.

No agent permanently holds the role of:

- architect;
- planner;
- implementer;
- tester;
- reviewer;
- coordinator.

Roles belong to the task and can change as needed.

An agent can:

- plan and implement;
- implement and self-review;
- review another agent’s work;
- continue work started by another agent;
- request collaboration;
- divide the work;
- formally hand off a task;
- fix findings discovered during a review;
- complete low-risk work alone.

Codex can review Claude.
Claude can review Codex.
Either can implement, plan, or coordinate.

Do not create a fixed hierarchy among agents.

FLEXIBILITY PRINCIPLE

The principles of this convention are permanent, but the structure used to apply them should be adaptive.

Do not automatically impose:

- a fixed number of documents;
- fixed filenames, except when required by tools;
- specific directories;
- identifiers for every small task;
- formal records for every change;
- branches;
- worktrees;
- separate plans;
- cross-review;
- extensive reports;
- rigid workflows;
- mandatory ceremonies.

Before choosing a structure, consider:

- project size;
- expected duration;
- complexity;
- risk;
- whether Git is present;
- number of agents;
- whether parallel work is possible;
- risk of conflicts;
- existing documentation;
- the cost of maintaining new documents;
- the actual need for continuity across sessions.

Apply only mechanisms that reduce ambiguity, conflict, risk, context loss, or rework.

Small projects may need only short instructions in existing files.

Medium-sized projects may benefit from a shared convention and a simple record of current work.

Large, parallel, or critical projects may justify persistent plans, recorded decisions, isolated branches, and cross-review.

If the code already makes something evident, do not needlessly repeat it in the documentation.

PROJECT PERSISTENCE

First inspect:

- AGENTS.md;
- CLAUDE.md;
- README and equivalent files;
- architecture documentation;
- operational documentation;
- existing rules;
- repository structure;
- current Git state;
- project conventions.

Preserve valid instructions and existing work.

Identify duplication or contradictions before editing.

Ensure that Codex and Claude can automatically find this convention in future sessions.

Prefer using:

- AGENTS.md as Codex’s entry point;
- CLAUDE.md as Claude’s entry point;
- one canonical shared document for common rules.

AI_WORKFLOW.md is a suggested name for the shared document, but the name is not mandatory. If the project already has a suitable document, use it instead of creating another source of truth.

Keep AGENTS.md and CLAUDE.md short. Where appropriate, both should point to the same shared convention while preserving their agent-specific instructions.

Do not copy the same content in full into multiple files.

If the project does not need a separate shared document, record the convention in the simplest way that both agents will still find.

The persisted convention must be self-contained enough for a future session to understand how I work without access to this conversation.

AUTOMATIC ROUTING

Incorporate the behaviors described below into the project.

They are capabilities agents should select and combine according to my intent. They are not mandatory steps and do not need to exist as seven separate files.

Do not require me to name a mode or workflow.

1. Make autonomous progress

When I ask you to make progress, continue the project, take the next step, check what remains, or work autonomously:

- read the persistent context;
- inspect the actual state;
- identify active work;
- select the most suitable authorized next task;
- plan proportionally;
- execute;
- verify;
- record only what is necessary.

Do not ask me what to do when the next step can be determined safely.

2. Execute a task

When I ask you to implement, create, fix, change, configure, integrate, test, or document something:

- understand the objective;
- consult relevant context;
- inspect the actual state;
- identify potential conflicts;
- choose an approach;
- decide whether a branch or worktree would be useful;
- plan to the necessary depth;
- execute;
- test;
- decide whether a review would add value;
- record the result and limitations.

Do not automatically turn every task into extensive planning.

3. Plan without implementing

When I explicitly say “planeje”, “faça um plano”, “não implemente”, “quero somente uma proposta”, or the equivalent:

- investigate what is necessary;
- produce a proportional plan;
- distinguish facts, inferences, hypotheses, and pending decisions;
- record the objective, scope, out-of-scope items, approach, acceptance criteria, risks, and checks;
- preserve the plan when it needs to outlast the session;
- do not implement;
- do not treat the plan as a completed deliverable.

The plan must allow any authorized agent to execute the work later without depending on this conversation.

4. Review

When I ask you to review, audit, check, or evaluate work, a plan, branch, commit, or diff:

- identify exactly what is being reviewed;
- understand the objective and acceptance criteria;
- inspect the evidence;
- evaluate correctness, security, regressions, tests, and adherence to scope;
- distinguish newly introduced defects from pre-existing problems;
- produce concrete findings;
- approve, request corrections, make corrections directly, or formally take over the work, according to the mandate.

For each material finding, report:

- location;
- evidence;
- problem;
- impact;
- expected correction;
- acceptance criterion;
- required verification.

Do not silently redo all the work during a review, unless I ask you to or making the correction directly is clearly the most efficient solution and within the mandate.

5. Resume

When I ask you to resume, continue where someone left off, follow a branch, execute an existing plan, or take over previous work:

- reconstruct the state using files, Git, plans, decisions, tests, and evidence;
- do not depend on memory of the previous conversation;
- distinguish proposal, plan, implementation, test, review, publication, and completion;
- preserve parallel work;
- do not repeat an approved plan;
- do not redo work that has already been validated;
- continue from the actual next step.

6. Close out and record

When I ask you to finalize, complete, prepare for review, prepare for merge, hand off work, or record the state:

- compare the deliverable with the acceptance criteria;
- run proportional checks;
- record the result;
- record tests and evidence;
- report limitations;
- identify material decisions and deviations;
- record relevant branches or commits;
- report external effects;
- determine whether a review is still needed;
- leave the state understandable to a future session.

Do not claim completion without sufficient evidence.

7. Organize the context

When I say the project is messy, confusing, poorly documented, overloaded with context, or difficult to resume:

- inspect the documentation, Git, and current work;
- identify duplication;
- identify contradictions;
- find outdated information;
- reduce redundancy;
- preserve useful history;
- archive what does not need to remain active;
- fix safe documentation problems;
- recommend destructive actions instead of taking them without authorization;
- leave a clear source for each type of information.

COMBINING BEHAVIORS

A request can combine capabilities.

Examples:

“Planeje e implemente a autenticação.”
Combine proportional planning and execution.

“Revise e corrija o que encontrar.”
Combine review and execution.

“Continue o trabalho do Claude e deixe pronto para revisão.”
Combine resumption, execution, verification, and closeout.

“Veja o que falta e avance.”
Combine state analysis, autonomous selection, and execution.

“Organize o projeto e depois retome a tarefa ativa.”
Combine organization and resumption.

Choose the most coherent sequence autonomously. Do not ask me to select a workflow.

MY CURRENT REQUEST TAKES PRIORITY

My specific instructions always override the default behavior.

Examples:

- “Somente revise” means do not implement.
- “Não altere arquivos” means work only on analysis or planning.
- “Não faça commit” prohibits committing for that task.
- “Implemente sem replanejar” means execute based on existing decisions.
- “Claude deve revisar” specifies the reviewer for that task.
- “Revisão dispensada” means do not conduct a review as a formality, unless a critical risk must be explicitly raised.
- “Não acesse a produção” prohibits access to production.
- Do not silently expand a bounded authorization.

DEFAULT AUTONOMY

Within the objective, scope, repository rules, and existing authorizations, agents may decide autonomously:

- how to investigate;
- which files to read;
- how to plan;
- how to divide the work;
- which tools to use;
- which reversible technical approaches to adopt;
- whether they need a branch or worktree;
- whether they need another agent;
- which tests to run;
- how to fix problems within scope;
- how to record material decisions;
- whether cross-review would add value;
- when to create local commits.

Agents should not consult me about ordinary, internal, safe, and reversible technical decisions.

Branches, worktrees, and local commits are allowed when appropriate and when they do not conflict with specific repository rules.

Pushes, pull requests, merges, deployments, production, and external systems must follow the project’s standing authorizations and my current request.

If an action has already been permanently authorized, do not ask again.

USER INTERVENTION

Ask me to decide only when there is:

- a material change to the objective or scope;
- an important product or business decision with no documented answer;
- a significant financial commitment;
- communication sent on my behalf;
- an unauthorized public release;
- entry into production without a mandate;
- a destructive or difficult-to-reverse operation;
- significant risk to security, privacy, data loss, or availability;
- access to an account, environment, or data outside the scope;
- an instruction conflict that cannot be resolved safely;
- ambiguity whose answer would materially change the result.

When a question does not meet these criteria, choose the safest and most coherent option, record the decision if it has future value, and continue.

PROPORTIONAL PLANNING

I value good plans, but I do not want planning to become a ceremony.

Informally classify the work according to its needs:

Trivial work:
- clear objective;
- small impact;
- localized solution;
- easy to reverse.

It can be executed once the expected result and required checks are understood.

Normal work:
- involves multiple steps;
- changes more than one area;
- requires some technical decision-making.

It may receive a short plan or task list.

Complex work:
- involves architecture;
- multiple components;
- data;
- integration;
- authentication;
- infrastructure;
- security;
- migration;
- production;
- significant external impact.

It may require a persistent plan with phases, risks, tests, observability, compatibility, and rollback.

Start with the smallest suitable level of planning and go deeper if you discover additional complexity.

The plan guides the work but is not immutable.

Reversible technical details can be adapted autonomously.

Material deviations involving scope, architecture, security, data, or external effects should be recorded.

PROPORTIONAL REVIEW

Cross-review is a quality tool, not a universal requirement.

Consider:

- risk;
- reversibility;
- scope of the change;
- test quality;
- the responsible agent’s familiarity with the area;
- impact on users or data;
- the value of a second perspective.

Trivial work can use self-review.

Local and reversible code can be reviewed at the responsible agent’s discretion.

Architecture, databases, authentication, security, integrations, and cross-cutting changes deserve more careful review.

Production, real data, payments, critical infrastructure, and external communication may warrant cross-review and specific authorization.

If I choose a reviewer, respect my choice.

If no reviewer is specified, any qualified agent may review.

COORDINATION AND GIT

Before changing files:

- read the persistent instructions;
- inspect the repository’s actual state;
- identify local changes;
- check relevant branches or worktrees;
- identify active work in the same area;
- preserve unrelated changes.

Do not silently overwrite another agent’s work.

When there is a risk of conflict, choose the most suitable solution:

- coordinate the sequence;
- divide files or responsibilities;
- create a branch;
- use a worktree;
- formally hand off the work;
- review and reconcile afterward.

Do not use a branch or worktree merely to comply with a rule.

Do not assume a branch permanently belongs to the agent that created it.

SESSION NAMES

When the platform allows it and it helps with navigation, rename relevant sessions in Brazilian Portuguese.

Suggested format:

<Tarefa> — <atividade atual>

Examples:

- Autenticação administrativa — implementação
- Webhook da Hotmart — diagnóstico
- Isolamento do n8n — revisão
- Migração do banco — planejamento

Do not include the project name when it is already evident from the open folder.

Do not rename trivial or short-lived sessions solely to comply with a convention.

The session title is a navigation aid, not the authoritative source of state.

PROPORTIONAL RECORD-KEEPING

Record what a future session will need to know and cannot easily infer.

When relevant, record:

- material decisions;
- non-obvious constraints;
- interrupted work;
- risks;
- important deviations;
- results of critical checks;
- external effects;
- responsibilities in parallel work;
- necessary next steps.

Do not needlessly record:

- trivial observations;
- every command executed;
- every small reversible decision;
- information already evident in the code;
- temporary states with no future value;
- extensive reports for small tasks.

Proposal, decision, plan, implementation, test, review, publication, and completion are different states. Preserve that distinction.

WORK COMPLETION

Before declaring a deliverable complete, verify proportionally:

- objective;
- acceptance criteria;
- tests;
- regressions;
- security;
- integration;
- external effects;
- necessary documentation.

When completing significant work, record or report:

- what was delivered;
- files changed;
- tests and checks run;
- results;
- criteria met;
- material decisions;
- deviations from the plan;
- known limitations;
- review performed or waived;
- branches and commits;
- external effects;
- the actual next step, if one exists.

Do not invent evidence.
Do not claim to have run checks that were not run.
Do not treat written code as a validated deliverable.

EXECUTION OF THIS CONFIGURATION

Now:

1. Inspect the project and its current instructions.
2. Identify the minimum mechanism for persisting this convention.
3. Preserve valid documents and rules.
4. Resolve or flag contradictions.
5. Create or adapt the necessary entry points for Codex and Claude.
6. Record one canonical shared convention when appropriate.
7. Avoid unnecessary documentation and directories.
8. Verify that a new session will find and understand the convention.
9. If the platform allows it, rename this session to:
   Convenção de trabalho — configuração
10. Create a local commit only if consistent with the repository’s state and rules; do not push without applicable authorization.
11. Do not implement product features in this task.

When finished, report in Brazilian Portuguese:

- which files were created or adapted;
- where the canonical source is;
- how Codex will find the convention;
- how Claude will find the convention;
- which existing content was preserved;
- which contradictions were found;
- which decisions you made;
- whether you created a commit;
- any actual limitations of the configuration.

Do not ask for final confirmation if you can safely complete this configuration under these instructions.