4 ملفات تخلي الـ agent بتاعك أشطر، وميحرقش الـ limit

هيتحطوا فين

كلهم جوه فولدر المشروع. الـ CLAUDE.md في أوله، والباقي جوه فولدر .claude.

انسخ كل ملف بالزرار اللي فوقه، وحطه في نفس المكان اللي في الشجرة.

your-project/
├── CLAUDE.md
└── .claude/
    ├── settings.json
    ├── hooks/
    │   └── filter-test-output.sh
    ├── skills/
    │   └── deploy/
    │       └── SKILL.md
    └── agents/
        └── test-runner.md

01

CLAUDE.md: خريطة المشروع

بيتقري في أول كل session. بيقول للـ agent المشروع ده إيه، الفولدرات فين، والأوامر إيه، فميلفش في المشروع كله يدور.

• خليه قصير. Anthropic بتنصح بأقل من 200 سطر، لأن كل سطر فيه بيتحمل في كل session حتى لو مش محتاجه.
• آخر جزء، Compact instructions، بيقول للـ agent يحتفظ بإيه لما المحادثة تتلخص.
• غيّر: اسم المشروع، الفولدرات، والأوامر بتاعتك.

# Project name

One or two lines: what this project is and who uses it.

## Layout
- `src/` app code
- `src/api/` server routes
- `tests/` tests, one file per module
- `dist/`, `build/` and lock files are generated. Do not read them.

## Commands
- Install: `npm install`
- Dev server: `npm run dev`
- Tests: `npm test`
- Lint: `npm run lint`

## Rules
- Run the tests before you say a change is done.
- Keep changes small. Do not refactor code you were not asked to touch.
- Never commit `.env` or anything that holds a key.

## Workflows
- Tests and logs: hand them to the `test-runner` subagent.
- Deploying: only when I run `/deploy`. Never deploy on your own.

# Compact instructions
When you compact, keep the code changes, the test results and the open tasks.

02

SKILL.md: تعليمات وقت اللزوم بس

أي شغلانة ليها خطوات، زي الـ deploy أو الـ PR review، مكانها skill مش CLAUDE.md. من الـ skill العادي بيفضل الـ description بس في الـ context، والباقي مبيتحملش غير لما يتستخدم.

• في القالب ده disable-model-invocation: true، فحتى الـ description مش بيتحمل، والـ agent مش هيعمل deploy من دماغه. انت بس اللي بتشغله بـ /deploy.
• المكان: .claude/skills/deploy/SKILL.md. كل skill في فولدر باسمه.
• غيّر الخطوات لأوامر الـ deploy بتاعتك.

---
name: deploy
description: Deploy the app to production.
disable-model-invocation: true
---

# Deploy

1. Check the working tree is clean and you are on `main`.
2. Run `npm test`. If anything fails, stop and report it.
3. Run `npm run build`.
4. Run `npm run deploy` and wait for it to finish.
5. Open the live URL and check the home page loads.
6. Report the deployed version and the URL.

03

subagent: التستات والـ logs بعيد عن المحادثة

الـ subagent بيشتغل في context لوحده. بيشغّل التستات ويقرا الـ logs الطويلة، ويرجّع للمحادثة الأساسية الخلاصة بس، فآلاف السطور دي متتبعتش مع كل رسالة بعد كده.

• model: haiku بيشغّله على Haiku، أرخص من Sonnet و Opus، وده كفاية لشغل زي ده.
• الـ subagent بيصرف tokens برضه، بس على موديل أرخص وفي context منفصل.
• المكان: .claude/agents/test-runner.md. لو أمر التستات عندك مش npm test، غيّره في خطوة 1.

---
name: test-runner
description: Runs tests, reads logs and build output, and reports only what failed. Use it after code changes and whenever test or log output would be long.
tools: Read, Grep, Glob, Bash
model: haiku
---

You run tests and read logs so the main conversation does not have to.

1. Run the command you were given, or `npm test` if none was given.
2. If everything passes, reply in one line: how many tests ran and that they passed.
3. If something fails, list each failing test with its file, line and error
   message in a few lines. Do not paste the full output.
4. Do not edit any file. Report and stop.

04

settings.json: hook بيفلتر الـ output

الـ hook بيشتغل قبل أي أمر Bash. لو الأمر تستات، الـ agent بيشوف الـ errors وآخر 5 سطور بس بدل الـ output كله. جربناه على output فيه 5,004 سطر، فطلع 12 سطر، والـ exit code فضل زي ما هو.

• فيه كمان permissions.deny: بيمنع الـ agent يقرا الـ .env اللي فيه الأسرار بتاعتك، والـ package-lock.json لأنه ملف ضخم ونادرا ما بيحتاجه.
• الملف التاني هو سكريبت الـ hook نفسه. محتاج jq متسطب، وعلى Windows محتاج Git Bash. وخليه executable:
  chmod +x .claude/hooks/filter-test-output.sh
• لو أمر التستات بتاعك مختلف، زي npx vitest run، ضيفه في سطر الـ pattern.
• اتأكد إنه شغال: اكتب /hooks جوه Claude Code، وهتلاقيه تحت PreToolUse.

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./package-lock.json)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/filter-test-output.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# Runs before every Bash command. When the command is a test run,
# it keeps only the failures and the last summary lines.
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')

# Add your own test command here if it is not one of these
pattern='^(npm test|pytest|go test)( [^;&|<>`$#\\[:cntrl:]]*)?$'
if [[ "$cmd" =~ $pattern ]]; then
  filtered_cmd="(out=\$(mktemp); $cmd > \"\$out\" 2>&1; status=\$?; grep -A 5 -E '(FAIL|ERROR|error:)' \"\$out\" | head -100; tail -n 5 \"\$out\"; rm -f \"\$out\"; exit \$status)"
  echo "$input" | jq --arg filtered "$filtered_cmd" \
    '{hookSpecificOutput: {hookEventName: "PreToolUse", updatedInput: (.tool_input + {command: $filtered})}}'
else
  echo "{}"
fi