mirror of
https://github.com/NanmiCoder/cc-haha
synced 2026-07-16 13:03:31 +08:00
435e4ccc9f
Route required checks by changed surface, add offline provider and chat contracts, and keep fork PRs independent of live credentials. Layer agent guidance by subtree and enforce a compact instruction budget. Tested: bun run check:policy Confidence: high Scope-risk: broad
68 lines
5.9 KiB
Markdown
68 lines
5.9 KiB
Markdown
# Repository Instructions
|
|
|
|
This file is the entry point for coding agents. Keep it short: it should route an agent to the right code, tests, and deeper documentation rather than duplicate them.
|
|
|
|
Rules closer to the code take precedence. Before editing `.github/`, `src/`, `desktop/`, `adapters/`, or `docs/`, read the nested `AGENTS.md` in that directory.
|
|
|
|
## Start Here
|
|
|
|
- Run `git status --short` before editing. Preserve all existing user changes and never revert, restage, reformat, or overwrite unrelated work.
|
|
- Identify the affected surface and inspect its production path, nearest tests, and existing implementation pattern before proposing a change. Check recent history when regression context matters.
|
|
- For bugs, reproduce the failure or add a regression test that fails for the intended reason. If reproduction is impossible, state the limitation instead of guessing.
|
|
- Define the smallest behavior change and the proof that will demonstrate it. Stop and re-scope if the diff crosses an unplanned surface, adds a dependency, or grows beyond the verified seam.
|
|
- For broad investigation, parallel read-only subagents are encouraged. Give editing agents non-overlapping file ownership; the primary agent owns integration and final verification.
|
|
- Tool access is capability, not authorization. Do not create/switch branches, commit, push, open or merge a PR, publish a release, change repository settings, or spend live-provider quota unless the user explicitly requests that operation.
|
|
|
|
## Repository Map
|
|
|
|
- `src/`: CLI, Ink UI, commands, services, tools, shared runtime utilities, and the local API/WebSocket server.
|
|
- `desktop/`: React desktop UI, Electron host, native/sidecar resources, and desktop build scripts.
|
|
- `adapters/`: Telegram, Feishu, WeChat, DingTalk, and shared IM adapter utilities.
|
|
- `docs/` and `docs/en/`: VitePress documentation; keep Chinese and English counterparts aligned when both exist.
|
|
- `.github/workflows/`, `scripts/pr/`, and `scripts/quality-gate/`: CI routing and quality policy.
|
|
- `release-notes/`, `scripts/release.ts`, and `.github/workflows/release-desktop.yml`: desktop release automation.
|
|
|
|
## Implementation Rules
|
|
|
|
- Make narrow, owned diffs. Every changed line must trace to the request, a failing test, or a verified compatibility constraint.
|
|
- Prefer existing utilities, stores, services, and test harnesses. Do not add dependencies or speculative abstractions unless the task requires them.
|
|
- Production changes under `src/`, `desktop/src/`, or `adapters/` require a same-area regression test unless a maintainer explicitly approves an exception.
|
|
- Keep TypeScript ESM style: 2-space indentation, no semicolons, `PascalCase` components, and `camelCase` functions/hooks/stores.
|
|
- Use structured parsers and existing boundaries instead of ad hoc string manipulation. Add comments only for non-obvious control flow or external constraints.
|
|
- Do not commit generated output such as `artifacts/`, coverage reports, `node_modules/`, build directories, or Rust `target/` trees.
|
|
- When publishing is explicitly requested, use Conventional Commit subjects and normal product branch prefixes such as `fix/`, `feat/`, or `docs/`; do not create `codex/` branches in this repository.
|
|
|
|
## Verification
|
|
|
|
1. Run the narrowest relevant test while iterating.
|
|
2. Run `bun run check:impact`; every command it selects is part of the minimum handoff for the current diff.
|
|
3. Run `bun run verify` only when full validation is requested or before claiming a code change is PR-ready or push-ready.
|
|
|
|
Additional invariants:
|
|
|
|
- Required PR checks must be deterministic and work on an untrusted fork: no real models, public network, repository secrets, saved providers, or real user home/config. Use fake credentials, fixtures, mocked/loopback transports, temporary directories, and explicit cleanup.
|
|
- Provider/auth/proxy/runtime changes may select `bun run check:provider-contract`; desktop chat/WebSocket/session changes may select `bun run check:chat-contract`. These contracts are offline and do not replace their selected surface checks.
|
|
- Any persisted JSON, `localStorage`, or app-config shape change requires a forward migration, an old-fixture regression test, and `bun run check:persistence-upgrade`.
|
|
- User-visible desktop or cross-process behavior needs an actual browser/desktop smoke path when unit tests cannot prove the workflow.
|
|
- Live model checks are separate maintainer evidence. Run them only after deterministic checks pass and a maintainer explicitly authorizes quota use; finding credentials on the machine is not authorization.
|
|
- `bun run check:docs` runs `npm ci`; run it sequentially with checks that rely on root `node_modules`.
|
|
|
|
## User-State Safety
|
|
|
|
- Never use or mutate the developer's real `~/.claude`, keychain, tokens, transcripts, providers, or project settings in tests. Redirect every relevant path to a temporary directory.
|
|
- Treat `~/.claude/settings.json` as user-owned shared state: preserve unknown fields, merge additively, and never add a repository-owned global schema marker.
|
|
- Repair/Doctor flows are deny-by-default. They may automatically change only explicitly allowlisted, regenerable desktop UI state; protected user data requires a reviewed, backup-first manual flow.
|
|
|
|
## Handoff
|
|
|
|
- Review `git diff --check`, `git diff`, and `git status --short` before reporting completion.
|
|
- Report only evidence from the current worktree: changed files, tests added, commands actually run and their observed results, checks not run, blockers, and remaining risk.
|
|
- `passed`, `failed`, `skipped`, `blocked`, and `not run` are different states. A build is not E2E, a mock is not live-provider evidence, and an older report becomes stale after relevant edits.
|
|
|
|
## Deeper Guides
|
|
|
|
- Contributor workflow and quality lanes: `CONTRIBUTING.md` and `docs/guide/contributing.md`
|
|
- Package scripts and path routing: `package.json` and `scripts/pr/change-policy.ts`
|
|
- PR evidence contract: `.github/pull_request_template.md`
|
|
- Desktop release and auto-update runbook: `docs/desktop/10-release-auto-update.md`
|