AgentList
Submit

Sign in to AgentList

Use a passkey — no password, no email.

AgentList

Canonical directory of AI skills, agent configs, and paid agent services — ranked by the community and exposed for agents to ingest.

HTML directory agents.txt llms.txt auth.md

Lightning Invoice

Scan with any Lightning wallet to pay.

Baseline Coding Agent

A base for software teams building across projects, it aims to improve readability, reviewability of code outputs and the delight of your colleagues. The file is minimal enough to not waste tokens while still capturing the most essential parts of making everybody's life easier. Best saved at a user level (~/.claude (rename to CLAUDE.md), ~/.opencode etc). Project AGENT.md files can still exist on a project level and will also be considered.

Category: agent  Author: npub1carj2jw…h8c9  Date: 2 Apr 2026  Votes: 1

# AGENTS.md

> Code standards for humans and agents. Applies to all languages and projects.

## Code reuse

There is very often an already existing project that has deployment files, frameworks in place that will mirror a new project. When creating greenfield code, ask the user on what other project to base the framework on - not essential but highly recommended.

## Code Clarity

Write code that reads like well-written prose. Names should reveal intent -- if you need a comment to explain *what* code does, rename things until you don't. A straightforward `if/else` that a new team member reads in one pass beats a ternary chain that saves two lines. Optimize for the reader and the reviewer, not the writer.

## Comments

Comments explain *why*, never *what*. If the "what" is even remotely unclear, that's a signal to improve the code itself -- better names, smaller functions, clearer structure. Reserve comments for: business rules, non-obvious constraints, workarounds for known issues, and "this looks wrong but is intentional because..." situations. Delete comments that restate the code.

```python
# Bad: restates the code
user_count = len(users)  # get the number of users

# Good: explains a non-obvious business rule
# Stripe webhooks can arrive out of order, so we always
# re-fetch the subscription state rather than trusting the event payload.
subscription = stripe.Subscription.retrieve(event.subscription_id)
```

## Planning & Abstraction

Before writing code, for anything non-trivial, make a plan. Save it in a planning document for large features, or in the context for small features. The purpose behind large features plan documents is so that bug fixing immediately after implementing becommes easier. Abstract where it genuinely helps shared logic, repeated patterns, clear interfaces, but every abstraction decision should be made with readability as the primary constraint. If an abstraction makes the code harder to follow for a developer reading it cold or a reviewer scanning a diff, inline it. Code that is easy to read is easy to trust.

## Configuration & Environment

Never fall back to default values for environment variables. If a config value is required, fail immediately at startup when it's missing. Silent defaults mask misconfiguration across environments. a loud crash on boot is always better than a subtle bug in production at 2am. Every environment should be explicitly configured, and missing config should be impossible to accidentally deploy.

```python
# Wrong: silently uses a default that may be wrong per environment
db_url = os.getenv("DATABASE_URL", "sqlite:///local.db")

# Right: fails fast with a clear message
db_url = os.environ["DATABASE_URL"]
```

## Error Handling

Errors should be loud, not silent. Never swallow exceptions. If you catch one, either handle it meaningfully or re-raise it. Prefer early returns and guard clauses over deeply nested conditionals.

```javascript
// Wrong
try { await save(data) } catch (e) { /* ignore */ }

// Right
try {
  await save(data);
} catch (error) {
  logger.error("Failed to save record", { error, data });
  throw error;
}
```

## Testing

Test behavior, not implementation. A good test describes what the system does from the outside; a bad test asserts which internal methods were called. If you can refactor internals without breaking tests, your tests are correct. If a refactor breaks tests but not behavior, your tests are wrong.

## Git Workflow

<!-- Requires a project Justfile with dev/merge/promote recipes. -->

Trunk-based development. Branch from `qa` using `just dev <name>`, PR back to `qa` with `gh pr create -B qa`. Every PR requires at least one approval before merge. Merges are fast-forward only (`just merge-qa`) -- rebase if your branch falls behind. Promotion to staging and production happens via `just promote-staging` and `just promote-production`, each requiring its own reviewed PR.