110 lines
5.3 KiB
Markdown
110 lines
5.3 KiB
Markdown
# Agent Rules
|
|
|
|
## Deployments and Destructive Changes
|
|
|
|
**NEVER run any command that mutates production infrastructure without the user explicitly saying to deploy.**
|
|
|
|
If a deploy or mutating action seems like the logical next step, **stop and ask the user** whether they want to proceed. Do not infer consent from context. Do not deploy just because the plan says "next step is deploy". Wait for an explicit instruction like "go ahead and deploy" or "run the deploy now".
|
|
|
|
Violating this rule is not a minor mistake. It is unacceptable.
|
|
|
|
### Deployment workflow
|
|
|
|
We generally deploy services exclusively via CDK in CD. To trigger builds on the test servers, they are triggered by force pushing the current feature branch onto the branches `t1` or `t2`. There are git aliases `git t1` and `git t2` that can be used to do this. Always seek confirmation before using these commands however.
|
|
|
|
## AWS Access
|
|
|
|
The `aws` CLI is blocked at the system level. Do not attempt to use it.
|
|
|
|
For AWS inspection tasks, use the appropriate AWS MCP server. The following servers may be available — ask the user to enable the relevant one if it is not already active:
|
|
|
|
- `aws-cloudwatch` — CloudWatch logs and metrics
|
|
- `aws-ecs` — ECS cluster and service inspection
|
|
- `aws-cloudformation` — CloudFormation stacks
|
|
- `aws-iac` — Infrastructure-as-code tooling
|
|
- `aws-cost-explorer` — Cost and billing
|
|
|
|
The one exception is `cdk diff`, which runs locally and is permitted:
|
|
|
|
```
|
|
AWS_PROFILE=ro npx cdk diff ...
|
|
```
|
|
|
|
If a task requires write access to AWS, stop and ask the user to run the command themselves.
|
|
|
|
## Git Worktree Setup
|
|
|
|
Projects are set up using a `git bare-clone` alias that creates a bare-clone worktree layout:
|
|
|
|
```
|
|
project-name/ ← project root (cd here)
|
|
.bare/ ← bare git repo (the actual git data)
|
|
.git ← file containing "gitdir: ./.bare"
|
|
main/ ← example worktree for main branch
|
|
feature-branch/ ← example worktree for a feature
|
|
```
|
|
|
|
**The alias does this:**
|
|
```bash
|
|
mkdir "$folder_name" && cd "$folder_name"
|
|
git clone --bare "$repo_url" .bare
|
|
echo "gitdir: ./.bare" > .git
|
|
git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
|
|
git fetch origin
|
|
```
|
|
|
|
### Worktree placement rules
|
|
|
|
- **Always place worktrees as direct children of the project root**, e.g. `~/projects/myrepo/my-feature/`
|
|
- **Never use a nested `.worktrees/` subdirectory** — worktrees sit at the top level alongside other branch worktrees
|
|
- The project root itself is not a worktree; it's the container. You must `cd` into a branch worktree to do any work
|
|
- To add a new worktree: `git worktree add my-feature -b my-feature` (from the project root), or `git worktree add ../my-feature -b my-feature` (from within an existing worktree)
|
|
- No `.gitignore` entry is needed for worktree directories since the repo is bare and the project root is not itself a working tree
|
|
|
|
## Git Commits
|
|
|
|
Commit early and often. After completing any logical unit of work — a bug fix, a feature addition, a refactor, a config change — create a commit immediately rather than batching everything at the end.
|
|
|
|
All commits must follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
|
|
|
|
```
|
|
<type>[optional scope]: <description>
|
|
|
|
[optional body]
|
|
```
|
|
|
|
Common types:
|
|
- `feat` — a new feature
|
|
- `fix` — a bug fix
|
|
- `refactor` — code change that neither fixes a bug nor adds a feature
|
|
- `chore` — maintenance, dependency updates, config changes
|
|
- `docs` — documentation only changes
|
|
- `test` — adding or updating tests
|
|
- `style` — formatting, missing semicolons, etc. (no logic change)
|
|
|
|
Examples:
|
|
```
|
|
feat(auth): add JWT refresh token support
|
|
fix(api): handle null response from payments endpoint
|
|
chore: update dependencies to latest versions
|
|
```
|
|
|
|
Rules:
|
|
- Use lowercase for the type and description
|
|
- Keep the description concise (under 72 characters)
|
|
- Do not end the description with a period
|
|
- Commit after each discrete, coherent change — do not wait until the end of a task
|
|
|
|
<!-- context7 -->
|
|
Use Context7 MCP to fetch current documentation whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service -- even well-known ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This includes API syntax, configuration, version migration, library-specific debugging, setup instructions, and CLI tool usage. Use even when you think you know the answer -- your training data may not reflect recent changes. Prefer this over web search for library docs.
|
|
|
|
Do not use for: refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts.
|
|
|
|
## Steps
|
|
|
|
1. Always start with `resolve-library-id` using the library name and the user's question, unless the user provides an exact library ID in `/org/project` format
|
|
2. Pick the best match (ID format: `/org/project`) by: exact name match, description relevance, code snippet count, source reputation (High/Medium preferred), and benchmark score (higher is better). If results don't look right, try alternate names or queries (e.g., "next.js" not "nextjs", or rephrase the question). Use version-specific IDs when the user mentions a version
|
|
3. `query-docs` with the selected library ID and the user's full question (not single words)
|
|
4. Answer using the fetched docs
|
|
<!-- context7 -->
|