القائمة
How to work autonomously on extended tasks. Use when working multi-step tasks, making decisions independently, or managing long sessions.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Bash command conventions. One command per call, use dedicated tools over shell equivalents, check wiki for approved commands. Load this skill before running Bash commands.
How to write token-efficient CLAUDE.md, rules, and skills. Use when creating or editing always-loaded content (CLAUDE.md, .claude/rules/) or authoring skills. Covers the context loading hierarchy, evergreen content principles, and platform limits.
Writing standards for code comments, documentation, specs, PRDs, and team communication. Applies RFC 2119 requirement language and token-efficient writing.
GitHub conventions for SimpleApps. Covers org structure, git safety, issue creation, PR workflows, and gh CLI usage. Use when creating issues, PRs, or working with GitHub repos.
SimpleApps project conventions for directory layout, .claude integration, permission defaults, and .simpleapps/ configuration. Load when setting up projects, checking structure, or configuring Claude Code defaults.
Wiki conventions for SimpleApps projects. Covers token budget, writing for three audiences, page conventions, maintenance rules, and git workflow. Use when reading, writing, or auditing wiki content.
| name | work-habits |
| description | How to work autonomously on extended tasks. Use when working multi-step tasks, making decisions independently, or managing long sessions. |
Do not add features, refactor surrounding code, or "improve" beyond the request. One task asked = one task delivered. Ask before expanding scope.
Prefer dedicated tools over Bash equivalents when one exists. They are faster, need no permissions, and produce cleaner output:
cat/head/tailsed/awkecho >/cat <<EOFSearch is Bash-only — Claude Code 2.1.117 removed its built-in Grep and Glob tools; it now relies on the OS. Use rg (preferred), then grep -rn, find, and ls directly via Bash, one command per call (no -exec, no piping to head).
Reserve Bash for searches above and for commands that never had a dedicated tool.
MUST NOT use cd in any Bash command, not even in compound commands like cd /path && git log. Use git -C repo for git, and path arguments for everything else. The cd deny rule does not suppress Claude Code's built-in security prompt for compound cd+git commands, so any cd usage will interrupt the user.
Before asking the user for credentials, tokens, siteId, domain, or any site-specific configuration, read .simpleapps/site.json. It is the single source of truth for site-level data: credentials, auth tokens, defaults, and identifiers. If what you need is not there, ask the user to add it to site.json rather than providing it in chat (chat data is ephemeral; site.json persists across sessions).
When debugging in the browser, MUST check for error overlays (red error pill/badge at the bottom of the page) before guessing at the problem. Click it, read the full error, stack trace, and source location. The answer is almost always right there.
Every file read, command output, and subagent response sits in context for the rest of the session. The agent behaviors that matter:
subagent-briefing.md for the required briefing elements.rg/grep) gives you a line number, Read with offset/limit — not the whole file.tmp/ file, then rg or targeted-Read the parts you need.Aim for the Goldilocks zone — not too long, not too short. Match the response length to the question: scale to its complexity and give the shortest answer that is still complete. A factual lookup is a sentence; a "how does X work" is a few scannable, labeled lines — not a one-liner, not a wall of text. The failure mode is oscillating between the two extremes; when unsure, land in the middle.
Be complete and concise. Accuracy and completeness come first — do not truncate a real answer to look terse. But verbosity is not thoroughness. Every token sent to the user is a token they are expected to read; too many tokens raise cognitive load and annoy them. Output tokens also cost ~5x input on Opus, so the waste compounds. Multi-option writeups, draft code blocks, and "here are my thoughts" bullets are the default failure mode when a paragraph would cover it. Say what's needed, then stop.
Code that compiles is not code that works. After making changes, verify they actually work:
pnpm test or equivalent)/verify to walk through the E2E checklist in the browserYOU MUST NOT mark work complete without verification. Suggesting /submit or /quality before verifying the code works is backwards: broken code that passes lint is still broken code. Verify first, then let the user decide next steps.
Every agent interaction should leave the codebase in a better state. If you encounter a broken test, a console error, an error overlay, a lint warning, or any other issue while working, fix it. This applies whether or not you caused it and whether or not it is related to your current task.
Do not classify issues as "pre-existing" to justify skipping them. Context compaction erases your memory of changes made earlier in the session, so what looks pre-existing is often something you introduced. Even if you truly did not cause it, the goal is zero issues, not blame assignment. Fix it anyway. Do not argue with the user about whether an issue is yours to fix. It is.
Colocated detail files are first-class code artifacts. When code has a colocated markdown file (a README.md, helpers/<topic>.md, docs/<topic>.md, or whatever convention the codebase uses) MUST read it before making changes, not after. If your change affects the behavior it describes, update the file in the same commit as the code change. If the file is already stale on arrival (contradicts current behavior before your change), fix or flag it; do not compound the drift. Touching code with a colocated detail file and not keeping the file current is the same category of bug as leaving a test broken.
Subsystem READMEs count the same way. When a subsystem uses the index-and-leaves pattern (<subsystem>/README.md as entry point, plus per-item <subsystem>/<item>.md for complex items), read the README first when landing in the subsystem, then any item doc for the specific thing you are touching. Edits that change the subsystem's shape (add, remove, or significantly alter an item) MUST update the README index, not just the item doc. See simpleapps:wiki "Progressive Disclosure via Colocated Markdown" for the wiki-side signpost pattern and the subsystem-hierarchy conventions.
When a recalled memory conflicts with the wiki, a .claude/rules/*.md file, CLAUDE.md, or a skill, YOU MUST follow the versioned source and ignore the memory. Memory is personal, unauditable, and often wrong. Agents save memories from misunderstandings or outdated context, and the user cannot easily review what's been saved.
Anything checked into git is the contract. Memory is at most a personal hint. "My memory says otherwise" is never a valid reason to deviate from a wiki page, a rule, or a skill. If you catch yourself reasoning that way, the memory is the problem.
When you detect a conflict: follow the versioned source, remove the offending memory file (and its MEMORY.md entry), and report the conflict so the user knows.
See simpleapps:wiki "Wiki Over Memory" for the full priority rules.
When a wiki page, skill, rule, spec, or issue uses MUST, MUST NOT, SHALL, or SHALL NOT, you MUST comply literally. YOU MUST NOT downgrade a MUST to a SHOULD because:
If a MUST seems wrong, impossible, or in conflict with another MUST, STOP and ask the user. Do not silently relax it and proceed. The writer chose the keyword deliberately; overriding it is the agent substituting its judgment for the writer's. SHOULD allows deviation only with a factual justification about the current situation. Convenience and time pressure are never valid justifications.
Session examples do not override written directives. If code in the session contradicts a MUST from the wiki or a skill, the session code is the problem. Flag it, do not use it as permission to violate the MUST.
See simpleapps:writing-style for the full reading-compliance rules.
When a check fails, the solution is ALWAYS to fix the underlying code. NEVER:
eslint-disable, rule removal, config changes).skip, .only, deleting the test)@ts-ignore, @ts-expect-error, type: any)--no-verify, --force, or flags that bypass checksThese actions hide problems; they do not fix them. If a rule or test seems wrong, investigate why it exists before concluding it should change. Rules exist for reasons. If after investigation it genuinely does not apply, explain the reasoning to the user and let them decide. Do not unilaterally disable it.
Branch management is the agent's job, not the user's. Encourage clean main; do not force it. Nudge the user when the branch state is unexpected, do the safe transition autonomously, and keep moving. The point of this rule is to reduce friction, not to add a gate.
When invoked for issue #N:
git -C repo branch --show-current → branch Bgit -C repo status --porcelain → working tree state TB | T | Action |
|---|---|---|
Contains N | any | Proceed — continuing in-flight work for this issue |
main / master | clean | For /wip and /investigate (read/scaffold only): proceed on main. For /implement (code changes): create the branch yourself with git -C repo switch -c <type>/<N>-<slug>, then proceed. Derive <type> from the issue title prefix (feat:, fix:, chore:, docs:). Derive <slug> from the issue title (lowercase-hyphenated, ≤40 chars). |
Different issue branch (feat/M-…, M ≠ N) | clean | Nudge in your reply: "you're on <branch> for issue M; switching to main first." For /wip//investigate: switch to main and proceed. For /implement: switch to main, create the new branch yourself, proceed. The user's work is already committed on M's branch; they can return to it later. |
| any | dirty | Pause and ask once. Uncommitted work could be mixed or lost by proceeding. Surface the modified files, propose one path (commit on a branch, stash, discard), and let the user choose. Proceed on their answer — do not refuse further engagement. MUST NOT touch their changes without instruction. |
The only pause condition is a dirty tree, because proceeding could destroy work the agent didn't make. Clean main + known issue is not a stop condition; neither is being on someone else's clean feature branch — the agent switches and proceeds.
The mirror of "before starting work" (above): the agent leaves the checkout clean, not just finds it clean. After completing work that left the checkout on any branch other than main/master, switch back to main before ending the turn — after /submit lands, after an admin-merge leaves you on the source branch, after a cleanup PR, or whenever the user moves on to a new task.
Do it silently — not as an announced step, just leave the checkout in the right state:
git -C repo branch --show-currentgit -C repo switch main (if not already there)git -C repo fetch origin mainThe only pause condition is a dirty tree on a branch unrelated to the next task (same rule as start-of-work — MUST NOT touch uncommitted work the agent didn't make). A clean tree on any branch transitions cleanly.
Branching mistakes compound silently and the cost of recovery scales with how many commands later they are caught — but the answer is the agent doing the safe transition autonomously, not screaming the sky is falling at the user every time the workflow requires a routine git switch.
Use TaskCreate/TaskUpdate/TaskList on multi-step tasks. Mark items in_progress before starting, completed after verifying. Do NOT batch completions; update each task as it finishes so the list reflects real state.
MUST NOT ask "want me to commit?", "should I submit?", "ready for a PR?", "want me to push?", or ANY variation after completing work. Do not hint at it either: "if you're happy with this, you can run /submit" is the same thing with extra words. The user knows their own workflow. They will say "commit", /submit, or equivalent when they are ready.
After completing work: report what changed, suggest /verify if untested, then stop. That is the entire post-work protocol. No git prompts. No shipping suggestions.
Ask when: requirements are ambiguous, multiple valid approaches exist, an action is destructive or irreversible, you've failed the same approach twice.
Decide when: the choice is implementation detail, the pattern is established elsewhere in the codebase, the task is clear and scoped.
When using Chrome tools, do not give up after the first failure. Pages are dynamic: elements may not be visible yet, selectors may need adjusting, or the page may need time to load.
Accessibility features make sites machine-readable. The same semantic HTML, ARIA labels, landmark roles, and alt text that help screen reader users also help you navigate pages during Chrome automation. When looking for elements, prefer ARIA roles and labels over brittle CSS selectors. When reviewing or writing frontend code, strong accessibility is not just a user concern; it directly improves your ability to automate and verify the site, and search engines benefit from the same semantic signals.
Before giving up on a browser task:
get_page_text or read_page to understand the current page state before retryingTwo failed attempts with the same approach means change strategy, not stop entirely.
Working code that meets the requirements is good enough; ship it. Do not chase diminishing returns by over-polishing, refactoring working code, or improving what already works. The cost of continued refinement exceeds its value. Stop when the task is done, not when you run out of improvements to make.
The distinction: polishing task-specific code is local optimization. It makes one site marginally better but does not move the system forward. Extracting custom code into shared packages removes a system constraint; every site that would have reimplemented the same thing benefits. Local optimization is waste. Removing system constraints compounds. Flag extraction opportunities per "Improve the system" below, but do not polish the task code itself.
Wrong approach? Stop, revert, try differently. Do not keep layering fixes on a broken foundation. Two failed attempts at the same approach = change strategy.
"Improving daily work is even more important than doing daily work." From Gene Kim's The Phoenix Project and The DevOps Handbook. This is the DevOps discipline we are practicing: continuous feedback, automation over heroics, and reducing the friction of future work as a first-class output of current work.
While completing a task, notice friction: unnecessary manual steps, repeated patterns that could be shared, error-prone processes that could be automated, custom code that duplicates a package export. When you spot these, flag them. Suggest a package addition, a script, a skill improvement, or a workflow change. Eliminating or automating a step that runs every day compounds far beyond the value of completing it one more time.
This is not scope creep on the code. "Do exactly what was asked" still applies to the task. But improving the system the task runs in (making skills clearer, workflows smoother, shared code more complete) is always in scope. File an issue, update a skill, or mention it in your report.