מוח פרויקט פשוט לעבודה עם קלוד וקודקס

AGENTS.md
CLAUDE.md
project-brain/
  overview.md
  active-context.md
  tasks.md
  decisions.md
  open-questions.md

You are helping me set up a compact project brain for this project.

The goal is to create a small Markdown-based working memory system that helps future AI agents understand the project, preserve important context, track current work, record decisions, manage open questions, and continue work across sessions.

This project brain should work for any type of project, including code, product, marketing, content, research, operations, or business strategy.

It should also support working with multiple AI agents in the same folder, especially OpenAI Codex and Claude Code.

Do not create a large documentation system.
Create only the most important files.
Keep the system practical, compact, and easy to maintain.

Before creating files:

1. Inspect the current folder or repository if files already exist.
2. Infer what this project is about from the available files.
3. Do not modify project files, code, content, configuration, or assets unless I explicitly ask.
4. Create only the project brain files.
5. Do not create extra folders or files unless there is a clear and immediate need.

Create this structure:

AGENTS.md
CLAUDE.md
project-brain/
  overview.md
  active-context.md
  tasks.md
  decisions.md
  open-questions.md

File purposes:

AGENTS.md

The main shared instruction file for AI agents.

This is the operating guide for Codex and other general AI agents.
Keep it short and practical.
Do not turn it into a full project document.

Include:

- The purpose of the project brain.
- Which files to read before starting work.
- The normal workflow for an agent.
- What not to change without asking.
- How to validate work before saying it is done.
- How to update the project brain.
- How to leave a handoff for another agent or future session.

The normal workflow should be:

1. Read AGENTS.md.
2. Read project-brain/overview.md.
3. Read project-brain/active-context.md.
4. Check project-brain/tasks.md.
5. Read project-brain/decisions.md only if the task may conflict with past decisions.
6. Read project-brain/open-questions.md if information is missing or unclear.
7. Work on one task at a time.
8. Make a short plan before large, risky, or multi-file changes.
9. Implement only the requested or clearly selected task.
10. Validate the work.
11. Summarize what changed.
12. Update only the relevant project brain files.

Important rules for agents:

- Do not invent project facts.
- Mark uncertain information clearly as Assumption.
- Do not store secrets, API keys, passwords, tokens, or private credentials.
- Do not duplicate the same information across files.
- Do not make broad changes without explaining the plan first.
- Do not modify unrelated project files.
- Do not treat the project brain as an archive.
- Keep updates short, useful, and current.
- Prefer updating existing brain files over adding new files.
- Only add new brain files if the project clearly needs them.

Validation rules:

Before saying a task is complete, report:

- What was changed.
- Which files were touched.
- What was tested or checked.
- What was not tested.
- Any risks, assumptions, or follow-up tasks.

For code projects, run relevant tests or explain why tests could not be run.
For UI projects, include a visual check when possible.
For research or content projects, separate facts, assumptions, and recommendations.

Handoff rule:

When handing work to another agent or future session, leave a short handoff in project-brain/active-context.md with:

- Current goal.
- Work completed.
- Files changed.
- Important decisions or assumptions.
- Tests or checks performed.
- Known issues.
- Recommended next step.

Feedback loop:

When a mistake, bad assumption, repeated confusion, or useful workflow lesson appears:

- If it affects future behavior, add it to the relevant brain file.
- If it is a project decision, update decisions.md.
- If it is an unresolved risk or missing info, update open-questions.md.
- If it creates follow-up work, update tasks.md.
- If it should guide the next session, add a short note to active-context.md.
- Do not add generic lessons. Only save lessons that should change future work.

CLAUDE.md

A very short file for Claude Code.

It should reference or import AGENTS.md.
Do not duplicate the full content of AGENTS.md.

Include only Claude-specific instructions:

- Read AGENTS.md first.
- Use planning before large, risky, or multi-file changes.
- Keep progress updates concise.
- Update the project brain when meaningful progress, decisions, blockers, or open questions appear.
- If supported, use an import/reference to AGENTS.md; otherwise clearly instruct Claude to read it first.

project-brain/overview.md

The stable overview of the project.

This file should change rarely.

Include:

- What the project is.
- Why it exists.
- Who it is for.
- Main goals.
- Important context.
- Key constraints.
- What is out of scope.
- Links or references to important project files, if relevant.

Do not include temporary tasks or session notes here.

project-brain/active-context.md

The current working context.

This file should stay short and be updated often.

Include:

- What we are working on now.
- Current status.
- Recent meaningful changes.
- Current focus.
- Known blockers.
- Notes for the next session.
- Handoff notes when another agent should continue the work.

This is the first file an agent should use to understand where things stand now.

project-brain/tasks.md

The lightweight task tracker.

Include:

- Active task.
- Backlog.
- Blocked tasks.
- Recently completed tasks.
- Follow-up tasks.

Keep tasks actionable.
Do not turn this into a full project management system.
Do not keep a long historical archive here.
Move old completed items out or summarize them when they are no longer useful.

project-brain/decisions.md

The decision log.

Use this only for meaningful decisions that affect the project direction, architecture, workflow, scope, positioning, or constraints.

For each important decision, include:

- Date.
- Decision.
- Reason.
- Consequences.
- When to revisit, if relevant.

Do not delete old decisions.
If a decision changes, add a new entry explaining the change.

project-brain/open-questions.md

Questions that still need answers.

Include only questions that affect future work.

These may include:

- Product questions.
- Technical questions.
- Marketing questions.
- Content questions.
- Business questions.
- Questions for me.
- Assumptions that need confirmation.

Startup rule:

When I say start from brain, read:

1. AGENTS.md
2. project-brain/overview.md
3. project-brain/active-context.md
4. project-brain/tasks.md

Then summarize what you understand in a few bullets before making changes.

Update rule:

When I say update brain, update only the relevant files:

- Always consider project-brain/active-context.md.
- Update project-brain/tasks.md if task status changed.
- Update project-brain/decisions.md only if an important decision was made.
- Update project-brain/open-questions.md if questions were added, answered, changed, or resolved.
- Update project-brain/overview.md only if the stable project context changed.

Do not rewrite the whole brain unless explicitly asked.
Do not make the brain bigger unless there is a clear need.

After creating the files, summarize:

1. Which files were created.
2. What you inferred about the project.
3. What assumptions you made.
4. What questions I should answer next.
5. How I should use this brain going forward.