A nonprofit theater keeps its ticket pages, show information and staff scheduling tools in one repository. A maintainer using Claude Code repeatedly explains the same project structure, and long checks sometimes finish while the maintainer is away from the terminal. Use a practice branch and fictional performance data to improve three observable outcomes. Searches should lead to current code, notifications should identify the action needed, and each change should have a bounded scope and a verification record.
Establish a search baseline before adding an index
Choose three questions with known answers. Find where accessible seating text enters the booking page, where a cancelled order releases capacity, and where a ticket date is formatted. Record the correct files, a short call path and a check that can verify each answer. Run the questions with the repository's existing file and text search tools first. Track elapsed time, files opened and misleading matches. Generated copies may need an exclusion rule. A business term that differs from the code's naming may justify evaluating semantic retrieval.
For an index candidate, inspect the supported languages, file types, exclusions, update process and data destinations. Define the scope for source code separately from show notes and generated output. Apply the project's data rules to account configuration, real orders and logs before indexing. Record the repository revision represented by the index. After a code change, ask the same baseline question and verify that the result points to the new location. Delete a synthetic old implementation and check whether it still appears. A stale candidate can waste investigation time or lead to a patch against the wrong path.
Require retrieval results to identify a file and location. Have the assistant explain why each candidate matters and then open the current source to check its caller, inputs and output. For the seating change, record the path from the visible page through the component to the copy data. A summary without a version or location needs its source restored before it becomes implementation input. Keep the baseline fixtures so an index upgrade can be compared under the same conditions.
Make notifications identify the next action
List the states that deserve attention. A check finishes, an operation waits for approval, or a task fails and needs intervention. Include the project, task identifier, state and local record location in a notification. Keep customer input, source excerpts and ticket details out of desktop previews or external channels. Different task identifiers let a maintainer return to the correct session and branch when several jobs are running.
Use the current Claude Code Hooks reference to check the event, configuration scope and handler contract supported by the installed version. Start with a local handler that records only the timestamp, event category and task identifier. Observe actual invocation before connecting a desktop notification. Give the handler an execution limit and verify what happens when it fails. Validate completion, waiting for input and failure separately. One successful notification establishes only the event and environment you exercised.
In the practice branch, run a short check, an operation that requires confirmation and a deliberately failing check. Compare each notification with the actual session state. A prompt waiting for approval must remain a request for attention in the notification. Start two independent project tasks and check that their identifiers remain distinguishable. If no desktop alert appears, first determine whether the handler ran. Then inspect configuration loading, host and version support, and the operating system's notification settings. Handler execution and notification presentation are separate points to observe.
Write project instructions that a maintainer can verify
Document the project entry points, ordinary check commands, data constraints and acceptance conditions in the appropriate instruction files. When using CLAUDE.md, follow the official memory documentation for loading and scope. Keep instructions at different directory levels consistent. A practical project note tells a contributor how to start the practice server, which check to run, which generated files belong to the build and which paths require additional review. Execute each documented command once and record its dependencies and success signal.
Create a task card for the seating copy change. State the reader, field to change, allowed files and verification method. Ask the assistant to read the relevant instructions, explain the call path and propose a bounded patch. Inspect the actual diff, run the existing checks and open the preview to examine text, wrapping and keyboard access. Record commands that ran and any unavailable checks with reasons. If investigation reveals a dependency on refund or inventory behavior, establish that impact before expanding the task.
For a long session, preserve a handoff with the goal, confirmed facts, changed files, checks, open questions and next action. References should identify the branch and current file revision. A new session should inspect the working tree and repeat a critical check before relying on the handoff. If the note says the copy was changed but the branch has no corresponding diff, reconcile the state with the files. The same discipline helps a human take over when the original maintainer is unavailable.
Give independent work distinct artifacts
Separate independent investigations by input revision, scope and output format. One unit can trace ticket dates while another reviews seating text. Candidate results belong in their own locations, with a maintainer or a single integration step responsible for shared files. Where a change depends on a confirmed fact, complete that fact check before editing. Evaluate a split by end-to-end time, conflicts and rework using the same sample, rather than counting concurrent sessions.
A review finding should identify the code location, trigger and practical consequence. For a ticket-date issue, have the reviewer run a failing example on the old behavior and repeat it after the repair. The assertion should detect the difference that motivated the patch. Give a colleague the final task card and ask them to locate the change, run the check and open the preview. If they need the full conversation to understand the result, add the missing context to the handoff.
Select skills using the same small acceptance task
An indexing capability should explain its scope, refresh behavior and candidate locations. Test it with the three labeled search questions. A notification capability should turn actual events into traceable state messages, expose its external calls and handle failures without losing the original task state. A workflow capability can help organize project instructions, task cards and review steps, provided its commands match the actual repository. Inspect the upstream package, prerequisites, read and write scope and data destinations before adopting it. Record the revision used for the trial.
Rehearse the whole seating change once. Locate the current copy source, record the index revision, apply the bounded change and inspect the diff. Run the check and open the preview. When the task waits for input, verify that the notification identifies the right project and state. Apply a reviewer's wrapping adjustment, rerun the relevant check and hand over the result. The deliverable includes the diff, observed check output, preview location and unresolved items. Have a new maintainer replay the steps to see whether the configuration actually reduced repeated explanation.
Common questions
Can work continue if the index is stale?
Open the current source and confirm the location before editing. Mark the stale result, update the index and replay the baseline question. Existing file search may be sufficient for a small task, but the handoff should always identify the files actually changed.
Why did a long task finish without an alert?
Check whether the expected event occurred, whether this host loaded the configuration and whether the handler executed. Then inspect desktop presentation. Test completion and waiting for input separately, keeping the installed version and event category with the results.
Can another agent host use the same configuration?
Check its instruction loading, event system and skill discovery separately. Translate the project rules into the target host's documented format and replay the same practice task. Verify that commands execute, instructions load and selected skills are invoked in the way the task needs.