Markdown, Repository Rules, and Git Worktrees

AI coding becomes more reliable when the repository has clear instructions and each agent works inside an isolated scope.

1. Why Markdown Works for Agent Instructions

Markdown is plain text that humans, Git, search tools, and AI models can read. Headings create hierarchy, tables express decision rules, code blocks preserve commands, and pull requests show exact changes. It is useful for repository knowledge that should remain close to the code.

Markdown is not magically loaded into every context. Each coding tool has its own discovery behavior. Point the agent to important files and follow official naming conventions.

Use FileMira Markdown Viewer when you want original and rendered views side by side without installing an extension. FileMira says processing stays in the browser. Still remove secrets before using any viewer.

2. A Practical Documentation Set

README.md   -> how to run the project
AGENTS.md   -> repository rules for supporting agents
CLAUDE.md   -> Claude Code project instructions
GEMINI.md   -> Gemini CLI project context
PRD.md      -> product requirements
DESIGN.md   -> visual and UX contract
PLAN.md     -> active task plan
ASSETS.md   -> asset inventory

Use only the files that clarify ownership. Duplicate and contradictory instructions are worse than a short authoritative set.

3. JSON, CSV, YAML, and TOML

Preserve indentation, commas, quotes, delimiters, and data types. JSON does not support standard comments. Validate after editing and review the diff. Remove tokens, credentials, and personal data before opening a file in any external tool.

4. What Belongs in Repository Instructions

Include stable, reusable facts: stack and version constraints, install and quality commands, directory ownership, security rules, migration policy, dependency policy, and definition of done. Exclude API keys, temporary ticket details, long transcripts, copied vendor documentation, and conflicting rules.

5. Branches and Worktrees

A branch is a line of development. A worktree is a separate checkout folder connected to the same Git repository. It lets different branches stay open in different folders without making full independent clones.

main folder       -> main
../project-ui     -> ai/ui
../project-api    -> ai/api

Use a worktree when separate agents have independent tasks, an experiment must not disturb the main folder, or an urgent fix must continue beside a large feature. A beginner usually needs only one agent, one branch, and small commits.

6. Create and Inspect Worktrees

Start from a clean branch:

git status
git worktree add ../project-ui -b ai/ui
git worktree add ../project-api -b ai/api
git worktree list

Open each folder in its own IDE window and assign distinct file ownership. After a branch is merged and clean, remove its worktree with git worktree remove ../project-ui. Do not manually delete a worktree folder before checking Git state.

7. Rules for Parallel Agents

Use one agent and one branch per worktree. Separate file ownership. Do not let agents edit the same migration, schema, dependency file, or global config concurrently. Merge one branch at a time, update the next branch, rerun tests after integration, and review conflict resolution as a human.

8. Worktree, Clone, or Ordinary Branch

An ordinary branch is simplest for one active task. A worktree provides another folder while sharing the Git object store. A separate clone provides stronger folder and remote isolation but duplicates more state. Choose the least complex option that safely supports the workflow.

9. Recovery Commands

Understand these commands before using an autonomous agent:

git status
git diff
git log --oneline --decorate -n 10
git restore <file>
git switch <branch>
git worktree list

Do not copy a destructive reset or rebase command merely because an agent suggested it. First determine exactly which commits and files it will affect.

10. AI-Ready Repository Checklist

• The baseline is clean and committed.
• Sources of truth and commands are documented.
• Secrets are ignored.
• Requirements and design rules are findable.
• Each working tree has one owner.
• Verification commands are known.
• Worktrees are used only when parallelism adds value.
• Conflict resolution receives human verification.